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