"Fossies" - the Fresh Open Source Software Archive

Member "opensips-3.0.1/modules/regex/README" (1 Oct 2019, 12611 Bytes) of package /linux/misc/opensips-3.0.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 3.0.0_vs_3.0.1.

    1 Regex Module
    2      __________________________________________________________
    3 
    4    Table of Contents
    5 
    6    1. Admin Guide
    7 
    8         1.1. Overview
    9         1.2. Dependencies
   10 
   11               1.2.1. OpenSIPS Modules
   12               1.2.2. External Libraries or Applications
   13 
   14         1.3. Exported Parameters
   15 
   16               1.3.1. file (string)
   17               1.3.2. max_groups (int)
   18               1.3.3. group_max_size (int)
   19               1.3.4. pcre_caseless (int)
   20               1.3.5. pcre_multiline (int)
   21               1.3.6. pcre_dotall (int)
   22               1.3.7. pcre_extended (int)
   23 
   24         1.4. Exported Functions
   25 
   26               1.4.1. pcre_match (string, pcre_regex)
   27               1.4.2. pcre_match_group (string [, group])
   28 
   29         1.5. Exported MI Functions
   30 
   31               1.5.1. regex_reload
   32 
   33         1.6. Installation and Running
   34 
   35               1.6.1. File format
   36 
   37    2. Contributors
   38 
   39         2.1. By Commit Statistics
   40         2.2. By Commit Activity
   41 
   42    3. Documentation
   43 
   44         3.1. Contributors
   45 
   46    List of Tables
   47 
   48    2.1. Top contributors by DevScore^(1), authored commits^(2) and
   49           lines added/removed^(3)
   50 
   51    2.2. Most recently active contributors^(1) to this module
   52 
   53    List of Examples
   54 
   55    1.1. Set file parameter
   56    1.2. Set max_groups parameter
   57    1.3. Set group_max_size parameter
   58    1.4. Set pcre_caseless parameter
   59    1.5. Set pcre_multiline parameter
   60    1.6. Set pcre_dotall parameter
   61    1.7. Set pcre_extended parameter
   62    1.8. pcre_match usage (forcing case insensitive)
   63    1.9. pcre_match usage (using "end of line" symbol)
   64    1.10. pcre_match_group usage
   65    1.11. regex file
   66    1.12. Using with pua_usrloc
   67    1.13. Incorrect groups file
   68 
   69 Chapter 1. Admin Guide
   70 
   71 1.1. Overview
   72 
   73    This module offers matching operations against regular
   74    expressions using the powerful PCRE library.
   75 
   76    A text file containing regular expressions categorized in
   77    groups is compiled when the module is loaded, storing the
   78    compiled PCRE objects in an array. A function to match a string
   79    or pseudo-variable against any of these groups is provided. The
   80    text file can be modified and reloaded at any time via a MI
   81    command. The module also offers a function to perform a PCRE
   82    matching operation against a regular expression provided as
   83    function parameter.
   84 
   85    For a detailed list of PCRE features read the man page of the
   86    library.
   87 
   88 1.2. Dependencies
   89 
   90 1.2.1. OpenSIPS Modules
   91 
   92    The following modules must be loaded before this module:
   93      * No dependencies on other OpenSIPS modules.
   94 
   95 1.2.2. External Libraries or Applications
   96 
   97    The following libraries or applications must be installed
   98    before running OpenSIPS with this module loaded:
   99      * libpcre-dev - the development libraries of PCRE.
  100 
  101 1.3. Exported Parameters
  102 
  103 1.3.1. file (string)
  104 
  105    Text file containing the regular expression groups. It must be
  106    set in order to enable the group matching function.
  107 
  108    Default value is “NULL”.
  109 
  110    Example 1.1. Set file parameter
  111 ...
  112 modparam("regex", "file", "/etc/opensips/regex_groups")
  113 ...
  114 
  115 1.3.2. max_groups (int)
  116 
  117    Max number of regular expression groups in the text file.
  118 
  119    Default value is “20”.
  120 
  121    Example 1.2. Set max_groups parameter
  122 ...
  123 modparam("regex", "max_groups", 40)
  124 ...
  125 
  126 1.3.3. group_max_size (int)
  127 
  128    Max content size of a group in the text file.
  129 
  130    Default value is “8192”.
  131 
  132    Example 1.3. Set group_max_size parameter
  133 ...
  134 modparam("regex", "group_max_size", 16384)
  135 ...
  136 
  137 1.3.4. pcre_caseless (int)
  138 
  139    If this options is set, matching is done caseless. It is
  140    equivalent to Perl's /i option, and it can be changed within a
  141    pattern by a (?i) or (?-i) option setting.
  142 
  143    Default value is “0”.
  144 
  145    Example 1.4. Set pcre_caseless parameter
  146 ...
  147 modparam("regex", "pcre_caseless", 1)
  148 ...
  149 
  150 1.3.5. pcre_multiline (int)
  151 
  152    By default, PCRE treats the subject string as consisting of a
  153    single line of characters (even if it actually contains
  154    newlines). The "start of line" metacharacter (^) matches only
  155    at the start of the string, while the "end of line"
  156    metacharacter ($) matches only at the end of the string, or
  157    before a terminating newline.
  158 
  159    When this option is set, the "start of line" and "end of line"
  160    constructs match immediately following or immediately before
  161    internal newlines in the subject string, respectively, as well
  162    as at the very start and end. This is equivalent to Perl's /m
  163    option, and it can be changed within a pattern by a (?m) or
  164    (?-m) option setting. If there are no newlines in a subject
  165    string, or no occurrences of ^ or $ in a pattern, setting this
  166    option has no effect.
  167 
  168    Default value is “0”.
  169 
  170    Example 1.5. Set pcre_multiline parameter
  171 ...
  172 modparam("regex", "pcre_multiline", 1)
  173 ...
  174 
  175 1.3.6. pcre_dotall (int)
  176 
  177    If this option is set, a dot metacharater in the pattern
  178    matches all characters, including those that indicate newline.
  179    Without it, a dot does not match when the current position is
  180    at a newline. This option is equivalent to Perl's /s option,
  181    and it can be changed within a pattern by a (?s) or (?-s)
  182    option setting.
  183 
  184    Default value is “0”.
  185 
  186    Example 1.6. Set pcre_dotall parameter
  187 ...
  188 modparam("regex", "pcre_dotall", 1)
  189 ...
  190 
  191 1.3.7. pcre_extended (int)
  192 
  193    If this option is set, whitespace data characters in the
  194    pattern are totally ignored except when escaped or inside a
  195    character class. Whitespace does not include the VT character
  196    (code 11). In addition, characters between an unescaped #
  197    outside a character class and the next newline, inclusive, are
  198    also ignored. This is equivalent to Perl's /x option, and it
  199    can be changed within a pattern by a (?x) or (?-x) option
  200    setting.
  201 
  202    Default value is “0”.
  203 
  204    Example 1.7. Set pcre_extended parameter
  205 ...
  206 modparam("regex", "pcre_extended", 1)
  207 ...
  208 
  209 1.4. Exported Functions
  210 
  211 1.4.1.  pcre_match (string, pcre_regex)
  212 
  213    Matches the given string parameter against the regular
  214    expression pcre_regex, which is compiled into a PCRE object.
  215    Returns TRUE if it matches, FALSE otherwise.
  216 
  217    Meaning of the parameters is as follows:
  218      * string - String to compare.
  219      * pcre_regex (string) - Regular expression to be compiled in
  220        a PCRE object.
  221 
  222    NOTE: To use the "end of line" symbol '$' in the pcre_regex
  223    parameter use '$$'.
  224 
  225    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
  226    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  227 
  228    Example 1.8.  pcre_match usage (forcing case insensitive)
  229 ...
  230 if (pcre_match("$ua", "(?i)^twinkle")) {
  231     xlog("L_INFO", "User-Agent matches\n");
  232 }
  233 ...
  234 
  235    Example 1.9.  pcre_match usage (using "end of line" symbol)
  236 ...
  237 if (pcre_match($rU, "^user[1234]$$")) {  # Will be converted to "^user[1
  238 234]$"
  239     xlog("L_INFO", "RURI username matches\n");
  240 }
  241 ...
  242 
  243 1.4.2.  pcre_match_group (string [, group])
  244 
  245    It uses the groups readed from the text file (see
  246    Section 1.6.1, “File format”) to match the given string
  247    parameter against the compiled regular expression in group
  248    number group. Returns TRUE if it matches, FALSE otherwise.
  249 
  250    Meaning of the parameters is as follows:
  251      * string - String to compare.
  252      * group (int) - group to use in the operation. If not
  253        specified then 0 (the first group) is used.
  254 
  255    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
  256    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  257 
  258    Example 1.10.  pcre_match_group usage
  259 ...
  260 if (pcre_match_group($rU, 2)) {
  261     xlog("L_INFO", "RURI username matches group 2\n");
  262 }
  263 ...
  264 
  265 1.5. Exported MI Functions
  266 
  267 1.5.1.  regex_reload
  268 
  269    Causes regex module to re-read the content of the text file and
  270    re-compile the regular expressions. The number of groups in the
  271    file can be modified safely.
  272 
  273    Name: regex_reload
  274 
  275    Parameters: none
  276 
  277    MI FIFO Command Format:
  278 opensips-cli -x mi regex_reload
  279 
  280 1.6. Installation and Running
  281 
  282 1.6.1. File format
  283 
  284    The file contains regular expressions categorized in groups.
  285    Each group starts with "[number]" line. Lines starting by
  286    space, tab, CR, LF or # (comments) are ignored. Each regular
  287    expression must take up just one line, this means that a
  288    regular expression can't be splitted in various lines.
  289 
  290    An example of the file format would be the following:
  291 
  292    Example 1.11. regex file
  293 ### List of User-Agents publishing presence status
  294 [0]
  295 
  296 # Softphones
  297 ^Twinkle/1
  298 ^X-Lite
  299 ^eyeBeam
  300 ^Bria
  301 ^SIP Communicator
  302 ^Linphone
  303 
  304 # Deskphones
  305 ^Snom
  306 
  307 # Others
  308 ^SIPp
  309 ^PJSUA
  310 
  311 
  312 ### Blacklisted source IP's
  313 [1]
  314 
  315 ^190\.232\.250\.226$
  316 ^122\.5\.27\.125$
  317 ^86\.92\.112\.
  318 
  319 
  320 ### Free PSTN destinations in Spain
  321 [2]
  322 
  323 ^1\d{3}$
  324 ^((\+|00)34)?900\d{6}$
  325 
  326    The module compiles the text above to the following regular
  327    expressions:
  328 group 0: ((^Twinkle/1)|(^X-Lite)|(^eyeBeam)|(^Bria)|(^SIP Communicator)|
  329           (^Linphone)|(^Snom)|(^SIPp)|(^PJSUA))
  330 group 1: ((^190\.232\.250\.226$)|(^122\.5\.27\.125$)|(^86\.92\.112\.))
  331 group 2: ((^1\d{3}$)|(^((\+|00)34)?900\d{6}$))
  332 
  333    The first group can be used to avoid auto-generated PUBLISH
  334    (pua_usrloc module) for UA's already supporting presence:
  335 
  336    Example 1.12. Using with pua_usrloc
  337 route[REGISTER] {
  338     if (! pcre_match_group("$ua", 0)) {
  339         xlog("L_INFO", "Auto-generated PUBLISH for $fu ($ua)\n");
  340         pua_set_publish();
  341     }
  342     save("location");
  343     exit;
  344 }
  345 
  346    NOTE: It's important to understand that the numbers in each
  347    group header ([number]) must start by 0. If not, the real group
  348    number will not match the number appearing in the file. For
  349    example, the following text file:
  350 
  351    Example 1.13. Incorrect groups file
  352 [1]
  353 ^aaa
  354 ^bbb
  355 
  356 [2]
  357 ^ccc
  358 ^ddd
  359 
  360    will generate the following regular expressions:
  361 group 0: ((^aaa)|(^bbb))
  362 group 1: ((^ccc)|(^ddd))
  363 
  364    Note that the real index doesn't match the group number in the
  365    file. This is, compiled group 0 always points to the first
  366    group in the file, regardless of its number in the file. In
  367    fact, the group number appearing in the file is used for
  368    nothing but for delimiting different groups.
  369 
  370    NOTE: A line containing a regular expression cannot start by
  371    '[' since it would be treated as a new group. The same for
  372    lines starting by space, tab, or '#' (they would be ignored by
  373    the parser). As a workaround, using brackets would work:
  374 [0]
  375 ([0-9]{9})
  376 ( #abcde)
  377 ( qwerty)
  378 
  379 Chapter 2. Contributors
  380 
  381 2.1. By Commit Statistics
  382 
  383    Table 2.1. Top contributors by DevScore^(1), authored
  384    commits^(2) and lines added/removed^(3)
  385      Name DevScore Commits Lines ++ Lines --
  386    1. Iñaki Baz Castillo 14 3 1242 2
  387    2. Razvan Crainea (@razvancrainea) 13 11 41 24
  388    3. Liviu Chircu (@liviuchircu) 12 10 25 42
  389    4. Vlad Patrascu (@rvlad-patrascu) 9 6 63 88
  390    5. Bogdan-Andrei Iancu (@bogdan-iancu) 8 6 12 7
  391    6. Sergio Gutierrez 3 1 19 1
  392    7. Ovidiu Sas (@ovidiusas) 3 1 13 11
  393    8. Anca Vamanu 3 1 6 3
  394    9. Marius Zbihlei 2 1 2 0
  395 
  396    (1) DevScore = author_commits + author_lines_added /
  397    (project_lines_added / project_commits) + author_lines_deleted
  398    / (project_lines_deleted / project_commits)
  399 
  400    (2) including any documentation-related commits, excluding
  401    merge commits. Regarding imported patches/code, we do our best
  402    to count the work on behalf of the proper owner, as per the
  403    "fix_authors" and "mod_renames" arrays in
  404    opensips/doc/build-contrib.sh. If you identify any
  405    patches/commits which do not get properly attributed to you,
  406    please submit a pull request which extends "fix_authors" and/or
  407    "mod_renames".
  408 
  409    (3) ignoring whitespace edits, renamed files and auto-generated
  410    files
  411 
  412 2.2. By Commit Activity
  413 
  414    Table 2.2. Most recently active contributors^(1) to this module
  415                      Name                   Commit Activity
  416    1. Razvan Crainea (@razvancrainea)     Sep 2011 - Sep 2019
  417    2. Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
  418    3. Bogdan-Andrei Iancu (@bogdan-iancu) Feb 2009 - Apr 2019
  419    4. Liviu Chircu (@liviuchircu)         Mar 2014 - Nov 2018
  420    5. Ovidiu Sas (@ovidiusas)             Jan 2013 - Jan 2013
  421    6. Marius Zbihlei                      Sep 2010 - Sep 2010
  422    7. Iñaki Baz Castillo                  Feb 2009 - Jul 2010
  423    8. Anca Vamanu                         Sep 2009 - Sep 2009
  424    9. Sergio Gutierrez                    Feb 2009 - Feb 2009
  425 
  426    (1) including any documentation-related commits, excluding
  427    merge commits
  428 
  429 Chapter 3. Documentation
  430 
  431 3.1. Contributors
  432 
  433    Last edited by: Vlad Patrascu (@rvlad-patrascu), Razvan Crainea
  434    (@razvancrainea), Liviu Chircu (@liviuchircu), Bogdan-Andrei
  435    Iancu (@bogdan-iancu), Iñaki Baz Castillo.
  436 
  437    Documentation Copyrights:
  438 
  439    Copyright © 2009 Iñaki Baz Castillo