Revoving obsolete file

[privoxy.git] / doc / pcrs.3

diff --git a/doc/pcrs.3 b/doc/pcrs.3
index c692565..2a96d5a 100644 (file)
--- a/doc/pcrs.3
+++ b/doc/pcrs.3
@@ -17,82 +17,84 @@
 .\"
 .\" You should have received a copy of the GNU General Public
 .\" License along with this manual; if not, write to the Free
 .\"
 .\" You should have received a copy of the GNU General Public
 .\" License along with this manual; if not, write to the Free

-.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
-.\" USA.
+.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+.\" MA 02111, USA.

 .\"
 .\"

-.TH PCRS 3 "17 August 2001"
+.TH PCRS 3 "4 March 2002" "pcrs-0.0.1"

 .SH NAME
 pcrs - Perl-compatible regular substitution.
 .SH SYNOPSIS
 .br
 .SH NAME
 pcrs - Perl-compatible regular substitution.
 .SH SYNOPSIS
 .br

-.BI "#include <pcrs.h>"
+.B "#include <pcrs.h>"

 .PP
 .br
 .PP
 .br

-.BI "pcrs_job *pcrs_compile(const char *" "pattern" "," 
+.BI "pcrs_job *pcrs_compile(const char *" pattern "," 

 .ti +5n
 .ti +5n

-.BI "const char *" "substitute" ", const char *" "options" ","
+.BI "const char *" substitute ", const char *" options ,

 .ti +5n
 .ti +5n

-.BI "int *" "errptr" ");"
+.BI "int *" errptr );

 .PP
 .br
 .PP
 .br

-.BI "pcrs_job *pcrs_compile_command(const char *" "command" ","
+.BI "pcrs_job *pcrs_compile_command(const char *" command ,

 .ti +5n
 .ti +5n

-.BI "int *" "errptr");
+.BI "int *" errptr );

 .PP
 .br
 .PP
 .br

-.BI "int pcrs_execute(pcrs_job *" "job" ", char *" "subject" ","
+.BI "int pcrs_execute(pcrs_job *" job ", char *" subject ,

 .ti +5n
 .ti +5n

-.BI "int " "subject_length" ", char **" "result" ","
+.BI "int " subject_length ", char **" result ,

 .ti +5n
 .ti +5n

-.BI "int *" "result_length" ");"
+.BI "int *" result_length );

 .PP
 .br
 .PP
 .br

-.BI "int pcrs_execute_list (pcrs_job *" "joblist" ", char *" "subject" ","
+.BI "int pcrs_execute_list (pcrs_job *" joblist ", char *" subject ,

 .ti +5n
 .ti +5n

-.BI "int " "subject_length" ", char **" "result" ","
+.BI "int " subject_length ", char **" result ,

 .ti +5n
 .ti +5n

-.BI "int *" "result_length" ");"
+.BI "int *" result_length );

 .PP
 .br
 .PP
 .br

-.BI "pcrs_job *pcrs_free_job(pcrs_job *" "job" ");"
+.BI "pcrs_job *pcrs_free_job(pcrs_job *" job );

 .PP
 .br
 .PP
 .br

-.BI "void pcrs_free_joblist(pcrs_job *" "joblist" ");"
+.BI "void pcrs_free_joblist(pcrs_job *" joblist );

 .PP
 .br
 .PP
 .br

-.BI "char *pcrs_strerror(int " "err" ");"
+.BI "char *pcrs_strerror(int " err );

 .PP
 .br
 
 .SH DESCRIPTION
 .PP
 .br
 
 .SH DESCRIPTION

+

 The
 .SM PCRS
 library is a supplement to the 
 .SB PCRE(3)
 library that implements
 The
 .SM PCRS
 library is a supplement to the 
 .SB PCRE(3)
 library that implements

-.RB "regular expression based substitution, like provided by " "Perl(1)" "'s 's'"
+.RB "regular expression based substitution, like provided by " Perl(1) "'s 's'"

 operator. It uses the same syntax and semantics as Perl 5, with just a few
 differences (see below).
 
 In a first step, the information on a substitution, i.e. the pattern, the
 substitute and the options are compiled from Perl syntax to an internal form
 operator. It uses the same syntax and semantics as Perl 5, with just a few
 differences (see below).
 
 In a first step, the information on a substitution, i.e. the pattern, the
 substitute and the options are compiled from Perl syntax to an internal form

