1 /* regexprops.c -- document the properties of the regular expressions
4 Copyright 2005 Free Software Foundation, Inc.
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)
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.
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. */
20 /* Written by James Youngman, <jay@gnu.org>. */
31 #include "regextype.h"
34 /* Name this program was run with. */
37 static void output(const char *s
, int escape
)
43 static void newline(void)
48 static void content(const char *s
)
53 static void literal(const char *s
)
58 static void directive(const char *s
)
63 static void enum_item(const char *s
)
70 static void table_item(const char *s
)
78 static void code(const char *s
)
85 static void begin_subsection(const char *name
,
94 content(" regular expression syntax");
97 directive("@subsection ");
101 content(" regular expression syntax");
105 static void begintable_asis()
108 directive("@table @asis");
112 static void begintable_markup(char const *markup
)
115 directive("@table ");
120 static void endtable()
123 directive("@end table");
127 static void beginenum()
130 directive("@enumerate");
134 static void endenum()
137 directive("@end enumerate");
141 static void newpara()
147 static int describe_regex_syntax(int options
)
150 content("The character @samp{.} matches any single character");
151 if ( (options
& RE_DOT_NEWLINE
) == 0 )
153 content(" except newline");
155 if (options
& RE_DOT_NOT_NULL
)
157 if ( (options
& RE_DOT_NEWLINE
) == 0 )
162 content(" the null character");
167 if (!(options
& RE_LIMITED_OPS
))
169 begintable_markup("@samp");
170 if (options
& RE_BK_PLUS_QM
)
173 content("indicates that the regular expression should match one"
174 " or more occurrences of the previous atom or regexp. ");
176 content("indicates that the regular expression should match zero"
177 " or one occurrence of the previous atom or regexp. ");
178 enum_item("+ and ? ");
179 content("match themselves. ");
184 content("indicates that the regular expression should match one"
185 " or more occurrences of the previous atom or regexp. ");
187 content("indicates that the regular expression should match zero"
188 " or one occurrence of the previous atom or regexp. ");
190 literal("matches a @samp{+}");
192 literal("matches a @samp{?}. ");
199 content("Bracket expressions are used to match ranges of characters. ");
200 literal("Bracket expressions where the range is backward, for example @samp{[z-a]}, are ");
201 if (options
& RE_NO_EMPTY_RANGES
)
207 if (options
& RE_BACKSLASH_ESCAPE_IN_LISTS
)
208 literal("Within square brackets, @samp{\\} can be used to quote "
209 "the following character. ");
211 literal("Within square brackets, @samp{\\} is taken literally. ");
213 if (options
& RE_CHAR_CLASSES
)
214 content("Character classes are supported; for example "
215 "@samp{[[:digit:]]} will match a single decimal digit. ");
217 literal("Character classes are not supported, so for example "
218 "you would need to use @samp{[0-9]} "
219 "instead of @samp{[[:digit:]]}. ");
221 if (options
& RE_HAT_LISTS_NOT_NEWLINE
)
223 literal("Non-matching lists @samp{[^@dots{}]} do not ever match newline. ");
226 if (options
& RE_NO_GNU_OPS
)
228 content("GNU extensions are not supported and so "
229 "@samp{\\w}, @samp{\\W}, @samp{\\<}, @samp{\\>}, @samp{\\b}, @samp{\\B}, @samp{\\`}, and @samp{\\'} "
231 "@samp{w}, @samp{W}, @samp{<}, @samp{>}, @samp{b}, @samp{B}, @samp{`}, and @samp{'} respectively. ");
235 content("GNU extensions are supported:");
237 enum_item("@samp{\\w} matches a character within a word");
238 enum_item("@samp{\\W} matches a character which is not within a word");
239 enum_item("@samp{\\<} matches the beginning of a word");
240 enum_item("@samp{\\>} matches the end of a word");
241 enum_item("@samp{\\b} matches a word boundary");
242 enum_item("@samp{\\B} matches characters which are not a word boundary");
243 enum_item("@samp{\\`} matches the beginning of the whole input");
244 enum_item("@samp{\\'} matches the end of the whole input");
251 if (options
& RE_NO_BK_PARENS
)
253 literal("Grouping is performed with parentheses @samp{()}. ");
255 if (options
& RE_UNMATCHED_RIGHT_PAREN_ORD
)
256 literal("An unmatched @samp{)} matches just itself. ");
260 literal("Grouping is performed with backslashes followed by parentheses @samp{\\(}, @samp{\\)}. ");
263 if (options
& RE_NO_BK_REFS
)
265 content("A backslash followed by a digit matches that digit. ");
269 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 ");
270 if (options
& RE_NO_BK_PARENS
)
273 literal("@samp{\\(}");
279 if (!(options
& RE_LIMITED_OPS
))
281 if (options
& RE_NO_BK_VBAR
)
282 literal("The alternation operator is @samp{|}. ");
284 literal("The alternation operator is @samp{\\|}. ");
288 if (options
& RE_CONTEXT_INDEP_ANCHORS
)
290 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. ");
294 literal("The character @samp{^} only represents the beginning of a string when it appears:");
296 enum_item("\nAt the beginning of a regular expression");
297 enum_item("After an open-group, signified by ");
298 if (options
& RE_NO_BK_PARENS
)
304 literal("@samp{\\(}");
307 if (!(options
& RE_LIMITED_OPS
))
309 if (options
& RE_NEWLINE_ALT
)
310 enum_item("After a newline");
312 if (options
& RE_NO_BK_VBAR
)
313 enum_item("After the alternation operator @samp{|}");
315 enum_item("After the alternation operator @samp{\\|}");
320 literal("The character @samp{$} only represents the end of a string when it appears:");
322 enum_item("At the end of a regular expression");
323 enum_item("Before an close-group, signified by ");
324 if (options
& RE_NO_BK_PARENS
)
330 literal("@samp{\\)}");
332 if (!(options
& RE_LIMITED_OPS
))
334 if (options
& RE_NEWLINE_ALT
)
335 enum_item("Before a newline");
337 if (options
& RE_NO_BK_VBAR
)
338 enum_item("Before the alternation operator @samp{|}");
340 enum_item("Before the alternation operator @samp{\\|}");
345 if (!(options
& RE_LIMITED_OPS
) )
347 if ((options
& RE_CONTEXT_INDEP_OPS
)
348 && !(options
& RE_CONTEXT_INVALID_OPS
))
350 literal("The characters @samp{*}, @samp{+} and @samp{?} are special anywhere in a regular expression. ");
354 if (options
& RE_BK_PLUS_QM
)
355 literal("@samp{\\*}, @samp{\\+} and @samp{\\?} ");
357 literal("@samp{*}, @samp{+} and @samp{?} ");
359 if (options
& RE_CONTEXT_INVALID_OPS
)
361 content("are special at any point in a regular expression except the following places, where they are not allowed:");
365 content("are special at any point in a regular expression except:");
369 enum_item("At the beginning of a regular expression");
370 enum_item("After an open-group, signified by ");
371 if (options
& RE_NO_BK_PARENS
)
377 literal("@samp{\\(}");
379 if (!(options
& RE_LIMITED_OPS
))
381 if (options
& RE_NEWLINE_ALT
)
382 enum_item("After a newline");
384 if (options
& RE_NO_BK_VBAR
)
385 enum_item("After the alternation operator @samp{|}");
387 enum_item("After the alternation operator @samp{\\|}");
395 if (options
& RE_INTERVALS
)
397 if (options
& RE_NO_BK_BRACES
)
399 literal("Intervals are specified by @samp{@{} and @samp{@}}. ");
400 if (options
& RE_INVALID_INTERVAL_ORD
)
402 literal("Invalid intervals are treated as literals, for example @samp{a@{1} is treated as @samp{a\\@{1}");
406 literal("Invalid intervals such as @samp{a@{1z} are not accepted. ");
411 literal("Intervals are specified by @samp{\\@{} and @samp{\\@}}. ");
412 if (options
& RE_INVALID_INTERVAL_ORD
)
414 literal("Invalid intervals are treated as literals, for example @samp{a\\@{1} is treated as @samp{a@{1}");
418 literal("Invalid intervals such as @samp{a\\@{1z} are not accepted. ");
425 if (options
& RE_NO_POSIX_BACKTRACKING
)
427 content("Matching succeeds as soon as the whole pattern is matched, meaning that the result may not be the longest possible match. ");
431 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. ");
443 output("@menu\n", 0);
445 options
= get_regex_type_flags(i
),
446 name
=get_regex_type_name(i
);
451 content(" regular expression syntax");
455 output("@end menu\n", 0);
459 static int describe_all(const char *up
)
461 const char *name
, *next
, *previous
;
470 options
= get_regex_type_flags(i
),
471 name
=get_regex_type_name(i
);
474 next
= get_regex_type_name(i
+1);
477 begin_subsection(name
, next
, previous
, up
);
478 parent
= get_regex_type_synonym(i
);
481 content("This is a synonym for ");
482 content(get_regex_type_name(parent
));
487 describe_regex_syntax(options
);
495 int main (int argc
, char *argv
[])
498 program_name
= argv
[0];