regstr/ciphering_explain_e.js

JSON.stringify objects with RegExp properties and then JSON.parse json string resulted back into original objects. Converts RegExp object to be serializable - into pair of strings (key,value). Could be used for RegExp being bilaterally stringified and ge

(function () {
  var cE, h, o, v;
  //ciphering_explain
  console.log('\n' +
    '  Package <regStr>\n' +
    ' (serialisation of objects and arrays containing regular expression objects.\n' +
    '  JSON-stringify-parse compatable)\n' +
    '\n' +
    ' Converts single RegExp object or some object with RegExp properties\n' +
    ' to the form adequate to stringify and back parse them using JSON\n' +
    ' by means of JSON.stringify and then JSON.parse back.)\n' +
    '\n' +
    '          ----- Ciphering or convertion  ------\n' +
    '\n' +
    ' The main concept is to cipher RegExp object into \'cipher\' pair of strings\n' +
    ' or cipher object - single property object, easily stringifiable,\n' +
    ' and automatically recognisable after back parsing to get "initial"\n' +
    ' object contained RegExp-s.\n' +
    ' The easiest way to get acquaintance with module is to look at examples:\n' +
    '\n' +
    ' Loading handler from working directory ( using variable - h presuming\n' +
    ' that module is a handler. regstr or any yourVar would be OK as well):\n\n' +
    '        var h=require(\'./regstr\').regStr;\n');
  regstr = require('./regstr').regStr;
  console.log('' +
    '\n' +
    ' ciphering is provided by method h.streger() , like this:\n' +
    '\n' +
    '        var v=/asdf/gi;\n'
  );
  v = /asdf/gi;
  console.log(v);
  console.log('' +
    '\n' +
    '        h.streger( v ) or  h.streger(/asdf/gi)\n' +
    ' gives\n'
  );
  console.log(regstr.streger(v));
  console.log('' +
    '\n or an object\n\n' +
    '        var o={a:/asdf/gim};\n' +
    '\n' +
    '        h.streger(o) or  h.streger( {a:/asdf/gim} )\n\n' +
    ' gives\n');
  o = {
    a: /asdf/gim
  };
  console.log(regstr.streger(o));
  console.log('' +
    '\n or an object inside an array\n\n' +
    '       h.streger( [ {a:/asdf/gi},/^[+]+cc.*$/gim ] );\n' +
    '\n' +
    ' returns\n'
  );
  console.log(
    regstr.streger([{
      a: /asdf/gi
    }, /^[+]+cc.*$/gim])
  );
  console.log('' +
    '\n' +
    'or array with RegExp objects elements \n\n' +
    '       h.streger( [\n' +
    '                    /asdf/gi,\n' +
    '                    /^[+]+cc.*$/gim,\n' +
    '                    /sdf/\n' +
    '                  ]\n' +
    '                );\n' +
    '\n');
  console.log(
    regstr.streger([
      /asdf/gi,
      /^[+]+cc.*$/gim,
      /sdf/
    ]));

  console.log('' +
    'or object with RegExp objects properties \n\n' +
    '       h.streger(\n' +
    '                  { a: /asdf/gi,\n' +
    '                    b: /^[+]+cc.*$/gim,\n' +
    '                    ab:[{ bb:/sdfg/mg},/sdf/]\n' +
    '                  }\n' +
    '                 );\n' +
    '\n');
  console.log(
    regstr.streger({
      a: /asdf/gi,
      b: /^[+]+cc.*$/gim,
      ab: [{
        bb: /sdfg/mg
      }, /sdf/]
    }));
  console.log('' +
    ' all these results are easily stringified and back parsed by\n' +
    ' JSON.stringify and JSON.parse\n' +
    ' after parsing applying h.reger() method will bring RegEpx:\n' +
    ' keeping in mind the process flow\n\n' +
    '              ciphering                 deciphering\n' +
    '     RegExp > h.streger > cipherObject >  h.reger  > RegExp\n' +
    '\n' +
    '      h.reger(  h.streger({ a: /asdf/gi,\n' +
    '                            b: /^[+]+cc.*$/gim,\n' +
    '                            ab:[{ bb:/sdfg/mg},/sdf/] } )\n' +
    '              );\n' +
    ' gives:\n'
  );
  console.log(
    regstr.reger(regstr.streger({
      a: /asdf/gi,
      b: /^[+]+cc.*$/gim,
      ab: [{
        bb: /sdfg/mg
      }, /sdf/]
    })));
  console.log('' +
    ' In strings representing keys and values ciphered you already could\n' +
    ' observed the letters \'RE\' and few (two) digits after it. This a mark\n' +
    ' using in ciphering and identification ciphered regExp later. Digits are\n' +
    ' random and their number could be changed by property h.nMin. For example\n' +
    ' let\'s set it to 5.\n' +
    ' h.nMin=5;\n\n' +
    ' and the lay out of key and value strings will have changed. For ex.:\n' +
    '       h.streger(  { a: /asdf/gi,\n' +
    '                     b: /^[+]+cc.*$/gim,\n' +
    '                     ab:[{ bb:/sdfg/mg},/sdf/],\n' +
    '                     c:{re:/nnn.+$/gim,ar:[/aaa/,/bbb/g]} \n' +
    '                   }\n' +
    '                 );\n' +
    ' returns: \n');
  regstr.nMin = 5;
  console.log(
    regstr.streger({
      a: /asdf/gi,
      b: /^[+]+cc.*$/gim,
      ab: [{
        bb: /sdfg/mg
      }, /sdf/],
      c: {
        re: /nnn.+$/gim,
        ar: [/aaa/, /bbb/g]
      }
    }));
  regstr.nMin = 2;
  console.log('\n' +
    ' The explanation regarding REn follows bellow. Here we just mention\n' +
    ' that during deciphering different key-vlalue pairs ciphering different\n' +
    ' regexp-s could have different number of that random digits after \'RE\'' +
    '\n\n' +
    ' like this: \n\n' +
    ' var b=[ { aRE28: \'asdfRE28gi\' },' +
    ' { \'1RE62555\': \'^[+]+cc.*$RE62555gmi\' } ]\n\n' +
    ' h.reger( b);  will return \n');

  var b = [{
    aRE28: 'asdfRE28gi'
  }, {
    "1RE62555": "^[+]+cc.*$RE62555gmi"
  }];
  console.log(regstr.reger(b));
  console.log('' +
    '\n' +
    ' Handler h (regstr) has h.replacer and h.reviver \n' +
    ' methods that could be used to serialise and parse back objects and \n' +
    ' arrays with RegExp-s without\n' +
    ' direct intermediary of h.streger(...) and h.reger(...).\n' +
    ' functions could be used \n' +
    '        var replacer = h.replacer.bind(h);\n' +
    '        var reviver = h.reviver.bind(h);\n' +
    ' and\n' +
    '     o -> o1 = JSON.stringify(o,replacer) ->\n' +
    '          o  =     JSON.parse(o1,reviver)\n' +
    ' compare o \n');
  o = [{
    a: /asdf/gi
  }, /^[+]+cc.*$/gim];
  console.log(o);

  console.log('\n' +
    'with\n' +
    '\n' +
    '     o=JSON.parse ( JSON.stringify(o,h.replacer.bind(h)), h.reviver.bind(h))\n' +
    ' or\n' +
    '     o=JSON.parse ( JSON.stringify(o,replacer), reviver)\n' +
    '\n');

  var replacer = regstr.replacer.bind(regstr);
  var reviver = regstr.reviver.bind(regstr);
  console.log(JSON.parse(JSON.stringify(o, replacer), reviver));
  console.log('\n' +
    'and with\n' +
    '     h.reger( h.streger([{a:/asdf/gi},/^[+]+cc.*$/gim]) );\n' +
    '\n');
  console.log(regstr.reger(regstr.streger([{
    a: /asdf/gi
  }, /^[+]+cc.*$/gim])));
  console.log('\n' +
    '\n' +
    ' Explanation:\n' +
    ' Let\'s pO is some parent object with a property described by\n' +
    ' (key,value) pair, where\n' +
    '\n' +
    '   value=pO[key]; // and value is regular expression object\n' +
    '   (value instanceof RegExp===true)?true:false; // is true and\n' +
    '\n' +
    '   value=new RegExp(body,mig); //  where  body and mig are strings\n' +
    '\n' +
    '  {string}body - is  string of regular expression and\n' +
    '  {string}mig - RegExp flags -  ( multiline, insencitive, global)\n' +
    '\n' +
    ' Conversion algorithm fitures:\n' +
    ' 1. Additional property key1 is added to object pO -\n' +
    '\n' +
    '   pO[key1]=value1;\n' +
    '   key1=key+RE;    //value=new RegExp(body,mig) are converted into string\n' +
    '   value1=body+RE+mig; // where\n' +
    '   RE=\'RE\'+rndm10;\n' +
    '\n' +
    '   and {string}rndm10 is random string consisted of 10 random digits\n' +
    '   from 0-9 in each place, for ex.\n' +
    '   rndm10=\'0987654321\'; //\n' +
    '\n' +
    ' The number of random digit depends and could be any of your choise\n' +
    ' rndm4, ..rndm2 ...\n' +
    ' Obviousely pO[key1] is serializable by JSON.\n' +
    ' 2. Or\n' +
    '   delete pO[key];\n' +
    ' or if you would not have done it yourself the JSON.stringify will do\n' +
    ' during serialization\n' +
    '\n' +
    ' Inclusion of RE string into key1 and value1 is used as a mark\n' +
    ' marking the property and permits to identify it during reverse\n' +
    ' parse procedure and to transform\n' +
    ' value1 string  body+RE+mig into new RegExp(body,mig) :\n' +
    ' Back Parsing fitures:\n' +
    ' After JSON.parse( regExpJsoned )\n' +
    ' 1. Selects object string property containing in key and value\n' +
    ' marking string RE===\'RE\'+rndmN ,\n' +
    ' where N is number of digital positions in random rndmN N-digital string.\n' +
    ' RE populates the ending positions of key( property name string) and\n' +
    ' separates body-part from mig-part in property string value===body+RE+mig, so\n' +
    '\n' +
    ' var vs=pO[oid+RE].split(RE);                   //   (5)\n' +
    ' var newRegExpValue= new RegExp( vs[0],vs[1]);  //   (6)\n' +
    '\n' +
    ' when you would be need to get RE you should look for a property\n' +
    ' with string value, in (key,value) pair :\n' +
    ' and\n' +
    ' 1. property name and property string value contain the same pattern RE\n' +
    ' 2. the property name has it located at the end of string\n' +
    ' 3. the value string consists of three parts: body,RE and mig\n' +
    ' splitting the valueString by RE pattern body and mig -parts could be got\n' +
    ' and therefor RegExp value be invoked\n' +
    '\n' +
    ' Package Usage for pO object:\n' +
    '\n' +
    ' var regstr=require(\'regstr).regStr; // handler object\n' +
    '\n' +
    ' variant A.\n' +
    ' RegExp property conversions into string:\n' +
    ' For each property being RegExp new converted string property\n' +
    ' is created. Original ones keep safe.( are not deleted from object\n' +
    ' if it\'s necessary do it yourself or use optional parameter ciphMode_opt\n' +
    ' to manage this option)\n' +
    '\n' +
    ' pO=regstr.streger(pO);     // Remark: changes of pO properties are accessible\n' +
    '                             // for external scope of stregger. Possible call is\n' +
    '                             // regstr.streger(pO);\n' +
    '\n' +
    ' variant B.\n' +
    ' per single RegExp property transfromation\n' +
    '\n' +
    ' var o;\n' +
    ' // preJson step\n' +
    ' for(var k in pO){\n' +
    '	if( pO[k] instanceof RegExp){\n' +
    '	  o=regstr.reStr(pO[k],k);\n' +
    '     // creates new property with new key and value {string}\n' +
    '     pO[o.ky]=o.v;\n' +
    '   }\n' +
    ' }\n' +
    ' // json.stringify\n' +
    ' var jsonPo=JSON.stringify(pO)\n' +
    '\n' +
    ' // parse Back\n' +
    '\n' +
    ' detailed explanation see in deciphering_explain.txt of deciphering_explain.js-object\n' +
    ' in docs directory.\n' +
    ' to get it in console type: npm run explain\n' +
    ' or inside node by require(\'./docs.deciphering_explain.js\'); command\n' +
    '\n' +
    ' var oP=JSON.parse(jsonPo);\n' +
    '\n' +
    ' postParse properties\' conversion into RegExp-s if any\n' +
    ' variant 1.\n' +
    ' All chypered property if are avalable are selected\n' +
    ' and are converted to RegExp with new keys (by excluding RE from key):\n' +
    '\n' +
    ' oP=regstr.reger(oP);\n' +
    '\n' +
    ' // or Variant 2\n' +
    ' // if \'property by property\' handling is necessary\n' +
    ' var ob;\n' +
    ' for( var ip in oP){\n' +
    '	if( typeof oP[ip]===\'string\'){\n' +
    '	  ob=regstr.regUp(oP[ip]);\n' +
    '     if(ob.key!==ip){\n' +
    '     // new RegExp property of oP\n' +
    '	    ob[ob.key]=ob.value;\n' +
    '       delete oP[ip];\n' +
    '   }\n' +
    '   }\n' +
    ' }\n' +
    ' Remark 1.\n' +
    ' RegExp object variable itself could be converted into\n' +
    ' object whith one property {RE:regString}\n' +
    ' var regE=someRegExp;  // someRegExp=new RegExp(body,mig);\n' +
    ' var oStrReg=regstr.reStr(regE);\n' +
    ' // var o=oStrReg.o();  where o={ RE: regString } where\n' +
    ' // RE=\'RE\'+rndmN , regString = body+RE+mig,\n' +
    ' // at the same time RE=oStrReg.re;\n' +
    ' //                  regString=oStrReg.c;\n' +
    ' //                  body=oStrReg.b;\n' +
    ' //                  mig=oStrReg.mig\n' +
    ' //\n' +
    ' Remark 2.\n' +
    ' uncycle package extention. (miss it now, go further up to Deciphering\n' +
    ' model explanation.)\n' +
    '\n' +
    ' This RegExp handling algorithm could be included in preStringify methods\n' +
    ' of <uncycle> package -targeting to stringify objects with circular references\n' +
    ' to provide extending functionality, or when json is used for cloning objects.\n' +
    ' to switch it on set\n' +
    ' unCycle.uiDirect.regOn=true;\n' +
    '\n' +
    ' .................................\n' +
    ' Following comments are based on notion of uncycle package.\n' +
    ' suppose some ith-property  with (oid,uid,value) being RegExp\n' +
    ' oid=\'oid\'; // property\'s object id or key\n' +
    ' uid=\'##x#x#...#oid\';  // appropriate universal identifyer of this property\n' +
    '\n' +
    ' If pO is this property\'s parent object,\n' +
    ' property\'s value is RegExp object\n' +
    '\n' +
    '  pO[oid]=new RegExp(body,mig);                //    (1)    {RegExp}\n' +
    '  unCycle.uiDirect[uid]=new RegExp(body,mig);  //    (2)    {RegExp}\n' +
    '\n' +
    ' to create new property for parent object with string value:\n' +
    '    pO[oid+RE]=body+RE+mig;                    //    (3)    {string}\n' +
    '         where RE=\'RE\'+rndm10\n' +
    '         and\n' +
    '    rndm10=\'0987654321\'; //-random string of 10 digits from 0-9 in each place\n' +
    '    The number of random digit depends and could be any of your choise\n' +
    '    rndm4, ..rendm2 ...\n' +
    '\n' +
    '\n' +
    ' 2. delete pO[oid];      // if you would no have done it yourself\n' +
    '                         // JSON.stringify will not do it but only\n' +
    '                         // would set empty appropriate object\n' +
    ' 3. appropriately, the uid of this new property will be\n' +
    '       uidNewPr=uid+RE;    // {string} and uiDirect object will contain property\n' +
    '       unCycle.uiDirect[uid+RE]=body+RE+mig;   //    (4)     {string}\n' +
    '\n' +
    ' Inclusion of RE string into oid and string value of newly created property\n' +
    ' simplifies it\'s identification and following transformation of\n' +
    ' body+RE+mig string into new RegExp(body,mig) :\n' +
    '\n' +
    ' var vs=pO[oid+RE].split(RE);                   //   (5)\n' +
    ' var newRegExpValue= new RegExp( vs[0],vs[1]);  //   (6)\n' +
    '\n' +
    ' when you would be need to get RE you should look for a property\n' +
    ' with string value, i.e.  for (key,value) :\n' +
    '\n' +
    '	 (typeof value === \'string\') &&  three remarkable points:\n' +
    ' 1. For newly created property - property name and\n' +
    ' property string ciphered value contain the same pattern RE\n' +
    ' 2. the property name has it at the end of string\n' +
    ' 3. the value\'s body and mig string could be obtained splitting the\n' +
    '    valueString by RE pattern\n' +
    ' ...........................................\n' +
    '\n');
}());