From 1656bccc9cfcd8a4294c7c667aae96bd47aed8a5 Mon Sep 17 00:00:00 2001 From: Ulya Trofimovich Date: Thu, 17 Sep 2015 15:16:38 +0100 Subject: [PATCH] Documentation: added warning descriptions to manpage and online manual. --- re2c/bootstrap/doc/manual.html | 129 ++++++++++++++++++++++++++++++++- re2c/bootstrap/doc/re2c.1 | 80 +++++++++++++++++++- re2c/doc/re2c.ad.in | 61 ++++++++++++++++ 3 files changed, 265 insertions(+), 5 deletions(-) diff --git a/re2c/bootstrap/doc/manual.html b/re2c/bootstrap/doc/manual.html index a0ed2380..f462cbe7 100644 --- a/re2c/bootstrap/doc/manual.html +++ b/re2c/bootstrap/doc/manual.html @@ -1109,6 +1109,131 @@ http://www.gnu.org/software/src-highlite --> Deprecated and does nothing (single pass is by default now).

+
+-W +
+
+

+ Turn on all warnings. +

+
+
+-Werror +
+
+

+ Turn warnings into errors. Note that this option along doesn’t + turn on any warnings, it only affects those warnings that have + been turned on so far or will be turned on later. +

+
+
+-W<warning> +
+
+

+ Turn on individual warning. +

+
+
+-Wno-<warning> +
+
+

+ Turn off individual warning. +

+
+
+-Werror-<warning> +
+
+

+ Turn on individual warning and treat it as error (this implies + -W<warning>). +

+
+
+-Wno-error-<warning> +
+
+

+ Don’t treat this particular warning as error. This doesn’t turn + off the warning itself. +

+
+ + + +
+

WARNINGS

+
+
+
+-Wcondition-order +
+
+

+ Warn if the generated program makes implicit assumptions about + condition numbering. One should use either -t, --type-header + option or /*!types:re2c*/ directive to generate mapping of + condition names to numbers and use autogenerated condition names. +

+
+
+-Wempty-character-class +
+
+

+ Warn if regular expression contains empty character class. From + the rational point of view trying to match empty character class + makes no sense: it should always fail. However, for backwards + compatibility reasons re2c allows empty character class and treats + it as empty string. Use --empty-class option to change default + behaviour. +

+
+
+-Wmatch-empty-string +
+
+

+ Warn if regular expression in a rule is nullable (matches empty + string). If DFA runs in a loop and empty match is unintentional + (input position in not advanced manually), lexer may get stuck + in eternal loop. +

+
+
+-Wswapped-range +
+
+

+ Warn if range lower bound is greater that upper bound. Default + re2c behaviour is to silently swap range bounds. +

+
+
+-Wundefined-control-flow +
+
+

+ Warn if some input strings cause undefined control flow in lexer + (the faulty patterns are reported). This is the most dangerous + and common mistake. It can be easily fixed by adding default rule + * (this rule has the lowest priority, matches any code unit + and consumes exactly one code unit). +

+
+
+-Wuseless-escape +
+
+

+ Warn if a symbol is escaped when it shouldn’t be. By default re2c + silently ignores escape, but this may as well indicate a typo + or an error in escape sequence. +

+
@@ -2309,14 +2434,14 @@ Ulya Trofimovich skvadrik@gmail.com

VERSION INFORMATION

-

This manpage describes re2c, version 0.14.1.dev, package date 20 Jul 2015.

+

This manpage describes re2c, version 0.14.1.dev, package date 17 Sep 2015.

