params.json

{"name":"jpcre2","tagline":"C++ wrapper of PCRE2 library","body":"#C++ wrapper for several utilities of PCRE2 Library\r\n\r\nPCRE2 is the name used for a revised API for the PCRE library, which is a set of functions, written in C, that implement regular expression pattern matching using the same syntax and semantics as Perl, with just a few differences. Some features that appeared in Python and the original PCRE before they appeared in Perl are also available using the Python syntax.\r\n\r\nThis provides some C++ wrapper functions to provide some useful utilities like regex match and regex replace.\r\n\r\n#Requirements:\r\n\r\n1. C++ compiler with C++11 support.\r\n2. pcre2 library (`version >=10.21`).\r\n\r\nIf the required `pcre2` version is not available in the official channel, download <a href=\"https://github.com/jpcre2\">my fork of the library from here</a>, Or use <a href=\"https://github.com/jpcre2/pcre2\">this repository</a> which will always be kept compatible with `jpcre2`.\r\n\r\n#How To:\r\n\r\n##How to compile:\r\n\r\n1. `#include` the `jpcre2.hpp` file in your program. \r\n\r\n2. Compile with `pcre2` library linked and c++11 enabled.\r\n\r\n**Example:**\r\n\r\nA simple *mycpp.cpp* file should be compiled with the following command with GCC.\r\n\r\n```sh\r\ng++ -std=c++11 mycpp.cpp -lpcre2-8\r\n```\r\n\r\n`-lpcre1-8` should be changed to the actual library i.e for 16 bit code unit: `-lpcre2-16` and for 32 bit code unit: `-lpcre2-32`.\r\n\r\nIf your `pcre2` library is not in the standard library path, then add the path:\r\n\r\n```sh\r\ng++ -std=c++11 mycpp.cpp -L/path/to/your/pcre2/library -lpcre2-8\r\n```\r\n\r\n**Note that** it requires the `pcre2` library installed in your system. If it is not already installed and linked in your compiler, you will need to link it with appropriate path and options.\r\n\r\n##How to code:\r\n\r\n<ol>\r\n<li>\r\nFirst create a <code>Pcre2Regex</code> object. This object will hold the pattern, modifiers, compiled pattern, error and warning codes.\r\n</li>\r\n  <ol>\r\n<li>Each object for each regex pattern.\r\n</li>\r\n<li>Pattern and modifier can be initialized with constructor (<code>Pcre2Regex(pattern,modifier)</code>) or with member functions <code>setPattern()</code> and <code>setModifier()</code>.\r\nEx:<pre class=\"highlight\"><code class=\"highlight-source-c++ cpp\">\r\nPcre2Regex re(\"\\\\d\\\\w+\",\"Sugi\");   //Initialize pattern and modifier with constructor\r\nre.setPattern(\"\\\\w\\\\S+\");          //This sets the pattern\r\nre.setModifier(\"g\");               //This sets the modifier.\r\n</code></pre>\r\n</li>\r\n<li>\r\nN.B: Every time you change the pattern, you will need to recompile it and every time you change compile modifier, you will need to recompile the pattern to apply the change.\r\n</li>\r\n  </ol>\r\n<li>\r\nCompile the pattern and catch any error exception:\r\n<pre class=\"highlight\"><code class=\"highlight-source-c++ cpp\">\r\ntry{re.compile();}                          //This compiles the previously set pattern and modifier\r\ncatch(int e){/*Handle error*//*std::cout&lt;&lt;re.getErrorMessage(e)&lt;&lt;std::endl;*/}\r\ntry{re.compile(\"pattern\",\"mgi\");}           //This compiles the pattern and modifier provided.\r\ncatch(int e){/*Handle error*//*std::cout&lt;&lt;re.getErrorMessage(e)&lt;&lt;std::endl;*/}\r\n</code></pre>\r\n</li>\r\n<li>\r\nNow you can perform match or replace against the pattern. Use the <code>match()</code> member function to preform regex match and the <code>replace()</code> member function to perform regex replace.\r\n</li>\r\n  <ol>\r\n<li>\r\n<b>Match:</b> The <code>match()</code> member function takes the subject string and some specialized vectors (vectors of maps of substrings) as its arguments and a last argument to tell whether to match all or only the first. It puts the results in the maps of the vectors and returns true on successful match and false otherwise.\r\n</li>\r\n    <ul>\r\n<li>\r\nPerform match and catch any error exception:\r\n<pre class=\"highlight\"><code class=\"highlight-source-c++ cpp\">\r\ntry{re.match(\"I am a subject string\",vec_num);}\r\ncatch(int e){/*Handle error*//*std::cout&lt;&lt;re.getErrorMessage(e)&lt;&lt;std::endl;*/}\r\n//vec_num will be populated with numbered substrings.\r\n</code></pre>\r\nAccess the substrings like this:\r\n<pre class=\"highlight\"><code class=\"highlight-source-c++ cpp\">\r\nfor(int i=0;i&lt;(int)vec_num.size();i++){\r\n    //This loop will iterate only once if find_all is false.\r\n    //i=0 is the first match found, i=1 is the second and so forth\r\n    for(auto const&amp; ent : vec_num[i]){\r\n    //ent.first is the number/position of substring found\r\n    //ent.second is the substring itself\r\n    //when ent.first is 0, ent.second is the total match.\r\n    }\r\n}\r\n</code></pre>\r\n</li>\r\n<li>\r\nOther variations of this function can be used to get named substrings and the position of named substrings. Simply pass the appropriate vectors in the match function:\r\n<pre class=\"highlight\"><code class=\"highlight-source-c++ cpp\">\r\ntry{re.match(\"I am a subject string\",vec_num,vec_nas,vec_nn);}\r\ncatch(int e){/*Handle error*//*std::cout&lt;&lt;re.getErrorMessage(e)&lt;&lt;std::endl;*/}\r\n</code></pre>\r\nAnd access the substrings by looping through the vectors and associated maps. The size of all three vectors are the same and they can be passed in any sequence (i.e the order of the vectors as arguments is not important).\r\n</li>\r\n    </ul>\r\n<li>\r\n<b>Replace:</b> The <code>replace()</code> member function takes the subject string as first argument and replacement string as the second argument and two optional arguments (modifier and the size of the resultant string) and returns the resultant string after performing the replacement operation. If no modifier is passed an empty modifier is assumed.\r\n</li>\r\n    <ul>\r\n<li>\r\nPerform replace and catch any error exception:\r\n<pre class=\"highlight prettyprint\"><code class=\"highlight-source-c++ cpp\">\r\ntry{re.replace(\"replace this string according to the pattern\",\"with this string\",\"mgi\");}\r\ncatch(int e){/*Handle error*//*std::cout&lt;&lt;re.getErrorMessage(e)&lt;&lt;std::endl;*/}\r\n//mgi is the modifier passed (multiline, global, case insensitive).\r\n//Access substrings/captured groups with ${1234},$1234 (for numbered substrings) or ${name} (for named substrings)\r\n</code></pre>\r\n</li>\r\n<li>\r\nIf you pass the size of the resultant string with the replace function, then make sure it will be enough to store the whole resultant replaced string, otherwise the internal replace function (<code>pcre2_substitute()</code>) will be called <i>twice</i> to adjust the size to hold the whole resultant string in order to avoid <code>PCRE2_ERROR_NOMEMORY</code> error. Two consecutive call of the same function may affect overall performance of your code.\r\n</li>\r\n    </ul>\r\n  </ol>\r\n</ol>\r\n\r\n#Insight:\r\n\r\n##Namespaces:\r\n\r\n1. **jpcre2_utils :** Some utility functions used by `jpcre2`.\r\n2. **jpcre2 :** This is the namespace you will be using in your code to access `jpcre2` classes and functions.\r\n\r\n##Classes:\r\n\r\n1. **Pcre2Regex :** This is the main class which holds the key utilities of `jpcre2`. Every regex needs an object of this class.\r\n\r\n##Functions:\r\n\r\n```cpp\r\n\r\nPcre2Regex(){pat_str=\"\";modifier=\"\";mylocale=DEFAULT_LOCALE;}\r\nPcre2Regex(const std::string& re,const std::string& mod=\"\",const std::string& loc=DEFAULT_LOCALE)\r\n{pat_str=re;modifier=mod;mylocale=loc;}\r\n\r\n~Pcre2Regex(){free();}\r\n\r\nvoid parseReplacementOpts(const std::string& mod);\r\nvoid parseCompileOpts(const std::string& mod);\r\nvoid parseOpts(const std::string& mod){parseReplacementOpts(mod);parseCompileOpts(mod);}\r\n\r\nstd::string getModifier(){return modifier;}\r\nvoid setModifier(const std::string& mod){modifier=mod;}\r\n\r\nstd::string getPattern(){return pat_str;}\r\nvoid setPattern(const std::string& pat){pat_str=pat;}\r\n\r\nvoid setLocale(const std::string& loc){mylocale=loc;}   ///Sets LC_CTYPE\r\nstd::string getLocale(){return mylocale;}               ///Gets LC_CTYPE\r\n\r\npcre2_code* getPcreCode(){return code;}                 ///returns address to compiled regex\r\nvoid free(void){pcre2_code_free(code);}                 ///frees memory used for the compiled regex.\r\n\r\n///Compiles the regex.\r\n///If pattern or modifier or both not passed, they will be defaulted to previously set value.\r\nvoid compile(void){compile(pat_str,modifier,mylocale);}\r\nvoid compile(const std::string& re,const std::string& mod,const std::string& loc=DEFAULT_LOCALE);\r\nvoid compile(const std::string& re){compile(re,modifier,mylocale);}\r\n\r\n///returns a replaced string after performing regex replace\r\n///If modifier is not passed it will be defaulted to empty string\r\nstd::string replace( std::string mains, std::string repl,const std::string& mod=\"\",PCRE2_SIZE out_size=REGEX_STRING_MAX);\r\nstd::string replace( std::string mains, std::string repl,size_t out_size){return replace(mains,repl,\"\",out_size);}\r\n\r\n///returns true for successful match, stores the match results in the specified vectors\r\nbool match(const std::string& subject,VecNum& vec_num,VecNas& vec_nas,VecNtN& vec_nn,bool find_all=false);\r\n\r\n///Other variants of match function\r\n///3-vector variants\r\nbool match(const std::string& subject,VecNum& vec_num,VecNtN& vec_nn,VecNas& vec_nas,bool find_all=false);\r\nbool match(const std::string& subject,VecNas& vec_nas,VecNum& vec_num,VecNtN& vec_nn,bool find_all=false);\r\nbool match(const std::string& subject,VecNas& vec_nas,VecNtN& vec_nn,VecNum& vec_num,bool find_all=false);\r\nbool match(const std::string& subject,VecNtN& vec_nn,VecNas& vec_nas,VecNum& vec_num,bool find_all=false);\r\nbool match(const std::string& subject,VecNtN& vec_nn,VecNum& vec_num,VecNas& vec_nas,bool find_all=false);\r\n\r\n///2-vector variants\r\nbool match(const std::string& subject,VecNum& vec_num,VecNas& vec_nas,bool find_all=false);\r\nbool match(const std::string& subject,VecNas& vec_nas,VecNum& vec_num,bool find_all=false);\r\nbool match(const std::string& subject,VecNum& vec_num,VecNtN& vec_nn,bool find_all=false);\r\nbool match(const std::string& subject,VecNtN& vec_nn,VecNum& vec_num,bool find_all=false);\r\nbool match(const std::string& subject,VecNas& vec_nas,VecNtN& vec_nn,bool find_all=false);\r\nbool match(const std::string& subject,VecNtN& vec_nn,VecNas& vec_nas,bool find_all=false);\r\n\r\n///1-vector variants\r\nbool match(const std::string& subject,VecNum& vec_num,bool find_all=false);\r\nbool match(const std::string& subject,VecNas& vec_nas,bool find_all=false);\r\nbool match(const std::string& subject,VecNtN& vec_nn,bool find_all=false);\r\n\r\n///Error handling\r\nstd::string getErrorMessage(int err_num);\r\nstd::string getErrorMessage();\r\nstd::string getWarningMessage(){return current_warning_msg;}\r\nint getErrorNumber(){return error_number;}\r\nint getErrorCode(){return error_code;}\r\nPCRE2_SIZE getErrorOffset(){return error_offset;}\r\n```\r\n\r\n\r\n#Testing:\r\n\r\n1. **test.cpp**: Contains an example code for match and replace function.\r\n2. **test_match.cpp**: Contains an example code for match function.\r\n3. **test_replace.cpp**: Contains an example code for replace function.\r\n\r\n#Screenshots of some test outputs:\r\n\r\ntest_match:\r\n----------\r\n\r\n![jpcre2 screenshot1](img/s1_1.png)\r\n![jpcre2 screenshot2](img/s1_2.png)\r\n![jpcre2 screenshot3](img/s1_3.png)\r\n![jpcre2 screenshot4](img/s1_4.png)\r\n\r\ntest_replace:\r\n-------------\r\n\r\n![jpcre2 screenshot5](img/s2_1.png)\r\n\r\n","google":"","note":"Don't delete this file! It's used internally to help with page regeneration."}