contrib/libxo/doc/xolint.rst

   1 'A percent sign appearing in text is a literal'
   2 +++++++++++++++++++++++++++++++++++++++++++++++
   3
   4 The message "A percent sign appearing in text is a literal" can be caused by code like:
   5
   6 ::
   7
   8     xo_emit("cost: %d", cost);
   9
  10 This code should be replaced with code like:
  11
  12 ::
  13
  14     xo_emit("{L:cost}: {:cost/%d}", cost);
  15
  16 This can be a bit surprising and could be a field that was not
  17 properly converted to a libxo-style format string.
  18
  19
  20 'Unknown long name for role/modifier'
  21 +++++++++++++++++++++++++++++++++++++
  22
  23 The message "Unknown long name for role/modifier" can be caused by code like:
  24
  25 ::
  26
  27     xo_emit("{,humanization:value}", value);
  28
  29 This code should be replaced with code like:
  30
  31 ::
  32
  33     xo_emit("{,humanize:value}", value);
  34
  35 The hn-* modifiers (hn-decimal, hn-space, hn-1000)
  36 are only valid for fields with the {h:} modifier.
  37
  38
  39 'Last character before field definition is a field type'
  40 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  41
  42 The message "Last character before field definition is a field type" can be caused by code like:
  43 A common typo:
  44
  45 ::
  46
  47     xo_emit("{T:Min} T{:Max}");
  48
  49 This code should be replaced with code like:
  50
  51 ::
  52
  53     xo_emit("{T:Min} {T:Max}");
  54
  55 Twiddling the "{" and the field role is a common typo.
  56
  57
  58 'Encoding format uses different number of arguments'
  59 ++++++++++++++++++++++++++++++++++++++++++++++++++++
  60
  61 The message "Encoding format uses different number of arguments" can be caused by code like:
  62
  63 ::
  64
  65     xo_emit("{:name/%6.6s %%04d/%s}", name, number);
  66
  67 This code should be replaced with code like:
  68
  69 ::
  70
  71     xo_emit("{:name/%6.6s %04d/%s-%d}", name, number);
  72
  73 Both format should consume the same number of arguments off the stack
  74
  75
  76 'Only one field role can be used'
  77 +++++++++++++++++++++++++++++++++
  78
  79 The message "Only one field role can be used" can be caused by code like:
  80
  81 ::
  82
  83     xo_emit("{LT:Max}");
  84
  85 This code should be replaced with code like:
  86
  87 ::
  88
  89     xo_emit("{T:Max}");
  90
  91 'Potential missing slash after C, D, N, L, or T with format'
  92 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  93
  94 The message "Potential missing slash after C, D, N, L, or T with format" can be caused by code like:
  95
  96 ::
  97
  98     xo_emit("{T:%6.6s}\n", "Max");
  99
 100 This code should be replaced with code like:
 101
 102 ::
 103
 104     xo_emit("{T:/%6.6s}\n", "Max");
 105
 106 The "%6.6s" will be a literal, not a field format.  While
 107 it's possibly valid, it's likely a missing "/".
 108
 109
 110 'An encoding format cannot be given (roles: DNLT)'
 111 ++++++++++++++++++++++++++++++++++++++++++++++++++
 112
 113 The message "An encoding format cannot be given (roles: DNLT)" can be caused by code like:
 114
 115 ::
 116
 117     xo_emit("{T:Max//%s}", "Max");
 118
 119 Fields with the C, D, N, L, and T roles are not emitted in
 120 the 'encoding' style (JSON, XML), so an encoding format
 121 would make no sense.
 122
 123
 124 'Format cannot be given when content is present (roles: CDLN)'
 125 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 126
 127 The message "Format cannot be given when content is present (roles: CDLN)" can be caused by code like:
 128
 129 ::
 130
 131     xo_emit("{N:Max/%6.6s}", "Max");
 132
 133 Fields with the C, D, L, or N roles can't have both
 134 static literal content ("{L:Label}") and a
 135 format ("{L:/%s}").
 136 This error will also occur when the content has a backslash
 137 in it, like "{N:Type of I/O}"; backslashes should be escaped,
 138 like "{N:Type of I\\/O}".  Note the double backslash, one for
 139 handling 'C' strings, and one for libxo.
 140
 141
 142 'Field has color without fg- or bg- (role: C)'
 143 ++++++++++++++++++++++++++++++++++++++++++++++
 144
 145 The message "Field has color without fg- or bg- (role: C)" can be caused by code like:
 146
 147 ::
 148
 149     xo_emit("{C:green}{:foo}{C:}", x);
 150
 151 This code should be replaced with code like:
 152
 153 ::
 154
 155     xo_emit("{C:fg-green}{:foo}{C:}", x);
 156
 157 Colors must be prefixed by either "fg-" or "bg-".
 158
 159
 160 'Field has invalid color or effect (role: C)'
 161 +++++++++++++++++++++++++++++++++++++++++++++
 162
 163 The message "Field has invalid color or effect (role: C)" can be caused by code like:
 164
 165 ::
 166
 167     xo_emit("{C:fg-purple,bold}{:foo}{C:gween}", x);
 168
 169 This code should be replaced with code like:
 170
 171 ::
 172
 173     xo_emit("{C:fg-red,bold}{:foo}{C:fg-green}", x);
 174
 175 The list of colors and effects are limited.  The
 176 set of colors includes default, black, red, green,
 177 yellow, blue, magenta, cyan, and white, which must
 178 be prefixed by either "fg-" or "bg-".  Effects are
 179 limited to bold, no-bold, underline, no-underline,
 180 inverse, no-inverse, normal, and reset.  Values must
 181 be separated by commas.
 182
 183
 184 'Field has humanize modifier but no format string'
 185 ++++++++++++++++++++++++++++++++++++++++++++++++++
 186
 187 The message "Field has humanize modifier but no format string" can be caused by code like:
 188
 189 ::
 190
 191     xo_emit("{h:value}", value);
 192
 193 This code should be replaced with code like:
 194
 195 ::
 196
 197     xo_emit("{h:value/%d}", value);
 198
 199 Humanization is only value for numbers, which are not
 200 likely to use the default format ("%s").
 201
 202
 203 'Field has hn-* modifier but not 'h' modifier'
 204 ++++++++++++++++++++++++++++++++++++++++++++++
 205
 206 The message "Field has hn-* modifier but not 'h' modifier" can be caused by code like:
 207
 208 ::
 209
 210     xo_emit("{,hn-1000:value}", value);
 211
 212 This code should be replaced with code like:
 213
 214 ::
 215
 216     xo_emit("{h,hn-1000:value}", value);
 217
 218 The hn-* modifiers (hn-decimal, hn-space, hn-1000)
 219 are only valid for fields with the {h:} modifier.
 220
 221
 222 'Value field must have a name (as content)")'
 223 +++++++++++++++++++++++++++++++++++++++++++++
 224
 225 The message "Value field must have a name (as content)")" can be caused by code like:
 226
 227 ::
 228
 229     xo_emit("{:/%s}", "value");
 230
 231 This code should be replaced with code like:
 232
 233 ::
 234
 235     xo_emit("{:tag-name/%s}", "value");
 236
 237 The field name is used for XML and JSON encodings.  These
 238 tags names are static and must appear directly in the
 239 field descriptor.
 240
 241
 242 'Use hyphens, not underscores, for value field name'
 243 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 244
 245 The message "Use hyphens, not underscores, for value field name" can be caused by code like:
 246
 247 ::
 248
 249     xo_emit("{:no_under_scores}", "bad");
 250
 251 This code should be replaced with code like:
 252
 253 ::
 254
 255     xo_emit("{:no-under-scores}", "bad");
 256
 257 Use of hyphens is traditional in XML, and the XOF_UNDERSCORES
 258 flag can be used to generate underscores in JSON, if desired.
 259 But the raw field name should use hyphens.
 260
 261
 262 'Value field name cannot start with digit'
 263 ++++++++++++++++++++++++++++++++++++++++++
 264
 265 The message "Value field name cannot start with digit" can be caused by code like:
 266
 267 ::
 268
 269     xo_emit("{:10-gig/}");
 270
 271 This code should be replaced with code like:
 272
 273 ::
 274
 275     xo_emit("{:ten-gig/}");
 276
 277 XML element names cannot start with a digit.
 278
 279
 280 'Value field name should be lower case'
 281 +++++++++++++++++++++++++++++++++++++++
 282
 283 The message "Value field name should be lower case" can be caused by code like:
 284
 285 ::
 286
 287     xo_emit("{:WHY-ARE-YOU-SHOUTING}", "NO REASON");
 288
 289 This code should be replaced with code like:
 290
 291 ::
 292
 293     xo_emit("{:why-are-you-shouting}", "no reason");
 294
 295 Lower case is more civilized.  Even TLAs should be lower case
 296 to avoid scenarios where the differences between "XPath" and
 297 "Xpath" drive your users crazy.  Lower case rules the seas.
 298
 299
 300 'Value field name should be longer than two characters'
 301 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 302
 303 The message "Value field name should be longer than two characters" can be caused by code like:
 304
 305 ::
 306
 307     xo_emit("{:x}", "mumble");
 308
 309 This code should be replaced with code like:
 310
 311 ::
 312
 313     xo_emit("{:something-meaningful}", "mumble");
 314
 315 Field names should be descriptive, and it's hard to
 316 be descriptive in less than two characters.  Consider
 317 your users and try to make something more useful.
 318 Note that this error often occurs when the field type
 319 is placed after the colon ("{:T/%20s}"), instead of before
 320 it ("{T:/20s}").
 321
 322
 323 'Value field name contains invalid character'
 324 +++++++++++++++++++++++++++++++++++++++++++++
 325
 326 The message "Value field name contains invalid character" can be caused by code like:
 327
 328 ::
 329
 330     xo_emit("{:cost-in-$$/%u}", 15);
 331
 332 This code should be replaced with code like:
 333
 334 ::
 335
 336     xo_emit("{:cost-in-dollars/%u}", 15);
 337
 338 An invalid character is often a sign of a typo, like "{:]}"
 339 instead of "{]:}".  Field names are restricted to lower-case
 340 characters, digits, and hyphens.
 341
 342
 343 'decoration field contains invalid character'
 344 +++++++++++++++++++++++++++++++++++++++++++++
 345
 346 The message "decoration field contains invalid character" can be caused by code like:
 347
 348 ::
 349
 350     xo_emit("{D:not good}");
 351
 352 This code should be replaced with code like:
 353
 354 ::
 355
 356     xo_emit("{D:((}{:good}{D:))}", "yes");
 357
 358 This is minor, but fields should use proper roles.  Decoration
 359 fields are meant to hold punctuation and other characters used
 360 to decorate the content, typically to make it more readable
 361 to human readers.
 362
 363
 364 'Anchor content should be decimal width'
 365 ++++++++++++++++++++++++++++++++++++++++
 366
 367 The message "Anchor content should be decimal width" can be caused by code like:
 368
 369 ::
 370
 371     xo_emit("{[:mumble}");
 372
 373 This code should be replaced with code like:
 374
 375 ::
 376
 377     xo_emit("{[:32}");
 378
 379 Anchors need an integer value to specify the width of
 380 the set of anchored fields.  The value can be positive
 381 (for left padding/right justification) or negative (for
 382 right padding/left justification) and can appear in
 383 either the start or stop anchor field descriptor.
 384
 385
 386 'Anchor format should be "%d"'
 387 ++++++++++++++++++++++++++++++
 388
 389 The message "Anchor format should be "%d"" can be caused by code like:
 390
 391 ::
 392
 393     xo_emit("{[:/%s}");
 394
 395 This code should be replaced with code like:
 396
 397 ::
 398
 399     xo_emit("{[:/%d}");
 400
 401 Anchors only grok integer values, and if the value is not static,
 402 if must be in an 'int' argument, represented by the "%d" format.
 403 Anything else is an error.
 404
 405
 406 'Anchor cannot have both format and encoding format")'
 407 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 408
 409 The message "Anchor cannot have both format and encoding format")" can be caused by code like:
 410
 411 ::
 412
 413     xo_emit("{[:32/%d}");
 414
 415 This code should be replaced with code like:
 416
 417 ::
 418
 419     xo_emit("{[:32}");
 420
 421 Anchors can have a static value or argument for the width,
 422 but cannot have both.
 423
 424
 425 'Max width only valid for strings'
 426 ++++++++++++++++++++++++++++++++++
 427
 428 The message "Max width only valid for strings" can be caused by code like:
 429
 430 ::
 431
 432     xo_emit("{:tag/%2.4.6d}", 55);
 433
 434 This code should be replaced with code like:
 435
 436 ::
 437
 438     xo_emit("{:tag/%2.6d}", 55);
 439
 440 libxo allows a true 'max width' in addition to the traditional
 441 printf-style 'max number of bytes to use for input'.  But this
 442 is supported only for string values, since it makes no sense
 443 for non-strings.  This error may occur from a typo,
 444 like "{:tag/%6..6d}" where only one period should be used.