diff options
Diffstat (limited to 'contrib/libxo/doc/xolint.rst')
| -rw-r--r-- | contrib/libxo/doc/xolint.rst | 484 |
1 files changed, 40 insertions, 444 deletions
diff --git a/contrib/libxo/doc/xolint.rst b/contrib/libxo/doc/xolint.rst index c3e518b9cddf..739fa18558f7 100644 --- a/contrib/libxo/doc/xolint.rst +++ b/contrib/libxo/doc/xolint.rst @@ -1,444 +1,40 @@ -'A percent sign appearing in text is a literal' -+++++++++++++++++++++++++++++++++++++++++++++++ - -The message "A percent sign appearing in text is a literal" can be caused by code like: - -:: - - xo_emit("cost: %d", cost); - -This code should be replaced with code like: - -:: - - xo_emit("{L:cost}: {:cost/%d}", cost); - -This can be a bit surprising and could be a field that was not -properly converted to a libxo-style format string. - - -'Unknown long name for role/modifier' -+++++++++++++++++++++++++++++++++++++ - -The message "Unknown long name for role/modifier" can be caused by code like: - -:: - - xo_emit("{,humanization:value}", value); - -This code should be replaced with code like: - -:: - - xo_emit("{,humanize:value}", value); - -The hn-* modifiers (hn-decimal, hn-space, hn-1000) -are only valid for fields with the {h:} modifier. - - -'Last character before field definition is a field type' -++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Last character before field definition is a field type" can be caused by code like: -A common typo: - -:: - - xo_emit("{T:Min} T{:Max}"); - -This code should be replaced with code like: - -:: - - xo_emit("{T:Min} {T:Max}"); - -Twiddling the "{" and the field role is a common typo. - - -'Encoding format uses different number of arguments' -++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Encoding format uses different number of arguments" can be caused by code like: - -:: - - xo_emit("{:name/%6.6s %%04d/%s}", name, number); - -This code should be replaced with code like: - -:: - - xo_emit("{:name/%6.6s %04d/%s-%d}", name, number); - -Both format should consume the same number of arguments off the stack - - -'Only one field role can be used' -+++++++++++++++++++++++++++++++++ - -The message "Only one field role can be used" can be caused by code like: - -:: - - xo_emit("{LT:Max}"); - -This code should be replaced with code like: - -:: - - xo_emit("{T:Max}"); - -'Potential missing slash after C, D, N, L, or T with format' -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Potential missing slash after C, D, N, L, or T with format" can be caused by code like: - -:: - - xo_emit("{T:%6.6s}\n", "Max"); - -This code should be replaced with code like: - -:: - - xo_emit("{T:/%6.6s}\n", "Max"); - -The "%6.6s" will be a literal, not a field format. While -it's possibly valid, it's likely a missing "/". - - -'An encoding format cannot be given (roles: DNLT)' -++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "An encoding format cannot be given (roles: DNLT)" can be caused by code like: - -:: - - xo_emit("{T:Max//%s}", "Max"); - -Fields with the C, D, N, L, and T roles are not emitted in -the 'encoding' style (JSON, XML), so an encoding format -would make no sense. - - -'Format cannot be given when content is present (roles: CDLN)' -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Format cannot be given when content is present (roles: CDLN)" can be caused by code like: - -:: - - xo_emit("{N:Max/%6.6s}", "Max"); - -Fields with the C, D, L, or N roles can't have both -static literal content ("{L:Label}") and a -format ("{L:/%s}"). -This error will also occur when the content has a backslash -in it, like "{N:Type of I/O}"; backslashes should be escaped, -like "{N:Type of I\\/O}". Note the double backslash, one for -handling 'C' strings, and one for libxo. - - -'Field has color without fg- or bg- (role: C)' -++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Field has color without fg- or bg- (role: C)" can be caused by code like: - -:: - - xo_emit("{C:green}{:foo}{C:}", x); - -This code should be replaced with code like: - -:: - - xo_emit("{C:fg-green}{:foo}{C:}", x); - -Colors must be prefixed by either "fg-" or "bg-". - - -'Field has invalid color or effect (role: C)' -+++++++++++++++++++++++++++++++++++++++++++++ - -The message "Field has invalid color or effect (role: C)" can be caused by code like: - -:: - - xo_emit("{C:fg-purple,bold}{:foo}{C:gween}", x); - -This code should be replaced with code like: - -:: - - xo_emit("{C:fg-red,bold}{:foo}{C:fg-green}", x); - -The list of colors and effects are limited. The -set of colors includes default, black, red, green, -yellow, blue, magenta, cyan, and white, which must -be prefixed by either "fg-" or "bg-". Effects are -limited to bold, no-bold, underline, no-underline, -inverse, no-inverse, normal, and reset. Values must -be separated by commas. - - -'Field has humanize modifier but no format string' -++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Field has humanize modifier but no format string" can be caused by code like: - -:: - - xo_emit("{h:value}", value); - -This code should be replaced with code like: - -:: - - xo_emit("{h:value/%d}", value); - -Humanization is only value for numbers, which are not -likely to use the default format ("%s"). - - -'Field has hn-* modifier but not 'h' modifier' -++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Field has hn-* modifier but not 'h' modifier" can be caused by code like: - -:: - - xo_emit("{,hn-1000:value}", value); - -This code should be replaced with code like: - -:: - - xo_emit("{h,hn-1000:value}", value); - -The hn-* modifiers (hn-decimal, hn-space, hn-1000) -are only valid for fields with the {h:} modifier. - - -'Value field must have a name (as content)")' -+++++++++++++++++++++++++++++++++++++++++++++ - -The message "Value field must have a name (as content)")" can be caused by code like: - -:: - - xo_emit("{:/%s}", "value"); - -This code should be replaced with code like: - -:: - - xo_emit("{:tag-name/%s}", "value"); - -The field name is used for XML and JSON encodings. These -tags names are static and must appear directly in the -field descriptor. - - -'Use hyphens, not underscores, for value field name' -++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Use hyphens, not underscores, for value field name" can be caused by code like: - -:: - - xo_emit("{:no_under_scores}", "bad"); - -This code should be replaced with code like: - -:: - - xo_emit("{:no-under-scores}", "bad"); - -Use of hyphens is traditional in XML, and the XOF_UNDERSCORES -flag can be used to generate underscores in JSON, if desired. -But the raw field name should use hyphens. - - -'Value field name cannot start with digit' -++++++++++++++++++++++++++++++++++++++++++ - -The message "Value field name cannot start with digit" can be caused by code like: - -:: - - xo_emit("{:10-gig/}"); - -This code should be replaced with code like: - -:: - - xo_emit("{:ten-gig/}"); - -XML element names cannot start with a digit. - - -'Value field name should be lower case' -+++++++++++++++++++++++++++++++++++++++ - -The message "Value field name should be lower case" can be caused by code like: - -:: - - xo_emit("{:WHY-ARE-YOU-SHOUTING}", "NO REASON"); - -This code should be replaced with code like: - -:: - - xo_emit("{:why-are-you-shouting}", "no reason"); - -Lower case is more civilized. Even TLAs should be lower case -to avoid scenarios where the differences between "XPath" and -"Xpath" drive your users crazy. Lower case rules the seas. - - -'Value field name should be longer than two characters' -+++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Value field name should be longer than two characters" can be caused by code like: - -:: - - xo_emit("{:x}", "mumble"); - -This code should be replaced with code like: - -:: - - xo_emit("{:something-meaningful}", "mumble"); - -Field names should be descriptive, and it's hard to -be descriptive in less than two characters. Consider -your users and try to make something more useful. -Note that this error often occurs when the field type -is placed after the colon ("{:T/%20s}"), instead of before -it ("{T:/20s}"). - - -'Value field name contains invalid character' -+++++++++++++++++++++++++++++++++++++++++++++ - -The message "Value field name contains invalid character" can be caused by code like: - -:: - - xo_emit("{:cost-in-$$/%u}", 15); - -This code should be replaced with code like: - -:: - - xo_emit("{:cost-in-dollars/%u}", 15); - -An invalid character is often a sign of a typo, like "{:]}" -instead of "{]:}". Field names are restricted to lower-case -characters, digits, and hyphens. - - -'decoration field contains invalid character' -+++++++++++++++++++++++++++++++++++++++++++++ - -The message "decoration field contains invalid character" can be caused by code like: - -:: - - xo_emit("{D:not good}"); - -This code should be replaced with code like: - -:: - - xo_emit("{D:((}{:good}{D:))}", "yes"); - -This is minor, but fields should use proper roles. Decoration -fields are meant to hold punctuation and other characters used -to decorate the content, typically to make it more readable -to human readers. - - -'Anchor content should be decimal width' -++++++++++++++++++++++++++++++++++++++++ - -The message "Anchor content should be decimal width" can be caused by code like: - -:: - - xo_emit("{[:mumble}"); - -This code should be replaced with code like: - -:: - - xo_emit("{[:32}"); - -Anchors need an integer value to specify the width of -the set of anchored fields. The value can be positive -(for left padding/right justification) or negative (for -right padding/left justification) and can appear in -either the start or stop anchor field descriptor. - - -'Anchor format should be "%d"' -++++++++++++++++++++++++++++++ - -The message "Anchor format should be "%d"" can be caused by code like: - -:: - - xo_emit("{[:/%s}"); - -This code should be replaced with code like: - -:: - - xo_emit("{[:/%d}"); - -Anchors only grok integer values, and if the value is not static, -if must be in an 'int' argument, represented by the "%d" format. -Anything else is an error. - - -'Anchor cannot have both format and encoding format")' -++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Anchor cannot have both format and encoding format")" can be caused by code like: - -:: - - xo_emit("{[:32/%d}"); - -This code should be replaced with code like: - -:: - - xo_emit("{[:32}"); - -Anchors can have a static value or argument for the width, -but cannot have both. - - -'Max width only valid for strings' -++++++++++++++++++++++++++++++++++ - -The message "Max width only valid for strings" can be caused by code like: - -:: - - xo_emit("{:tag/%2.4.6d}", 55); - -This code should be replaced with code like: - -:: - - xo_emit("{:tag/%2.6d}", 55); - -libxo allows a true 'max width' in addition to the traditional -printf-style 'max number of bytes to use for input'. But this -is supported only for string values, since it makes no sense -for non-strings. This error may occur from a typo, -like "{:tag/%6..6d}" where only one period should be used. +====== +xolint +====== + +`xolint` is a tool for reporting common mistakes in format strings +in source code that invokes `xo_emit`. It allows these errors +to be diagnosed at build time, rather than waiting until runtime. + +`xolint` takes the one or more C files as arguments, and reports +and errors, warning, or informational messages as needed: + + ============ =================================================== + Option Meaning + ============ =================================================== + -c Invoke 'cpp' against the input file + -C <flags> Flags that are passed to 'cpp + -d Enable debug output + -D Generate documentation for all xolint messages + -I Generate info table code + -p Print the offending lines after the message + -V Print vocabulary of all field names + -X Extract samples from xolint, suitable for testing + ============ =================================================== + +The output message will contain the source filename and line number, the +class of the message, the message, and, if -p is given, the +line that contains the error:: + + % xolint.pl -t xolint.c + xolint.c: 16: error: anchor format should be "%d" + 16 xo_emit("{[:/%s}"); + +The "-I" option will generate a table of `xo_info_t`_ structures, +suitable for inclusion in source code. + +.. _xo_info_t: :ref:`field-information` + +The "-V" option does not report errors, but prints a complete list of +all field names, sorted alphabetically. The output can help spot +inconsistencies and spelling errors. |