76afb20c58
- move from "oxtradoc" to RST/Sphinx documentation - new "csv" encoder, which allows path and leaf lists - address warnings from PVS-Stdio tool - add "xolint" detected errors to the documentation
445 lines
10 KiB
ReStructuredText
445 lines
10 KiB
ReStructuredText
'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.
|