-.RB "called " "pcrs_job" " by using either the " "pcrs_compile()" " or " 
-.BR "pcrs_compile_command()" " functions."
+.RB "called " pcrs_job " by using either the " pcrs_compile() " or " 
+.BR pcrs_compile_command() " functions."

 
 Once the job is compiled, it can be used on subjects, which are arbitrary 
 memory areas containing string or binary data, by calling
 
 Once the job is compiled, it can be used on subjects, which are arbitrary 
 memory areas containing string or binary data, by calling

-.BR "pcrs_execute()" ". Jobs can be chained to joblists and whole"
-.RB "joblists can be applied to a subject using " "pcrs_execute_list()" "."
+.BR pcrs_execute() ". Jobs can be chained to joblists and whole"
+.RB "joblists can be applied to a subject using " pcrs_execute_list() .

 
 There are also convenience functions for freeing the jobs and for errno-to-string
 
 There are also convenience functions for freeing the jobs and for errno-to-string

-.RB "conversion, namely " "pcrs_free_job()" ", " "pcrs_free_joblist()" " and "
-.BR "pcrs_strerror()" "."
+.RB "conversion, namely " pcrs_free_job() ", " pcrs_free_joblist() " and "
+.BR pcrs_strerror() .

 
 .SH COMPILING JOBS
 
 .SH COMPILING JOBS

-.RB "The function " "pcrs_compile()" " is called to compile a " "pcrs_job" 
-.RI "from a " "pattern" ", " "substitute" " and " "options" " string.
+
+.RB "The function " pcrs_compile() " is called to compile a " pcrs_job
+.RI "from a " pattern ", " substitute " and " options " string."

 .RB "The resulting " "pcrs_job" " structure is dynamically allocated and it"
 .RB "The resulting " "pcrs_job" " structure is dynamically allocated and it"

-.RB "is the caller's responsibility to " "free()" " it when it's no longer needed."
+.RB "is the caller's responsibility to call " "pcrs_free_job()" "  when it's no longer needed."

 
 .BR "pcrs_compile_command()" " is a convenience wrapper function that parses a Perl"
 .IR "command" " of the form"
 
 .BR "pcrs_compile_command()" " is a convenience wrapper function that parses a Perl"
 .IR "command" " of the form"


@@ -268,15 +270,15 @@ is set.
 
 .RB "On success, " pcrs_execute() " returns the number of substitutions that"
 were made, which is limited to 0 or 1 for non-global searches.
 
 .RB "On success, " pcrs_execute() " returns the number of substitutions that"
 were made, which is limited to 0 or 1 for non-global searches.

-.RI "On failure, a negative error code is returned and " *result " is set"
+.RI "On failure, a negative error code is returned and " result " is set"

 .RB "to " NULL .
 
 .SH FREEING JOBS
 .RB "It is not sufficient to call " free() " on a " pcrs_job ", because it "
 contains pointers to other dynamically allocated structures.
 .RB "to " NULL .
 
 .SH FREEING JOBS
 .RB "It is not sufficient to call " free() " on a " pcrs_job ", because it "
 contains pointers to other dynamically allocated structures.

-.RB "Use " pcrs_free() " instead. It is safe to pass " NULL " pointers "
+.RB "Use " pcrs_free_job() " instead. It is safe to pass " NULL " pointers "

 .RB "(or pointers to invalid " pcrs_job "s that contain " NULL " pointers"
 .RB "(or pointers to invalid " pcrs_job "s that contain " NULL " pointers"

-.RB "to dependant structures) to " pcrs_free() "."
+.RB "to dependant structures) to " pcrs_free_job() "."

 
 .SS Return value
 .RB "The value of the job's " next " pointer."
 
 .SS Return value
 .RB "The value of the job's " next " pointer."


