lib/regexprops.c

   1 /* regexprops.c -- document the properties of the regular expressions
   2                    understood by gnulib.
   3
   4    Copyright 2005 Free Software Foundation, Inc.
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 2, or (at your option)
   9    any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program; if not, write to the Free Software Foundation,
  18    Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
  19
  20 /* Written by James Youngman, <jay@gnu.org>. */
  21
  22 #include <config.h>
  23
  24
  25 #include <stdio.h>
  26 #include <unistd.h>
  27 #include <errno.h>
  28
  29 #include "regex.h"
  30 #include "regextype.h"
  31
  32
  33 /* Name this program was run with. */
  34 char *program_name;
  35
  36 static void output(const char *s, int escape)
  37 {
  38   (void) escape;
  39
  40   fputs(s, stdout);
  41 }
  42
  43
  44 static void newline(void)
  45 {
  46   output("\n", 0);
  47 }
  48
  49 static void content(const char *s)
  50 {
  51   output(s, 1);
  52 }
  53
  54 static void literal(const char *s)
  55 {
  56   output(s, 0);
  57 }
  58
  59 static void directive(const char *s)
  60 {
  61   output(s, 0);
  62 }
  63
  64 static void enum_item(const char *s)
  65 {
  66   newline();
  67   directive("@item ");
  68   literal(s);
  69   newline();
  70 }
  71
  72 static void begin_subsection(const char *name,
  73                           const char *next,
  74                           const char *prev,
  75                           const char *up)
  76 {
  77   (void) next;
  78   (void) prev;
  79   (void) up;
  80
  81   newline();
  82
  83   directive("@node ");
  84   content(name);
  85   content(" regular expression syntax");
  86   newline();
  87
  88   directive("@subsection ");
  89   output("@samp{", 0);
  90   content(name);
  91   output("}", 0);
  92   content(" regular expression syntax");
  93   newline();
  94 }
  95
  96 static void begintable_markup(char const *markup)
  97 {
  98   newline();
  99   directive("@table ");
 100   literal(markup);
 101   newline();
 102 }
 103
 104 static void endtable()
 105 {
 106   newline();
 107   directive("@end table");
 108   newline();
 109 }
 110
 111 static void beginenum()
 112 {
 113   newline();
 114   directive("@enumerate");
 115   newline();
 116 }
 117
 118 static void endenum()
 119 {
 120   newline();
 121   directive("@end enumerate");
 122   newline();
 123 }
 124
 125 static void newpara()
 126 {
 127   content("\n\n");
 128 }
 129
 130
 131 static void
 132 describe_regex_syntax(int options)
 133 {
 134   newpara();
 135   content("The character @samp{.} matches any single character");
 136   if ( (options & RE_DOT_NEWLINE)  == 0 )
 137     {
 138       content(" except newline");
 139     }
 140   if (options & RE_DOT_NOT_NULL)
 141     {
 142       if ( (options & RE_DOT_NEWLINE)  == 0 )
 143         content(" and");
 144       else
 145         content(" except");
 146
 147       content(" the null character");
 148     }
 149   content(".  ");
 150   newpara();
 151
 152   if (!(options & RE_LIMITED_OPS))
 153     {
 154       begintable_markup("@samp");
 155       if (options & RE_BK_PLUS_QM)
 156         {
 157           enum_item("\\+");
 158           content("indicates that the regular expression should match one"
 159                   " or more occurrences of the previous atom or regexp.  ");
 160           enum_item("\\?");
 161           content("indicates that the regular expression should match zero"
 162                   " or one occurrence of the previous atom or regexp.  ");
 163           enum_item("+ and ? ");
 164           content("match themselves.  ");
 165         }
 166       else
 167         {
 168           enum_item("+");
 169           content("indicates that the regular expression should match one"
 170                   " or more occurrences of the previous atom or regexp.  ");
 171           enum_item("?");
 172           content("indicates that the regular expression should match zero"
 173                   " or one occurrence of the previous atom or regexp.  ");
 174           enum_item("\\+");
 175           literal("matches a @samp{+}");
 176           enum_item("\\?");
 177           literal("matches a @samp{?}.  ");
 178         }
 179       endtable();
 180     }
 181
 182   newpara();
 183
 184   content("Bracket expressions are used to match ranges of characters.  ");
 185   literal("Bracket expressions where the range is backward, for example @samp{[z-a]}, are ");
 186   if (options & RE_NO_EMPTY_RANGES)
 187     content("invalid");
 188   else
 189     content("ignored");
 190   content(".  ");
 191
 192   if (options &  RE_BACKSLASH_ESCAPE_IN_LISTS)
 193     literal("Within square brackets, @samp{\\} can be used to quote "
 194             "the following character.  ");
 195   else
 196     literal("Within square brackets, @samp{\\} is taken literally.  ");
 197
 198   if (options & RE_CHAR_CLASSES)
 199     content("Character classes are supported; for example "
 200             "@samp{[[:digit:]]} will match a single decimal digit.  ");
 201   else
 202     literal("Character classes are not supported, so for example "
 203             "you would need to use @samp{[0-9]} "
 204             "instead of @samp{[[:digit:]]}.  ");
 205
 206   if (options & RE_HAT_LISTS_NOT_NEWLINE)
 207     {
 208       literal("Non-matching lists @samp{[^@dots{}]} do not ever match newline.  ");
 209     }
 210   newpara();
 211   if (options & RE_NO_GNU_OPS)
 212     {
 213       content("GNU extensions are not supported and so "
 214               "@samp{\\w}, @samp{\\W}, @samp{\\<}, @samp{\\>}, @samp{\\b}, @samp{\\B}, @samp{\\`}, and @samp{\\'} "
 215               "match "
 216               "@samp{w}, @samp{W}, @samp{<}, @samp{>}, @samp{b}, @samp{B}, @samp{`}, and @samp{'} respectively.  ");
 217     }
 218   else
 219     {
 220       content("GNU extensions are supported:");
 221       beginenum();
 222       enum_item("@samp{\\w} matches a character within a word");
 223       enum_item("@samp{\\W} matches a character which is not within a word");
 224       enum_item("@samp{\\<} matches the beginning of a word");
 225       enum_item("@samp{\\>} matches the end of a word");
 226       enum_item("@samp{\\b} matches a word boundary");
 227       enum_item("@samp{\\B} matches characters which are not a word boundary");
 228       enum_item("@samp{\\`} matches the beginning of the whole input");
 229       enum_item("@samp{\\'} matches the end of the whole input");
 230       endenum();
 231     }
 232
 233   newpara();
 234
 235
 236   if (options & RE_NO_BK_PARENS)
 237     {
 238       literal("Grouping is performed with parentheses @samp{()}.  ");
 239
 240       if (options & RE_UNMATCHED_RIGHT_PAREN_ORD)
 241         literal("An unmatched @samp{)} matches just itself.  ");
 242     }
 243   else
 244     {
 245       literal("Grouping is performed with backslashes followed by parentheses @samp{\\(}, @samp{\\)}.  ");
 246     }
 247
 248   if (options & RE_NO_BK_REFS)
 249     {
 250       content("A backslash followed by a digit matches that digit.  ");
 251     }
 252   else
 253     {
 254       literal("A backslash followed by a digit acts as a back-reference and matches the same thing as the previous grouped expression indicated by that number.  For example @samp{\\2} matches the second group expression.  The order of group expressions is determined by the position of their opening parenthesis ");
 255       if (options & RE_NO_BK_PARENS)
 256           literal("@samp{(}");
 257       else
 258         literal("@samp{\\(}");
 259       content(".  ");
 260     }
 261
 262
 263   newpara();
 264   if (!(options & RE_LIMITED_OPS))
 265     {
 266       if (options & RE_NO_BK_VBAR)
 267         literal("The alternation operator is @samp{|}.  ");
 268       else
 269         literal("The alternation operator is @samp{\\|}. ");
 270     }
 271   newpara();
 272
 273   if (options & RE_CONTEXT_INDEP_ANCHORS)
 274     {
 275       literal("The characters @samp{^} and @samp{$} always represent the beginning and end of a string respectively, except within square brackets.  Within brackets, @samp{^} can be used to invert the membership of the character class being specified.  ");
 276     }
 277   else
 278     {
 279       literal("The character @samp{^} only represents the beginning of a string when it appears:");
 280       beginenum();
 281       enum_item("\nAt the beginning of a regular expression");
 282       enum_item("After an open-group, signified by ");
 283       if (options & RE_NO_BK_PARENS)
 284         {
 285           literal("@samp{(}");
 286         }
 287       else
 288         {
 289           literal("@samp{\\(}");
 290         }
 291       newline();
 292       if (!(options & RE_LIMITED_OPS))
 293         {
 294           if (options & RE_NEWLINE_ALT)
 295             enum_item("After a newline");
 296
 297           if (options & RE_NO_BK_VBAR )
 298             enum_item("After the alternation operator @samp{|}");
 299           else
 300             enum_item("After the alternation operator @samp{\\|}");
 301         }
 302       endenum();
 303
 304       newpara();
 305       literal("The character @samp{$} only represents the end of a string when it appears:");
 306       beginenum();
 307       enum_item("At the end of a regular expression");
 308       enum_item("Before a close-group, signified by ");
 309       if (options & RE_NO_BK_PARENS)
 310         {
 311           literal("@samp{)}");
 312         }
 313       else
 314         {
 315           literal("@samp{\\)}");
 316         }
 317       if (!(options & RE_LIMITED_OPS))
 318         {
 319           if (options & RE_NEWLINE_ALT)
 320             enum_item("Before a newline");
 321
 322           if (options & RE_NO_BK_VBAR)
 323             enum_item("Before the alternation operator @samp{|}");
 324           else
 325             enum_item("Before the alternation operator @samp{\\|}");
 326         }
 327       endenum();
 328     }
 329   newpara();
 330   if (!(options & RE_LIMITED_OPS) )
 331     {
 332       if ((options & RE_CONTEXT_INDEP_OPS)
 333           && !(options & RE_CONTEXT_INVALID_OPS))
 334         {
 335           literal("The characters @samp{*}, @samp{+} and @samp{?} are special anywhere in a regular expression.  ");
 336         }
 337       else
 338         {
 339           if (options & RE_BK_PLUS_QM)
 340             literal("@samp{\\*}, @samp{\\+} and @samp{\\?} ");
 341           else
 342             literal("@samp{*}, @samp{+} and @samp{?} ");
 343
 344           if (options & RE_CONTEXT_INVALID_OPS)
 345             {
 346               content("are special at any point in a regular expression except the following places, where they are not allowed:");
 347             }
 348           else
 349             {
 350               content("are special at any point in a regular expression except:");
 351             }
 352
 353           beginenum();
 354           enum_item("At the beginning of a regular expression");
 355           enum_item("After an open-group, signified by ");
 356           if (options & RE_NO_BK_PARENS)
 357             {
 358               literal("@samp{(}");
 359             }
 360           else
 361             {
 362               literal("@samp{\\(}");
 363             }
 364           if (!(options & RE_LIMITED_OPS))
 365             {
 366               if (options & RE_NEWLINE_ALT)
 367                 enum_item("After a newline");
 368
 369               if (options & RE_NO_BK_VBAR)
 370                 enum_item("After the alternation operator @samp{|}");
 371               else
 372                 enum_item("After the alternation operator @samp{\\|}");
 373             }
 374           endenum();
 375         }
 376     }
 377
 378
 379   newpara();
 380   if (options & RE_INTERVALS)
 381     {
 382       if (options & RE_NO_BK_BRACES)
 383         {
 384           literal("Intervals are specified by @samp{@{} and @samp{@}}.  ");
 385           if (options & RE_INVALID_INTERVAL_ORD)
 386             {
 387               literal("Invalid intervals are treated as literals, for example @samp{a@{1} is treated as @samp{a\\@{1}");
 388             }
 389           else
 390             {
 391               literal("Invalid intervals such as @samp{a@{1z} are not accepted.  ");
 392             }
 393         }
 394       else
 395         {
 396           literal("Intervals are specified by @samp{\\@{} and @samp{\\@}}.  ");
 397           if (options & RE_INVALID_INTERVAL_ORD)
 398             {
 399               literal("Invalid intervals are treated as literals, for example @samp{a\\@{1} is treated as @samp{a@{1}");
 400             }
 401           else
 402             {
 403               literal("Invalid intervals such as @samp{a\\@{1z} are not accepted.  ");
 404             }
 405         }
 406
 407     }
 408
 409   newpara();
 410   if (options & RE_NO_POSIX_BACKTRACKING)
 411     {
 412       content("Matching succeeds as soon as the whole pattern is matched, meaning that the result may not be the longest possible match.  ");
 413     }
 414   else
 415     {
 416       content("The longest possible match is returned; this applies to the regular expression as a whole and (subject to this constraint) to subexpressions within groups.  ");
 417     }
 418   newpara();
 419 }
 420
 421
 422
 423 static void
 424 menu(void)
 425 {
 426   int i, options;
 427   const char *name;
 428
 429   output("@menu\n", 0);
 430   for (i=0;
 431        options = get_regex_type_flags(i),
 432          name=get_regex_type_name(i);
 433        ++i)
 434     {
 435       output("* ", 0);
 436       output(name, 0);
 437       content(" regular expression syntax");
 438       output("::", 0);
 439       newline();
 440     }
 441   output("@end menu\n", 0);
 442 }
 443
 444
 445 static void
 446 describe_all(const char *up)
 447 {
 448   const char *name, *next, *previous;
 449   int options;
 450   int i, parent;
 451
 452   menu();
 453
 454   previous = "";
 455
 456   for (i=0;
 457        options = get_regex_type_flags(i),
 458          name=get_regex_type_name(i);
 459        ++i)
 460     {
 461       next = get_regex_type_name(i+1);
 462       if (NULL == next)
 463         next = "";
 464       begin_subsection(name, next, previous, up);
 465       parent = get_regex_type_synonym(i);
 466       if (parent >= 0)
 467         {
 468           content("This is a synonym for ");
 469           content(get_regex_type_name(parent));
 470           content(".");
 471         }
 472       else
 473         {
 474           describe_regex_syntax(options);
 475         }
 476       previous = name;
 477     }
 478 }
 479
 480
 481
 482 int main (int argc, char *argv[])
 483 {
 484   const char *up = "";
 485   program_name = argv[0];
 486
 487   if (argc > 1)
 488     up = argv[1];
 489
 490   describe_all(up);
 491   return 0;
 492 }