doc/pcrs.3

   1 .\" Copyright (c) 2001-2003 Andreas S. Oesterhelt <oes@oesterhelt.org>
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" The GNU General Public License's references to "object code"
   9 .\" and "executables" are to be interpreted as the output of any
  10 .\" document formatting or typesetting system, including
  11 .\" intermediate and printed output.
  12 .\"
  13 .\" This manual is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public
  19 .\" License along with this manual; if not, write to the Free
  20 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
  21 .\" MA 02111, USA.
  22 .\"
  23 .TH PCRS 3 "2 December 2003" "pcrs-0.0.3"
  24 .SH NAME
  25 pcrs - Perl-compatible regular substitution.
  26 .SH SYNOPSIS
  27 .br
  28 .B "#include <pcrs.h>"
  29 .PP
  30 .br
  31 .BI "pcrs_job *pcrs_compile(const char *" pattern ","
  32 .ti +5n
  33 .BI "const char *" substitute ", const char *" options ,
  34 .ti +5n
  35 .BI "int *" errptr );
  36 .PP
  37 .br
  38 .BI "pcrs_job *pcrs_compile_command(const char *" command ,
  39 .ti +5n
  40 .BI "int *" errptr );
  41 .PP
  42 .br
  43 .BI "int pcrs_execute(pcrs_job *" job ", char *" subject ,
  44 .ti +5n
  45 .BI "int " subject_length ", char **" result ,
  46 .ti +5n
  47 .BI "int *" result_length );
  48 .PP
  49 .br
  50 .BI "int pcrs_execute_list (pcrs_job *" joblist ", char *" subject ,
  51 .ti +5n
  52 .BI "int " subject_length ", char **" result ,
  53 .ti +5n
  54 .BI "int *" result_length );
  55 .PP
  56 .br
  57 .BI "pcrs_job *pcrs_free_job(pcrs_job *" job );
  58 .PP
  59 .br
  60 .BI "void pcrs_free_joblist(pcrs_job *" joblist );
  61 .PP
  62 .br
  63 .BI "char *pcrs_strerror(int " err );
  64 .PP
  65 .br
  66
  67 .SH DESCRIPTION
  68
  69 The
  70 .SM PCRS
  71 library is a supplement to the
  72 .SB PCRE(3)
  73 library that implements
  74 .RB "regular expression based substitution, like provided by " Perl(1) "'s 's'"
  75 operator. It uses the same syntax and semantics as Perl 5, with just a few
  76 differences (see below).
  77
  78 In a first step, the information on a substitution, i.e. the pattern, the
  79 substitute and the options are compiled from Perl syntax to an internal form
  80 .RB "called " pcrs_job " by using either the " pcrs_compile() " or "
  81 .BR pcrs_compile_command() " functions."
  82
  83 Once the job is compiled, it can be used on subjects, which are arbitrary
  84 memory areas containing string or binary data, by calling
  85 .BR pcrs_execute() ". Jobs can be chained to joblists and whole"
  86 .RB "joblists can be applied to a subject using " pcrs_execute_list() .
  87
  88 There are also convenience functions for freeing the jobs and for errno-to-string
  89 .RB "conversion, namely " pcrs_free_job() ", " pcrs_free_joblist() " and "
  90 .BR pcrs_strerror() .
  91
  92 .SH COMPILING JOBS
  93
  94 .RB "The function " pcrs_compile() " is called to compile a " pcrs_job
  95 .RI "from a " pattern ", " substitute " and " options " string."
  96 .RB "The resulting " "pcrs_job" " structure is dynamically allocated and it"
  97 .RB "is the caller's responsibility to call " "pcrs_free_job()" "  when it's no longer needed."
  98
  99 .BR "pcrs_compile_command()" " is a convenience wrapper function that parses a Perl"
 100 .IR "command" " of the form"
 101 .BI "s/" "pattern" "/" "substitute" "/[" "options" "]"
 102 .RB "into its components and then calls " "pcrs_compile()" ". As in Perl, you"
 103 .RB "are not bound to the '" "/" "' character: Whatever"
 104 .RB "follows the '" "s" "' will be used as the delimiter. Patterns or substitutes"
 105 that contain the delimiter need to quote it:
 106 \fBs/th\\/is/th\\/at/\fR
 107 .RB "will replace " "th/is" " by " "th/at" " and can be written more simply as"
 108 .BR "s|th/is|th/at|" "."
 109
 110 .IR "pattern" ", " "substitute" ", " "options" " and " "command" " must be"
 111 .RI "zero-terminated C strings. " "substitute" " and " "options" " may be"
 112 .BR "NULL" ", in which case they are treated like the empty string."
 113
 114 .SS "Return value and diagnostics"
 115 On success, both functions return a pointer to the compiled job.
 116 .RB "On failure, " "NULL"
 117 .RI "is returned. In that case, the pcrs error code is written to *" "err" "."
 118
 119 .SS Patterns
 120 .RI "For the syntax of the " "pattern" ", see the "
 121 .BR "PCRE(3)" " manual page."
 122
 123 .SS Substitutes
 124 .RI "The " "substitute" " uses"
 125 .RB "Perl syntax as documented in the " "perlre(1)" " manual page, with"
 126 some exceptions:
 127
 128 Most notably and evidently, since
 129 .SM PCRS
 130 is not Perl, variable interpolation or Perl command substitution won't work.
 131 Special variables that do get interpolated, are:
 132 .TP
 133 .B "$1, $2, ..., $n"
 134 Like in Perl, these variables refer to what the nth capturing subpattern
 135 in the pattern matched.
 136 .TP
 137 .B "$& and $0"
 138 .RB "refer to the whole match. Note that " "$0" " is deprecated in recent"
 139 Perl versions and now refers to the program name.
 140 .TP
 141 .B "$+"
 142 refers to what the last capturing subpattern matched.
 143 .TP
 144 .BR "$` and $'" " (backtick and tick)"
 145 .RI "refer to the areas of the " "subject" " before and after the match, respectively."
 146 .RB "Note that, like in Perl, the " "unmodified" " subject is used, even"
 147 if a global substitution previously matched.
 148
 149 .PP
 150 Perl4-style references to subpattern matches of the form
 151 \fB\\1, \\2, ...\fR
 152 .RB "which only exist in Perl5 for backwards compatibility, are " "not"
 153 supported.
 154
 155 Also, since the substitute is a double-quoted string in Perl, you
 156 might expect all Perl syntax for special characters to apply. In fact,
 157 only the following are supported:
 158
 159 .TP
 160 \fB\\n\fR
 161 newline (0x0a)
 162 .TP
 163 \fB\\r\fR
 164 carriage return (0x0d)
 165 .TP
 166 \fB\\t\fR
 167 horizontal tab (0x09)
 168 .TP
 169 \fB\\f\fR
 170 form feed (0x0c)
 171 .TP
 172 \fB\\b\fR
 173 backspace (0x08)
 174 .TP
 175 \fB\\a\fR
 176 alarm, bell (0x07)
 177 .TP
 178 \fB\\e\fR
 179 escape (0x1b)
 180 .TP
 181 \fB\\0\fR
 182 binary zero (0x00)
 183
 184 .SS "Options"
 185 .RB "The options " "gmisx" " are supported. " "e" " is not, since it would"
 186 .RB "require a Perl interpreter and neither is " o ", because the pattern
 187 is explicitly compiled, anyway. Additionally,
 188 .SM PCRS
 189 .RB "honors the options " "U" " and " "T" "."
 190 Where
 191 .SM PCRE
 192 .RB "options are mentioned below, refer to " PCRE(3) " for the subtle differences"
 193 to Perl behaviour.
 194
 195 .TP
 196 .B g
 197 .RB "Replace " all " instances of"
 198 .IR pattern " in " subject ,
 199 not just the first one.
 200
 201 .TP
 202 .B i
 203 .RI "Match the " pattern " without respect to case. This translates to"
 204 .SM PCRE_CASELESS.
 205
 206 .TP
 207 .B m
 208 .RI "Treat the " subject " as consisting of multiple lines, i.e."
 209 .RB ' ^ "' matches immediately after, and '" $ "' immediately before each newline."
 210 Translates to
 211 .SM PCRE_MULTILINE.
 212
 213 .TP
 214 .B s
 215 .RI "Treat the " subject " as consisting of one single line, i.e."
 216 .RB "let the scope of the '" . "' metacharacter include newlines."
 217 Translates to
 218 .SM PCRE_DOTALL.
 219
 220 .TP
 221 .B x
 222 .RI "Allow extended regular expression syntax in the " pattern ","
 223 .RB "enabling whitespace and comments in complex patterns."
 224 Translates to
 225 .SM PCRE_EXTENDED.
 226
 227 .TP
 228 .B U
 229 .RB "Switch the default behaviour of the '" * "' and '" + "' quantifiers"
 230 .RB "to ungreedy. Note that appending a '" ? "' switches back to greedy(!)."
 231 .RB "The explicit in-pattern switches " (?U) " and " (?-U) " remain unaffected."
 232 Translates to
 233 .SM PCRE_UNGREEDY.
 234
 235 .TP
 236 .B T
 237 .RI "Consider the " substitute " trivial, i.e. do not interpret any references"
 238 or special character escape sequences in the substitute. Handy for large
 239 user-supplied substitutes, which would otherwise have to be examined and properly
 240 quoted.
 241
 242 .PP
 243 Unsupported options are silently ignored.
 244
 245 .SH EXECUTING JOBS
 246
 247 .RI "Calling " pcrs_execute() " produces a modified copy of the " subject ", in which"
 248 .RB "the first (or all, if the '" g "' option was given when compiling the job)"
 249 .RI "occurance(s) of the job's " pattern " in the " subject " is replaced by the job's"
 250 .IR substitute .
 251
 252 .RI "The first " subject_length " bytes following " subject " are processed, so"
 253 .RI  "a " subject_length " that exceeds the actual " subject " is dangerous."
 254 .RI "Note that for zero-terminated C strings, you should set " subject_length " to"
 255 .BI strlen( subject ) \fR,
 256 so that the dollar metacharacter matches at the end of the string, not after
 257 the string-terminating null byte. For convenience, an extra null byte is
 258 appended to the result so it can again be used as a string.
 259
 260 .RI "The " subject " itself is left untouched, and the " *result " is dynamically"
 261 .RB "allocated, so it is the caller's responsibility to " free() " it when it's"
 262 no longer needed.
 263
 264 .RI "The result's length (excluding the extra null byte) is written to " *result_length "."
 265
 266 .RB "If the job matched, the " PCRS_SUCCESS " flag in"
 267 .IB job ->flags
 268 is set.
 269
 270
 271 .SS String subjects
 272 If your
 273
 274 .SS Return value and diagnostics
 275
 276 .RB "On success, " pcrs_execute() " returns the number of substitutions that"
 277 were made, which is limited to 0 or 1 for non-global searches.
 278 .RI "On failure, a negative error code is returned and " result " is set"
 279 .RB "to " NULL .
 280
 281 .SH FREEING JOBS
 282 .RB "It is not sufficient to call " free() " on a " pcrs_job ", because it "
 283 contains pointers to other dynamically allocated structures.
 284 .RB "Use " pcrs_free_job() " instead. It is safe to pass " NULL " pointers "
 285 .RB "(or pointers to invalid " pcrs_job "s that contain " NULL " pointers"
 286 .RB "to dependant structures) to " pcrs_free_job() "."
 287
 288 .SS Return value
 289 .RB "The value of the job's " next " pointer."
 290
 291
 292 .SH CHAINING JOBS
 293
 294 .SM PCRS
 295 .RB "supports to some extent the chaining of multiple " pcrs_job " structures by"
 296 .RB "means of their " next " member."
 297
 298 Chaining the jobs is up to you, but once you have built a linked list of jobs,
 299 .RI "you can execute a whole " joblist " on a given subject by"
 300 .RB "a single call to " pcrs_execute_list() ", which will sequentially traverse"
 301 .RB "the linked list until it reaches a " NULL " pointer, and call " pcrs_execute()
 302 .RI "for each job it encounters, feeding the " result  " and " result_length " of each"
 303 .RI "call into the next as the " subject " and " subject_length ". As in the single"
 304 .RI "job case, the original " subject " remains untouched, but all interim " result "s"
 305 .RB "are of course " free() "d. The return value is the accumulated number of matches"
 306 .RI "for all jobs in the " joblist "."
 307 .RI "Note that while this is handy, it reduces the diagnostic value of " err ", since "
 308 you won't know which job failed.
 309
 310 .RI "In analogy, you can free all jobs in a given " joblist " by calling"
 311 .BR pcrs_free_joblist() .
 312
 313 .SH QUOTING
 314 The quote character is (surprise!) '\fB\\\fR'. It quotes the delimiter in a
 315 .IR command ", the"
 316 .RB ' $ "' in  a"
 317 .IR substitute ", and, of course, itself. Note that the"
 318 .RB ' $ "' doesn't need to be quoted if it isn't followed by " [0-9+'`&] "."
 319
 320 .RI "For quoting in the " pattern ", please refer to"
 321 .BR PCRE(3) .
 322
 323 .SH DIAGNOSTICS
 324
 325 .RB "When " compiling " a job either via the " pcrs_compile() " or " pcrs_compile_command()
 326 .RB "functions, you know that something went wrong when you are returned a " NULL " pointer."
 327 .RI "In that case, or in the event of non-fatal warnings, the integer pointed to by " err
 328 contains a nonzero error code, which is either a passed-through
 329 .SM PCRE
 330 error code or one generated by
 331 .SM PCRS.
 332 Under normal circumstances, it can take the following values:
 333 .TP
 334 .B PCRE_ERROR_NOMEMORY
 335 While compiling the pattern,
 336 .SM PCRE
 337 ran out of memory.
 338 .TP
 339 .B  PCRS_ERR_NOMEM
 340 While compiling the job,
 341 .SM PCRS
 342 ran out of memory.
 343 .TP
 344 .B  PCRS_ERR_CMDSYNTAX
 345 .BR pcrs_compile_command() " didn't find four tokens while parsing the"
 346 .IR command .
 347 .TP
 348 .B  PCRS_ERR_STUDY
 349 A
 350 .SM PCRE
 351 .RB "error occured while studying the compiled pattern. Since " pcre_study()
 352 only provides textual diagnostic information, the details are lost.
 353 .TP
 354 .B  PCRS_WARN_BADREF
 355 .RI "The " substitute " contains a reference to a capturing subpattern that"
 356 .RI "has a higher index than the number of capturing subpatterns in the " pattern
 357 or that exceeds the current hard limit of 33 (See LIMITATIONS below). As in Perl,
 358 this is non-fatal and results in substitutions with the empty string.
 359
 360 .PP
 361 .RB "When " executing " jobs via " pcrs_execute() " or " pcrs_execute_list() ","
 362 .RI "a negative return code indicates an error. In that case, *" result
 363 .RB "is " NULL ". Possible error codes are:"
 364 .TP
 365 .B PCRE_ERROR_NOMEMORY
 366 While matching the pattern,
 367 .SM PCRE
 368 ran out of memory. This can only happen if there are more than 33 backrefrences
 369 .RI "in the " pattern "(!)"
 370 .BR and " memory is too tight to extend storage for more."
 371 .TP
 372 .B  PCRS_ERR_NOMEM
 373 While executing the job,
 374 .SM PCRS
 375 ran out of memory.
 376 .TP
 377 .B  PCRS_ERR_BADJOB
 378 .RB "The " pcrs_job "*  passed to " pcrs_execute " was NULL, or the"
 379 .RB "job is bogus (it contains " NULL " pointers to the compiled
 380 pattern, extra, or substitute).
 381
 382 .PP
 383 If you see any other
 384 .SM PCRE
 385 error code passed through, you've either messed with the compiled job
 386 or found a bug in
 387 .SM PCRS.
 388 Please send me an email.
 389
 390 .RB "Ah, and don't look for " PCRE_ERROR_NOMATCH ", since this"
 391 is not an error in the context of
 392 .SM PCRS.
 393 .RI "Should there be no match, an exact copy of the " subject " is"
 394 .RI "found at *" result " and the return code is 0 (matches)."
 395
 396 All error codes can be translated into human readable text by means
 397 .RB "of the " pcrs_strerror() " function."
 398
 399
 400 .SH EXAMPLE
 401 A trivial command-line test program for
 402 .SM PCRS
 403 might look like:
 404
 405 .nf
 406 #include <pcrs.h>
 407 #include <stdio.h>
 408
 409 int main(int Argc, char **Argv)
 410 {
 411    pcrs_job *job;
 412    char *result;
 413    size_t newsize;
 414    int err;
 415
 416    if (Argc != 3)
 417    {
 418       fprintf(stderr, "Usage: %s s/pattern/substitute/[options]  subject\\n", Argv[0]);
 419       return 1;
 420    }
 421
 422    if (NULL == (job = pcrs_compile_command(Argv[1], &err)))
 423    {
 424       fprintf(stderr, "%s: compile error:  %s (%d).\\n", Argv[0], pcrs_strerror(err), err);
 425    }
 426
 427    if (0 > (err = pcrs_execute(job, Argv[2], strlen(Argv[2]), &result, &newsize)))
 428    {
 429       fprintf(stderr, "%s: exec error:  %s (%d).\\n", Argv[0], pcrs_strerror(err), err);
 430    }
 431    else
 432    {
 433       printf("Result: *%s*\\n", result);
 434       free(result);
 435    }
 436
 437    pcrs_free_job(job);
 438    return(err < 0);
 439
 440 }
 441
 442 .fi
 443
 444
 445 .SH LIMITATIONS
 446 The number of matches that a global job can have is only limited by the
 447 available memory. An initial storage for 40 matches is reserved, which
 448 is dynamically resized by the factor 1.6 whenever it is exhausted.
 449
 450 The number of capturing subpatterns is currently limited to 33, which
 451 is a Bad Thing[tm]. It should be dynamically expanded until it reaches the
 452 .SM PCRE
 453 limit of 99.
 454 .br
 455 This limitation is particularly embarassing since
 456 .SM PCRE
 457 3.5 has raised the capturing subpattern limit to 65K.
 458
 459 All of the above values can be adjusted in the "Capacity" section
 460 .RB "of " pcrs.h "."
 461
 462 The Perl-style escape sequences for special characters \\\fInnn\fR,
 463 \\x\fInn\fR, and \\c\fIX\fR are currently unsupported.
 464
 465 .SH BUGS
 466 This library has only been tested in the context of one application
 467 and should be considered high risk.
 468
 469 .SH HISTORY
 470 .SM PCRS
 471 was originally written for the Privoxy project
 472 (https://www.privoxy.org/).
 473
 474 .SH SEE ALSO
 475 .B PCRE(3), perl(1), perlre(1)
 476
 477 .SH AUTHOR
 478
 479 .SM PCRS
 480 is Copyright 2000 - 2003 by Andreas Oesterhelt <andreas@oesterhelt.org>
 481 and is free software.
 482
 483 You can redistribute it and/or modify it under the terms of the GNU
 484 General Public License as published by the Free Software Foundation;
 485 either version 2 of the License, or (at your option) any later
 486 version.
 487
 488 The GNU General Public License should be included with this file.
 489 If not, you can view it at https://www.gnu.org/copyleft/gpl.html or write
 490 to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 491 Boston, MA 02111-1307, USA.