@@ -308,7 +310,7 @@ The quote character is (surprise!) '\fB\\\fR'. It quotes the delimiter in a
 .IR command ", the"
 .RB ' $ "' in  a"
 .IR substitute ", and, of course, itself. Note that the"
 .IR command ", the"
 .RB ' $ "' in  a"
 .IR substitute ", and, of course, itself. Note that the"

-.RB ' $ "'doesn't need to be quoted if it isn't followed by " [0-9+'`&] "."
+.RB ' $ "' doesn't need to be quoted if it isn't followed by " [0-9+'`&] "."

 
 .RI "For quoting in the " pattern ", please refer to"
 .BR PCRE(3) .
 
 .RI "For quoting in the " pattern ", please refer to"
 .BR PCRE(3) .


@@ -403,7 +405,8 @@ int main(int Argc, char **Argv)
 {
    pcrs_job *job;
    char *result;
 {
    pcrs_job *job;
    char *result;

-   int newsize, err;
+   size_t newsize;
+   int err;

 
    if (Argc != 3)
    {
 
    if (Argc != 3)
    {


@@ -413,21 +416,22 @@ int main(int Argc, char **Argv)
 
    if (NULL == (job = pcrs_compile_command(Argv[1], &err)))
    {
 
    if (NULL == (job = pcrs_compile_command(Argv[1], &err)))
    {

-      printf("Compile error:  %s (%d).\\n", pcrs_strerror(err), err);
+      fprintf(stderr, "%s: compile error:  %s (%d).\\n", Argv[0], pcrs_strerror(err), err);

    }
 
    if (0 > (err = pcrs_execute(job, Argv[2], strlen(Argv[2]) + 1, &result, &newsize)))
    {
    }
 
    if (0 > (err = pcrs_execute(job, Argv[2], strlen(Argv[2]) + 1, &result, &newsize)))
    {

-      printf("Exec error:  %s (%d).\\n", pcrs_strerror(err), err);
+      fprintf(stderr, "%s: Exec error:  %s (%d).\\n", Argv[0], pcrs_strerror(err), err);
+   }
+   else
+   {
+      printf("Result: *%s*\\n", result);
+      free(result);

    }
    }

-
-   /* Will tolerate NULL result */
-   printf("Result: *%s*\\n", result);

 
    pcrs_free_job(job);
 
    pcrs_free_job(job);

-   if (result) free(result);
+   return(err < 0);

 
 

-   return 0;

 }
 
 .fi
 }
 
 .fi


@@ -436,7 +440,7 @@ int main(int Argc, char **Argv)
 .SH LIMITATIONS
 The number of matches that a global job can have is only limited by the
 available memory. An initial storage for 40 matches is reserved, which
 .SH LIMITATIONS
 The number of matches that a global job can have is only limited by the
 available memory. An initial storage for 40 matches is reserved, which

-is dynamically resized by the factor 1.6 if exhausted.
+is dynamically resized by the factor 1.6 whenever it is exhausted.

 
 The number of capturing subpatterns is currently limited to 33, which
 is a Bad Thing[tm]. It should be dynamically expanded until it reaches the
 
 The number of capturing subpatterns is currently limited to 33, which
 is a Bad Thing[tm]. It should be dynamically expanded until it reaches the


@@ -464,9 +468,12 @@ was originally written for the Internet Junkbuster project
 .SH AUTHOR
 
 .SM PCRS
 .SH AUTHOR
 
 .SM PCRS

-is Copyright 2000, 2001 by Andreas Oesterhelt <oes@oesterhelt.org> and is
-licensed under the Terms of the GNU Lesser General Public License (LGPL), which
-should be included in this distribution.
-
-If not, refer to http://www.gnu.org/licenses/lgpl.html or write to the Free
-Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.   
\ No newline at end of file
+is Copyright 2000, 2001 by Andreas Oesterhelt <andreas@oesterhelt.org> and is
+licensed under the terms of the GNU Lesser General Public License (LGPL),
+version 2.1, which should be included in this distribution, with the exception
+that the permission to replace that license with the GNU General Public
+License (GPL) given in section 3 is restricted to version 2 of the GPL.
+
+If it is missing from this distribution, the LGPL can be obtained from
+http://www.gnu.org/licenses/lgpl.html or by mail: Write to the Free Software
+Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.