diff --git a/re2c/bootstrap/doc/re2c.1 b/re2c/bootstrap/doc/re2c.1 index 952bc29b..a41c3308 100644 --- a/re2c/bootstrap/doc/re2c.1 +++ b/re2c/bootstrap/doc/re2c.1 @@ -2,12 +2,12 @@ .\" Title: re2c .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.78.0 -.\" Date: 07/20/2015 +.\" Date: 09/17/2015 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "RE2C" "1" "07/20/2015" "\ \&" "\ \&" +.TH "RE2C" "1" "09/17/2015" "\ \&" "\ \&" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -346,6 +346,80 @@ can be one of the following: .RS 4 Deprecated and does nothing (single pass is by default now)\&. .RE +.PP +\fB\-W\fR +.RS 4 +Turn on all warnings\&. +.RE +.PP +\fB\-Werror\fR +.RS 4 +Turn warnings into errors\&. Note that this option along doesn\(cqt turn on any warnings, it only affects those warnings that have been turned on so far or will be turned on later\&. +.RE +.PP +\fB\-W\fR +.RS 4 +Turn on individual warning\&. +.RE +.PP +\fB\-Wno\-\fR +.RS 4 +Turn off individual warning\&. +.RE +.PP +\fB\-Werror\-\fR +.RS 4 +Turn on individual warning and treat it as error (this implies +\fB\-W\fR)\&. +.RE +.PP +\fB\-Wno\-error\-\fR +.RS 4 +Don\(cqt treat this particular warning as error\&. This doesn\(cqt turn off the warning itself\&. +.RE +.SH "WARNINGS" +.PP +\fB\-Wcondition\-order\fR +.RS 4 +Warn if the generated program makes implicit assumptions about condition numbering\&. One should use either +\fB\-t, \-\-type\-header\fR +option or +\fB/*!types:re2c*/\fR +directive to generate mapping of condition names to numbers and use autogenerated condition names\&. +.RE +.PP +\fB\-Wempty\-character\-class\fR +.RS 4 +Warn if regular expression contains empty character class\&. From the rational point of view trying to match empty character class makes no sense: it should always fail\&. However, for backwards compatibility reasons +\fBre2c\fR +allows empty character class and treats it as empty string\&. Use +\fB\-\-empty\-class\fR +option to change default behaviour\&. +.RE +.PP +\fB\-Wmatch\-empty\-string\fR +.RS 4 +Warn if regular expression in a rule is nullable (matches empty string)\&. If DFA runs in a loop and empty match is unintentional (input position in not advanced manually), lexer may get stuck in eternal loop\&. +.RE +.PP +\fB\-Wswapped\-range\fR +.RS 4 +Warn if range lower bound is greater that upper bound\&. Default +\fBre2c\fR +behaviour is to silently swap range bounds\&. +.RE +.PP +\fB\-Wundefined\-control\-flow\fR +.RS 4 +Warn if some input strings cause undefined control flow in lexer (the faulty patterns are reported)\&. This is the most dangerous and common mistake\&. It can be easily fixed by adding default rule +\fB*\fR +(this rule has the lowest priority, matches any code unit and consumes exactly one code unit)\&. +.RE +.PP +\fB\-Wuseless\-escape\fR +.RS 4 +Warn if a symbol is escaped when it shouldn\(cqt be\&. By default re2c silently ignores escape, but this may as well indicate a typo or an error in escape sequence\&. +.RE .SH "INTERFACE CODE" .sp The user must supply interface code either in the form of C/C++ code (macros, functions, variables, etc\&.) or in the form of \fIinplace configurations\fR\&. Which symbols must be defined and which are optional depends on a particular use case\&. @@ -1539,4 +1613,4 @@ skvadrik@gmail\&.com .RE .SH "VERSION INFORMATION" .sp -This manpage describes \fBre2c\fR, version 0\&.14\&.1\&.dev, package date 20 Jul 2015\&. +This manpage describes \fBre2c\fR, version 0\&.14\&.1\&.dev, package date 17 Sep 2015\&. diff --git a/re2c/doc/re2c.ad.in b/re2c/doc/re2c.ad.in index fc63a981..9823a428 100644 --- a/re2c/doc/re2c.ad.in +++ b/re2c/doc/re2c.ad.in @@ -228,6 +228,67 @@ OPTIONS *-1* *--single-pass*:: Deprecated and does nothing (single pass is by default now). +*-W*:: + Turn on all warnings. + +*-Werror*:: + Turn warnings into errors. Note that this option along doesn't + turn on any warnings, it only affects those warnings that have + been turned on so far or will be turned on later. + +*-W*:: + Turn on individual warning. + +*-Wno-*:: + Turn off individual warning. + +*-Werror-*:: + Turn on individual warning and treat it as error (this implies + *-W*). + +*-Wno-error-*:: + Don't treat this particular warning as error. This doesn't turn + off the warning itself. + + +WARNINGS +-------- +*-Wcondition-order*:: + Warn if the generated program makes implicit assumptions about + condition numbering. One should use either *-t, --type-header* + option or *$$/*!types:re2c*/$$* directive to generate mapping of + condition names to numbers and use autogenerated condition names. + +*-Wempty-character-class*:: + Warn if regular expression contains empty character class. From + the rational point of view trying to match empty character class + makes no sense: it should always fail. However, for backwards + compatibility reasons *re2c* allows empty character class and treats + it as empty string. Use *--empty-class* option to change default + behaviour. + +*-Wmatch-empty-string*:: + Warn if regular expression in a rule is nullable (matches empty + string). If DFA runs in a loop and empty match is unintentional + (input position in not advanced manually), lexer may get stuck + in eternal loop. + +*-Wswapped-range*:: + Warn if range lower bound is greater that upper bound. Default + *re2c* behaviour is to silently swap range bounds. + +*-Wundefined-control-flow*:: + Warn if some input strings cause undefined control flow in lexer + (the faulty patterns are reported). This is the most dangerous + and common mistake. It can be easily fixed by adding default rule + *$$*$$* (this rule has the lowest priority, matches any code unit + and consumes exactly one code unit). + +*-Wuseless-escape*:: + Warn if a symbol is escaped when it shouldn't be. By default re2c + silently ignores escape, but this may as well indicate a typo + or an error in escape sequence. + INTERFACE CODE -------------- -- 2.40.0