1.\" # 2.\" # Copyright (c) 2014, Juniper Networks, Inc. 3.\" # All rights reserved. 4.\" # This SOFTWARE is licensed under the LICENSE provided in the 5.\" # ../Copyright file. By downloading, installing, copying, or 6.\" # using the SOFTWARE, you agree to be bound by the terms of that 7.\" # LICENSE. 8.\" # Phil Shafer, July 2014 9.\" 10.Dd December 4, 2014 11.Dt LIBXO 3 12.Os 13.Sh NAME 14.Nm xo_format 15.Nd content of format descriptors for xo_emit 16.Sh DESCRIPTION 17.Pp 18.Nm libxo 19uses format strings to control the rendering of data into 20various output styles, including 21.Em text , 22.Em XML , 23.Em JSON , 24and 25.Em HTML . 26Each format string contains a set of zero or more 27.Dq "field descriptions" , 28which describe independent data fields. 29Each field description contains a set of 30.Dq modifiers , 31a 32.Dq "content string" , 33and zero, one, or two 34.Dq "format descriptors" . 35The modifiers tell 36.Nm libxo 37what the field is and how to treat it, while the format descriptors are 38formatting instructions using 39.Xr printf 3 Ns -style 40format strings, telling 41.Nm libxo 42how to format the field. 43The field description is placed inside 44a set of braces, with a colon 45.Ql ( \&: ) 46after the modifiers and a slash 47.Ql ( \&/ ) 48before each format descriptors. 49Text may be intermixed with 50field descriptions within the format string. 51.Pp 52The field description is given as follows: 53.Bd -literal -offset indent 54 \(aq{\(aq [ role | modifier ]* [\(aq,\(aq long\-names ]* \(aq:\(aq [ content ] 55 [ \(aq/\(aq field\-format [ \(aq/\(aq encoding\-format ]] \(aq}\(aq 56.Ed 57.Pp 58The role describes the function of the field, while the modifiers 59enable optional behaviors. 60The contents, field\-format, and 61encoding\-format are used in varying ways, based on the role. 62These are described in the following sections. 63.Pp 64Braces can be escaped by using double braces, similar to "%%" in 65.Xr printf 3 . 66The format string "{{braces}}" would emit "{braces}". 67.Pp 68In the following example, three field descriptors appear. 69The first 70is a padding field containing three spaces of padding, the second is a 71label ("In stock"), and the third is a value field ("in\-stock"). 72The in\-stock field has a "%u" format that will parse the next argument 73passed to the 74.Xr xo_emit 3 , 75function as an unsigned integer. 76.Bd -literal -offset indent 77 xo_emit("{P: }{Lwc:In stock}{:in\-stock/%u}\\n", 65); 78.Ed 79.Pp 80This single line of code can generate text ("In stock: 65\\n"), XML 81("<in\-stock>65</in\-stock>"), JSON (\(aq"in\-stock": 65\(aq), or HTML (too 82lengthy to be listed here). 83.Pp 84While roles and modifiers typically use single character for brevity, 85there are alternative names for each which allow more verbose 86formatting strings. 87These names must be preceded by a comma, and may follow any 88single\-character values: 89.Bd -literal -offset indent 90 xo_emit("{L,white,colon:In stock}{,key:in\-stock/%u}\\n", 65); 91.Ed 92.Ss "Field Roles" 93Field roles are optional, and indicate the role and formatting of the 94content. 95The roles are listed below; only one role is permitted: 96.Bl -column "M" "Name12341234" 97.It Sy "M" "Name " "Description" 98.It C "color " "Field is a color or effect" 99.It D "decoration " "Field is non\-text (e.g. colon, comma)" 100.It E "error " "Field is an error message" 101.It L "label " "Field is text that prefixes a value" 102.It N "note " "Field is text that follows a value" 103.It P "padding " "Field is spaces needed for vertical alignment" 104.It T "title " "Field is a title value for headings" 105.It U "units " "Field is the units for the previous value field" 106.It V "value " "Field is the name of field (the default)" 107.It W "warning " "Field is a warning message" 108.It \&[ "start\-anchor" "Begin a section of anchored variable\-width text" 109.It \&] "stop\-anchor " "End a section of anchored variable\-width text" 110.El 111.Bd -literal -offset indent 112 EXAMPLE: 113 xo_emit("{L:Free}{D::}{P: }{:free/%u} {U:Blocks}\\n", 114 free_blocks); 115.Ed 116.Pp 117When a role is not provided, the "value" role is used as the default. 118.Pp 119Roles and modifiers can also use more verbose names, when preceded by 120a comma: 121.Bd -literal -offset indent 122 EXAMPLE: 123 xo_emit("{,label:Free}{,decoration::}{,padding: }" 124 "{,value:free/%u} {,units:Blocks}\\n", 125 free_blocks); 126.Ed 127.Ss "The Color Role ({C:})" 128Colors and effects control how text values are displayed; they are 129used for display styles (TEXT and HTML). 130.Bd -literal -offset indent 131 xo_emit("{C:bold}{:value}{C:no\-bold}\\n", value); 132.Ed 133.Pp 134Colors and effects remain in effect until modified by other "C"\-role 135fields. 136.Bd -literal -offset indent 137 xo_emit("{C:bold}{C:inverse}both{C:no\-bold}only inverse\\n"); 138.Ed 139.Pp 140If the content is empty, the "reset" action is performed. 141.Bd -literal -offset indent 142 xo_emit("{C:both,underline}{:value}{C:}\\n", value); 143.Ed 144.Pp 145The content should be a comma\-separated list of zero or more colors or 146display effects. 147.Bd -literal -offset indent 148 xo_emit("{C:bold,underline,inverse}All three{C:no\-bold,no\-inverse}\\n"); 149.Ed 150.Pp 151The color content can be either static, when placed directly within 152the field descriptor, or a printf\-style format descriptor can be used, 153if preceded by a slash ("/"): 154.Bd -literal -offset indent 155 xo_emit("{C:/%s%s}{:value}{C:}", need_bold ? "bold" : "", 156 need_underline ? "underline" : "", value); 157.Ed 158.Pp 159Color names are prefixed with either "fg\-" or "bg\-" to change the 160foreground and background colors, respectively. 161.Bd -literal -offset indent 162 xo_emit("{C:/fg\-%s,bg\-%s}{Lwc:Cost}{:cost/%u}{C:reset}\\n", 163 fg_color, bg_color, cost); 164.Ed 165.Pp 166The following table lists the supported effects: 167.Bl -column "no\-underline" 168.It Sy "Name " "Description" 169.It "bg\-xxxxx " "Change background color" 170.It "bold " "Start bold text effect" 171.It "fg\-xxxxx " "Change foreground color" 172.It "inverse " "Start inverse (aka reverse) text effect" 173.It "no\-bold " "Stop bold text effect" 174.It "no\-inverse " "Stop inverse (aka reverse) text effect" 175.It "no\-underline " "Stop underline text effect" 176.It "normal " "Reset effects (only)" 177.It "reset " "Reset colors and effects (restore defaults)" 178.It "underline " "Start underline text effect" 179.El 180.Pp 181The following color names are supported: 182.Bl -column "no\-underline" 183.It Sy "Name" 184.It black 185.It blue 186.It cyan 187.It default 188.It green 189.It magenta 190.It red 191.It white 192.It yellow 193.El 194.Ss "The Decoration Role ({D:})" 195Decorations are typically punctuation marks such as colons, 196semi\-colons, and commas used to decorate the text and make it simpler 197for human readers. 198By marking these distinctly, HTML usage scenarios 199can use CSS to direct their display parameters. 200.Bd -literal -offset indent 201 xo_emit("{D:((}{:name}{D:))}\\n", name); 202.Ed 203.Ss "The Gettext Role ({G:})" 204.Nm libxo 205supports internationalization (i18n) through its use of 206.Xr gettext 3 . 207Use the "{G:}" role to request that the remaining part of 208the format string, following the "{G:}" field, be handled using 209.Fn gettext . 210Since 211.Fn gettext 212uses the string as the key into the message catalog, 213.Nm libxo 214uses a simplified version of the format string that removes 215unimportant field formatting and modifiers, stopping minor formatting 216changes from impacting the expensive translation process. 217A developer 218change such as changing "/%06d" to "/%08d" should not force hand 219inspection of all .po files. 220.Pp 221The simplified version can be generated for a single message using the 222"xopo \-s <text>" command, or an entire .pot can be translated using 223the "xopo \-f <input> \-o <output>" command. 224.Bd -literal -offset indent 225 xo_emit("{G:}Invalid token\\n"); 226.Ed 227.Pp 228The {G:} role allows a domain name to be set. 229.Fn gettext 230calls will 231continue to use that domain name until the current format string 232processing is complete, enabling a library function to emit strings 233using it\(aqs own catalog. 234The domain name can be either static as the 235content of the field, or a format can be used to get the domain name 236from the arguments. 237.Bd -literal -offset indent 238 xo_emit("{G:libc}Service unavailable in restricted mode\\n"); 239.Ed 240.Ss "The Label Role ({L:})" 241Labels are text that appears before a value. 242.Bd -literal -offset indent 243 xo_emit("{Lwc:Cost}{:cost/%u}\\n", cost); 244.Ed 245.Ss "The Note Role ({N:})" 246Notes are text that appears after a value. 247.Bd -literal -offset indent 248 xo_emit("{:cost/%u} {N:per year}\\n", cost); 249.Ed 250.Ss "The Padding Role ({P:})" 251Padding represents whitespace used before and between fields. 252The padding content can be either static, when placed directly within 253the field descriptor, or a printf\-style format descriptor can be used, 254if preceded by a slash ("/"): 255.Bd -literal -offset indent 256 xo_emit("{P: }{Lwc:Cost}{:cost/%u}\\n", cost); 257 xo_emit("{P:/30s}{Lwc:Cost}{:cost/%u}\\n", "", cost); 258.Ed 259.Ss "The Title Role ({T:})" 260Titles are heading or column headers that are meant to be displayed to 261the user. 262The title can be either static, when placed directly within 263the field descriptor, or a printf\-style format descriptor can be used, 264if preceded by a slash ("/"): 265.Bd -literal -offset indent 266 xo_emit("{T:Interface Statistics}\\n"); 267 xo_emit("{T:/%20.20s}{T:/%6.6s}\\n", "Item Name", "Cost"); 268.Ed 269.Ss "The Units Role ({U:})" 270Units are the dimension by which values are measured, such as degrees, 271miles, bytes, and decibels. 272The units field carries this information 273for the previous value field. 274.Bd -literal -offset indent 275 xo_emit("{Lwc:Distance}{:distance/%u}{Uw:miles}\\n", miles); 276.Ed 277.Pp 278Note that the sense of the \(aqw\(aq modifier is reversed for units; 279a blank is added before the contents, rather than after it. 280.Pp 281When the 282.Dv XOF_UNITS 283flag is set, units are rendered in XML as the 284.Dq units 285attribute: 286.Bd -literal -offset indent 287 <distance units="miles">50</distance> 288.Ed 289.Pp 290Units can also be rendered in HTML as the "data\-units" attribute: 291.Bd -literal -offset indent 292 <div class="data" data\-tag="distance" data\-units="miles" 293 data\-xpath="/top/data/distance">50</div> 294.Ed 295.Ss "The Value Role ({V:} and {:})" 296The value role is used to represent the a data value that is 297interesting for the non\-display output styles (XML and JSON). 298Value 299is the default role; if no other role designation is given, the field 300is a value. 301The field name must appear within the field descriptor, 302followed by one or two format descriptors. 303The first format 304descriptor is used for display styles (TEXT and HTML), while the 305second one is used for encoding styles (XML and JSON). 306If no second 307format is given, the encoding format defaults to the first format, 308with any minimum width removed. 309If no first format is given, both 310format descriptors default to "%s". 311.Bd -literal -offset indent 312 xo_emit("{:length/%02u}x{:width/%02u}x{:height/%02u}\\n", 313 length, width, height); 314 xo_emit("{:author} wrote \"{:poem}\" in {:year/%4d}\\n, 315 author, poem, year); 316.Ed 317.Ss "The Anchor Roles ({[:} and {]:})" 318The anchor roles allow a set of strings by be padded as a group, 319but still be visible to 320.Xr xo_emit 3 321as distinct fields. 322Either the start 323or stop anchor can give a field width and it can be either directly in 324the descriptor or passed as an argument. 325Any fields between the start 326and stop anchor are padded to meet the minimum width given. 327.Pp 328To give a width directly, encode it as the content of the anchor tag: 329.Bd -literal -offset indent 330 xo_emit("({[:10}{:min/%d}/{:max/%d}{]:})\\n", min, max); 331.Ed 332.Pp 333To pass a width as an argument, use "%d" as the format, which must 334appear after the "/". 335Note that only "%d" is supported for widths. 336Using any other value could ruin your day. 337.Bd -literal -offset indent 338 xo_emit("({[:/%d}{:min/%d}/{:max/%d}{]:})\\n", width, min, max); 339.Ed 340.Pp 341If the width is negative, padding will be added on the right, suitable 342for left justification. 343Otherwise the padding will be added to the 344left of the fields between the start and stop anchors, suitable for 345right justification. 346If the width is zero, nothing happens. 347If the 348number of columns of output between the start and stop anchors is less 349than the absolute value of the given width, nothing happens. 350.Pp 351Widths over 8k are considered probable errors and not supported. 352If 353.Dv XOF_WARN 354is set, a warning will be generated. 355.Ss "Field Modifiers" 356Field modifiers are flags which modify the way content emitted for 357particular output styles: 358.Bl -column M "Name123456789" 359.It Sy M "Name " "Description" 360.It a "argument " "The content appears as a ""const char *"" argument" 361.It c "colon " "A colon ("":"") is appended after the label" 362.It d "display " "Only emit field for display styles (text/HTML)" 363.It e "encoding " "Only emit for encoding styles (XML/JSON)" 364.It h "humanize (hn) " "Format large numbers in human\-readable style" 365.It " " "hn\-space " "Humanize: Place space between numeric and unit" 366.It " " "hn\-decimal " "Humanize: Add a decimal digit, if number < 10" 367.It " " "hn\-1000 " "Humanize: Use 1000 as divisor instead of 1024" 368.It k "key " "Field is a key, suitable for XPath predicates" 369.It l "leaf\-list " "Field is a leaf\-list, a list of leaf values" 370.It n "no\-quotes " "Do not quote the field when using JSON style" 371.It q "quotes " "Quote the field when using JSON style" 372.It t "trim " "Trim leading and trailing whitespace" 373.It w "white space " "A blank ("" "") is appended after the label" 374.El 375.Pp 376For example, the modifier string "Lwc" means the field has a label 377role (text that describes the next field) and should be followed by a 378colon (\(aqc\(aq) and a space (\(aqw\(aq). 379The modifier string "Vkq" means the 380field has a value role, that it is a key for the current instance, and 381that the value should be quoted when encoded for JSON. 382.Pp 383Roles and modifiers can also use more verbose names, when preceded by 384a comma. 385For example, the modifier string "Lwc" (or "L,white,colon") 386means the field has a label role (text that describes the next field) 387and should be followed by a colon (\(aqc\(aq) and a space (\(aqw\(aq). 388The modifier string "Vkq" (or ":key,quote") means the field has a value 389role (the default role), that it is a key for the current instance, 390and that the value should be quoted when encoded for JSON. 391.Ss "The Argument Modifier ({a:})" 392The argument modifier indicates that the content of the field 393descriptor will be placed as a UTF\-8 string (const char *) argument 394within the xo_emit parameters. 395.Bd -literal -offset indent 396 EXAMPLE: 397 xo_emit("{La:} {a:}\\n", "Label text", "label", "value"); 398 TEXT: 399 Label text value 400 JSON: 401 "label": "value" 402 XML: 403 <label>value</label> 404.Ed 405.Pp 406The argument modifier allows field names for value fields to be passed 407on the stack, avoiding the need to build a field descriptor using 408.Xr snprintf 1 . 409For many field roles, the argument modifier is not needed, 410since those roles have specific mechanisms for arguments, 411such as "{C:fg\-%s}". 412.Ss "The Colon Modifier ({c:})" 413The colon modifier appends a single colon to the data value: 414.Bd -literal -offset indent 415 EXAMPLE: 416 xo_emit("{Lc:Name}{:name}\\n", "phil"); 417 TEXT: 418 Name:phil 419.Ed 420.Pp 421The colon modifier is only used for the TEXT and HTML output 422styles. 423It is commonly combined with the space modifier (\(aq{w:}\(aq). 424It is purely a convenience feature. 425.Ss "The Display Modifier ({d:})" 426The display modifier indicated the field should only be generated for 427the display output styles, TEXT and HTML. 428.Bd -literal -offset indent 429 EXAMPLE: 430 xo_emit("{Lcw:Name}{d:name} {:id/%d}\\n", "phil", 1); 431 TEXT: 432 Name: phil 1 433 XML: 434 <id>1</id> 435.Ed 436.Pp 437The display modifier is the opposite of the encoding modifier, and 438they are often used to give to distinct views of the underlying data. 439.Ss "The Encoding Modifier ({e:})" 440The encoding modifier indicated the field should only be generated for 441the encoding output styles, such as JSON and XML. 442.Bd -literal -offset indent 443 EXAMPLE: 444 xo_emit("{Lcw:Name}{:name} {e:id/%d}\\n", "phil", 1); 445 TEXT: 446 Name: phil 447 XML: 448 <name>phil</name><id>1</id> 449.Ed 450.Pp 451The encoding modifier is the opposite of the display modifier, and 452they are often used to give to distinct views of the underlying data. 453.Ss "The Humanize Modifier ({h:})" 454The humanize modifier is used to render large numbers as in a 455human\-readable format. 456While numbers like "44470272" are completely readable to computers and 457savants, humans will generally find "44M" more meaningful. 458.Pp 459"hn" can be used as an alias for "humanize". 460.Pp 461The humanize modifier only affects display styles (TEXT and HMTL). 462The "no\-humanize" option will block the function of the humanize modifier. 463.Pp 464There are a number of modifiers that affect details of humanization. 465These are only available in as full names, not single characters. 466The "hn\-space" modifier places a space between the number and any 467multiplier symbol, such as "M" or "K" (ex: "44 K"). 468The "hn\-decimal" modifier will add a decimal point and a single tenths digit 469when the number is less than 10 (ex: "4.4K"). 470The "hn\-1000" modifier will use 1000 as divisor instead of 1024, following the 471JEDEC\-standard instead of the more natural binary powers\-of\-two 472tradition. 473.Bd -literal -offset indent 474 EXAMPLE: 475 xo_emit("{h:input/%u}, {h,hn\-space:output/%u}, " 476 "{h,hn\-decimal:errors/%u}, {h,hn\-1000:capacity/%u}, " 477 "{h,hn\-decimal:remaining/%u}\\n", 478 input, output, errors, capacity, remaining); 479 TEXT: 480 21, 57 K, 96M, 44M, 1.2G 481.Ed 482.Pp 483In the HTML style, the original numeric value is rendered in the 484"data\-number" attribute on the <div> element: 485.Bd -literal -offset indent 486 <div class="data" data\-tag="errors" 487 data\-number="100663296">96M</div> 488.Ed 489.Ss "The Gettext Modifier ({g:})" 490The gettext modifier is used to translate individual fields using the 491gettext domain (typically set using the "{G:}" role) and current 492language settings. 493Once libxo renders the field value, it is passed 494to 495.Xr gettext 3 , 496where it is used as a key to find the native language 497translation. 498.Pp 499In the following example, the strings "State" and "full" are passed 500to 501.Fn gettext 502to find locale\-based translated strings. 503.Bd -literal -offset indent 504 xo_emit("{Lgwc:State}{g:state}\\n", "full"); 505.Ed 506.Ss "The Key Modifier ({k:})" 507The key modifier is used to indicate that a particular field helps 508uniquely identify an instance of list data. 509.Bd -literal -offset indent 510 EXAMPLE: 511 xo_open_list("user"); 512 for (i = 0; i < num_users; i++) { 513 xo_open_instance("user"); 514 xo_emit("User {k:name} has {:count} tickets\\n", 515 user[i].u_name, user[i].u_tickets); 516 xo_close_instance("user"); 517 } 518 xo_close_list("user"); 519.Ed 520.Pp 521Currently the key modifier is only used when generating XPath values 522for the HTML output style when 523.Dv XOF_XPATH 524is set, but other uses are likely in the near future. 525.Ss "The Leaf\-List Modifier ({l:})" 526The leaf\-list modifier is used to distinguish lists where each 527instance consists of only a single value. In XML, these are 528rendered as single elements, where JSON renders them as arrays. 529.Bd -literal -offset indent 530 EXAMPLE: 531 xo_open_list("user"); 532 for (i = 0; i < num_users; i++) { 533 xo_emit("Member {l:name}\\n", user[i].u_name); 534 } 535 xo_close_list("user"); 536 XML: 537 <user>phil</user> 538 <user>pallavi</user> 539 JSON: 540 "user": [ "phil", "pallavi" ] 541.Ed 542.Ss "The No\-Quotes Modifier ({n:})" 543The no\-quotes modifier (and its twin, the \(aqquotes\(aq modifier) affect 544the quoting of values in the JSON output style. 545JSON uses quotes for 546string values, but no quotes for numeric, boolean, and null data. 547.Xr xo_emit 3 548applies a simple heuristic to determine whether quotes are 549needed, but often this needs to be controlled by the caller. 550.Bd -literal -offset indent 551 EXAMPLE: 552 const char *bool = is_true ? "true" : "false"; 553 xo_emit("{n:fancy/%s}", bool); 554 JSON: 555 "fancy": true 556.Ed 557.Ss "The Plural Modifier ({p:})" 558The plural modifier selects the appropriate plural form of an 559expression based on the most recent number emitted and the current 560language settings. 561The contents of the field should be the singular 562and plural English values, separated by a comma: 563.Bd -literal -offset indent 564 xo_emit("{:bytes} {Ngp:byte,bytes}\\n", bytes); 565.Ed 566.Pp 567The plural modifier is meant to work with the gettext modifier ({g:}) 568but can work independently. 569.Pp 570When used without the gettext modifier or when the message does not 571appear in the message catalog, the first token is chosen when the last 572numeric value is equal to 1; otherwise the second value is used, 573mimicking the simple pluralization rules of English. 574.Pp 575When used with the gettext modifier, the 576.Xr ngettext 3 577function is 578called to handle the heavy lifting, using the message catalog to 579convert the singular and plural forms into the native language. 580.Ss "The Quotes Modifier ({q:})" 581The quotes modifier (and its twin, the \(aqno-quotes\(aq modifier) affect 582the quoting of values in the JSON output style. 583JSON uses quotes for 584string values, but no quotes for numeric, boolean, and null data. 585.Xr xo_emit 3 586applies a simple heuristic to determine whether quotes are 587needed, but often this needs to be controlled by the caller. 588.Bd -literal -offset indent 589 EXAMPLE: 590 xo_emit("{q:time/%d}", 2014); 591 JSON: 592 "year": "2014" 593.Ed 594.Ss "The White Space Modifier ({w:})" 595The white space modifier appends a single space to the data value: 596.Bd -literal -offset indent 597 EXAMPLE: 598 xo_emit("{Lw:Name}{:name}\\n", "phil"); 599 TEXT: 600 Name phil 601.Ed 602.Pp 603The white space modifier is only used for the TEXT and HTML output 604styles. 605It is commonly combined with the colon modifier (\(aq{c:}\(aq). 606It is purely a convenience feature. 607.Pp 608Note that the sense of the \(aqw\(aq modifier is reversed for the units role 609({Uw:}); a blank is added before the contents, rather than after it. 610.Ss "Field Formatting" 611The field format is similar to the format string for 612.Xr printf 3 . 613Its use varies based on the role of the field, but generally is used to 614format the field\(aqs contents. 615.Pp 616If the format string is not provided for a value field, it defaults 617to "%s". 618.Pp 619Note a field definition can contain zero or more printf\-style 620.Dq directives , 621which are sequences that start with a \(aq%\(aq and end with 622one of following characters: "diouxXDOUeEfFgGaAcCsSp". 623Each directive 624is matched by one of more arguments to the 625.Xr xo_emit 3 626function. 627.Pp 628The format string has the form: 629.Bd -literal -offset indent 630 \(aq%\(aq format\-modifier * format\-character 631.Ed 632.Pp 633The format\-modifier can be: 634.Bl -bullet 635.It 636a \(aq#\(aq character, indicating the output value should be prefixed with 637"0x", typically to indicate a base 16 (hex) value. 638.It 639a minus sign (\(aq\-\(aq), indicating the output value should be padded on 640the right instead of the left. 641.It 642a leading zero (\(aq0\(aq) indicating the output value should be padded on the 643left with zeroes instead of spaces (\(aq \(aq). 644.It 645one or more digits (\(aq0\(aq \- \(aq9\(aq) indicating the minimum width of the 646argument. 647If the width in columns of the output value is less than 648the minimum width, the value will be padded to reach the minimum. 649.It 650a period followed by one or more digits indicating the maximum 651number of bytes which will be examined for a string argument, or the maximum 652width for a non\-string argument. 653When handling ASCII strings this 654functions as the field width but for multi\-byte characters, a single 655character may be composed of multiple bytes. 656.Xr xo_emit 3 657will never dereference memory beyond the given number of bytes. 658.It 659a second period followed by one or more digits indicating the maximum 660width for a string argument. 661This modifier cannot be given for non\-string arguments. 662.It 663one or more \(aqh\(aq characters, indicating shorter input data. 664.It 665one or more \(aql\(aq characters, indicating longer input data. 666.It 667a \(aqz\(aq character, indicating a \(aqsize_t\(aq argument. 668.It 669a \(aqt\(aq character, indicating a \(aqptrdiff_t\(aq argument. 670.It 671a \(aq \(aq character, indicating a space should be emitted before 672positive numbers. 673.It 674a \(aq+\(aq character, indicating sign should emitted before any number. 675.El 676.Pp 677Note that \(aqq\(aq, \(aqD\(aq, \(aqO\(aq, and \(aqU\(aq are considered deprecated and will be 678removed eventually. 679.Pp 680The format character is described in the following table: 681.Bl -column C "Argument Type12" 682.It Sy "C" "Argument Type " "Format" 683.It d "int " "base 10 (decimal)" 684.It i "int " "base 10 (decimal)" 685.It o "int " "base 8 (octal)" 686.It u "unsigned " "base 10 (decimal)" 687.It x "unsigned " "base 16 (hex)" 688.It X "unsigned long " "base 16 (hex)" 689.It D "long " "base 10 (decimal)" 690.It O "unsigned long " "base 8 (octal)" 691.It U "unsigned long " "base 10 (decimal)" 692.It e "double " "[\-]d.ddde+\-dd" 693.It E "double " "[\-]d.dddE+\-dd" 694.It f "double " "[\-]ddd.ddd" 695.It F "double " "[\-]ddd.ddd" 696.It g "double " "as \(aqe\(aq or \(aqf\(aq" 697.It G "double " "as \(aqE\(aq or \(aqF\(aq" 698.It a "double " "[\-]0xh.hhhp[+\-]d" 699.It A "double " "[\-]0Xh.hhhp[+\-]d" 700.It c "unsigned char " "a character" 701.It C "wint_t " "a character" 702.It s "char * " "a UTF\-8 string" 703.It S "wchar_t * " "a unicode/WCS string" 704.It p "void * " "\(aq%#lx\(aq" 705.El 706.Pp 707The \(aqh\(aq and \(aql\(aq modifiers affect the size and treatment of the 708argument: 709.Bl -column "Mod" "d, i " "o, u, x, X " 710.It Sy "Mod" "d, i " "o, u, x, X" 711.It "hh " "signed char " "unsigned char" 712.It "h " "short " "unsigned short" 713.It "l " "long " "unsigned long" 714.It "ll " "long long " "unsigned long long" 715.It "j " "intmax_t " "uintmax_t" 716.It "t " "ptrdiff_t " "ptrdiff_t" 717.It "z " "size_t " "size_t" 718.It "q " "quad_t " "u_quad_t" 719.El 720.Ss "UTF\-8 and Locale Strings" 721All strings for 722.Nm libxo 723must be UTF\-8. 724.Nm libxo 725will handle turning them 726into locale\-based strings for display to the user. 727.Pp 728For strings, the \(aqh\(aq and \(aql\(aq modifiers affect the interpretation of 729the bytes pointed to argument. 730The default \(aq%s\(aq string is a \(aqchar *\(aq 731pointer to a string encoded as UTF\-8. 732Since UTF\-8 is compatible with 733.Em ASCII 734data, a normal 7\-bit 735.Em ASCII 736string can be used. 737"%ls" expects a 738"wchar_t *" pointer to a wide\-character string, encoded as 32\-bit 739Unicode values. 740"%hs" expects a "char *" pointer to a multi\-byte 741string encoded with the current locale, as given by the 742.Ev LC_CTYPE , 743.Ev LANG , 744or 745.Ev LC_ALL 746environment variables. 747The first of this list of 748variables is used and if none of the variables are set, the locale defaults to 749.Em UTF\-8 . 750.Pp 751.Nm libxo 752will 753convert these arguments as needed to either UTF\-8 (for XML, JSON, and 754HTML styles) or locale\-based strings for display in text style. 755.Bd -literal -offset indent 756 xo_emit("All strings are utf\-8 content {:tag/%ls}", 757 L"except for wide strings"); 758.Ed 759.Pp 760"%S" is equivalent to "%ls". 761.Pp 762For example, a function is passed a locale\-base name, a hat size, 763and a time value. 764The hat size is formatted in a UTF\-8 (ASCII) 765string, and the time value is formatted into a wchar_t string. 766.Bd -literal -offset indent 767 void print_order (const char *name, int size, 768 struct tm *timep) { 769 char buf[32]; 770 const char *size_val = "unknown"; 771 772 if (size > 0) 773 snprintf(buf, sizeof(buf), "%d", size); 774 size_val = buf; 775 } 776 777 wchar_t when[32]; 778 wcsftime(when, sizeof(when), L"%d%b%y", timep); 779 780 xo_emit("The hat for {:name/%hs} is {:size/%s}.\\n", 781 name, size_val); 782 xo_emit("It was ordered on {:order\-time/%ls}.\\n", 783 when); 784 } 785.Ed 786.Pp 787It is important to note that 788.Xr xo_emit 3 789will perform the conversion 790required to make appropriate output. 791Text style output uses the 792current locale (as described above), while XML, JSON, and HTML use 793UTF\-8. 794.Pp 795UTF\-8 and locale\-encoded strings can use multiple bytes to encode one 796column of data. 797The traditional "precision" (aka "max\-width") value 798for "%s" printf formatting becomes overloaded since it specifies both 799the number of bytes that can be safely referenced and the maximum 800number of columns to emit. 801.Xr xo_emit 3 802uses the precision as the former, 803and adds a third value for specifying the maximum number of columns. 804.Pp 805In this example, the name field is printed with a minimum of 3 columns 806and a maximum of 6. 807Up to ten bytes are in used in filling those columns. 808.Bd -literal -offset indent 809 xo_emit("{:name/%3.10.6s}", name); 810.Ed 811.Ss "Characters Outside of Field Definitions" 812Characters in the format string that are not part of a field definition are 813copied to the output for the TEXT style, and are ignored for the JSON 814and XML styles. 815For HTML, these characters are placed in a <div> with class "text". 816.Bd -literal -offset indent 817 EXAMPLE: 818 xo_emit("The hat is {:size/%s}.\\n", size_val); 819 TEXT: 820 The hat is extra small. 821 XML: 822 <size>extra small</size> 823 JSON: 824 "size": "extra small" 825 HTML: 826 <div class="text">The hat is </div> 827 <div class="data" data\-tag="size">extra small</div> 828 <div class="text">.</div> 829.Ed 830.Ss "\(aq%n\(aq is Not Supported" 831.Nm libxo 832does not support the \(aq%n\(aq directive. 833It is a bad idea and we 834just do not do it. 835.Ss "The Encoding Format (eformat)" 836The "eformat" string is the format string used when encoding the field 837for JSON and XML. 838If not provided, it defaults to the primary format 839with any minimum width removed. 840If the primary is not given, both default to "%s". 841.Sh EXAMPLE 842In this example, the value for the number of items in stock is emitted: 843.Bd -literal -offset indent 844 xo_emit("{P: }{Lwc:In stock}{:in\-stock/%u}\\n", 845 instock); 846.Ed 847.Pp 848This call will generate the following output: 849.Bd -literal -offset indent 850 TEXT: 851 In stock: 144 852 XML: 853 <in\-stock>144</in\-stock> 854 JSON: 855 "in\-stock": 144, 856 HTML: 857 <div class="line"> 858 <div class="padding"> </div> 859 <div class="label">In stock</div> 860 <div class="decoration">:</div> 861 <div class="padding"> </div> 862 <div class="data" data\-tag="in\-stock">144</div> 863 </div> 864.Ed 865.Pp 866Clearly HTML wins the verbosity award, and this output does 867not include 868.Dv XOF_XPATH 869or 870.Dv XOF_INFO 871data, which would expand the penultimate line to: 872.Bd -literal -offset indent 873 <div class="data" data\-tag="in\-stock" 874 data\-xpath="/top/data/item/in\-stock" 875 data\-type="number" 876 data\-help="Number of items in stock">144</div> 877.Ed 878.Sh WHAT MAKES A GOOD FIELD NAME? 879To make useful, consistent field names, follow these guidelines: 880.Ss "Use lower case, even for TLAs" 881Lower case is more civilized. 882Even TLAs should be lower case 883to avoid scenarios where the differences between "XPath" and 884"Xpath" drive your users crazy. 885Using "xpath" is simpler and better. 886.Ss "Use hyphens, not underscores" 887Use of hyphens is traditional in XML, and the 888.Dv XOF_UNDERSCORES 889flag can be used to generate underscores in JSON, if desired. 890But the raw field name should use hyphens. 891.Ss "Use full words" 892Do not abbreviate especially when the abbreviation is not obvious or 893not widely used. 894Use "data\-size", not "dsz" or "dsize". 895Use 896"interface" instead of "ifname", "if\-name", "iface", "if", or "intf". 897.Ss "Use <verb>\-<units>" 898Using the form <verb>\-<units> or <verb>\-<classifier>\-<units> helps in 899making consistent, useful names, avoiding the situation where one app 900uses "sent\-packet" and another "packets\-sent" and another 901"packets\-we\-have\-sent". 902The <units> can be dropped when it is 903obvious, as can obvious words in the classification. 904Use "receive\-after\-window\-packets" instead of 905"received\-packets\-of\-data\-after\-window". 906.Ss "Reuse existing field names" 907Nothing is worse than writing expressions like: 908.Bd -literal -offset indent 909 if ($src1/process[pid == $pid]/name == 910 $src2/proc\-table/proc/p[process\-id == $pid]/proc\-name) { 911 ... 912 } 913.Ed 914.Pp 915Find someone else who is expressing similar data and follow their 916fields and hierarchy. 917Remember the quote is not 918.Dq "Consistency is the hobgoblin of little minds" 919but 920.Dq "A foolish consistency is the hobgoblin of little minds" . 921.Ss "Think about your users" 922Have empathy for your users, choosing clear and useful fields that 923contain clear and useful data. 924You may need to augment the display content with 925.Xr xo_attr 3 926calls or "{e:}" fields to make the data useful. 927.Ss "Do not use an arbitrary number postfix" 928What does "errors2" mean? 929No one will know. 930"errors\-after\-restart" would be a better choice. 931Think of your users, and think of the future. 932If you make "errors2", the next guy will happily make 933"errors3" and before you know it, someone will be asking what is the 934difference between errors37 and errors63. 935.Ss "Be consistent, uniform, unsurprising, and predictable" 936Think of your field vocabulary as an API. 937You want it useful, 938expressive, meaningful, direct, and obvious. 939You want the client 940application\(aqs programmer to move between without the need to 941understand a variety of opinions on how fields are named. 942They should 943see the system as a single cohesive whole, not a sack of cats. 944.Pp 945Field names constitute the means by which client programmers interact 946with our system. 947By choosing wise names now, you are making their lives better. 948.Pp 949After using 950.Xr xolint 1 951to find errors in your field descriptors, use 952.Dq "xolint \-V" 953to spell check your field names and to detect different 954names for the same data. 955.Dq dropped\-short 956and 957.Dq dropped\-too\-short 958are both reasonable names, but using them both will lead users to ask the 959difference between the two fields. 960If there is no difference, 961use only one of the field names. 962If there is a difference, change the 963names to make that difference more obvious. 964.Sh SEE ALSO 965.Xr libxo 3 , 966.Xr xolint 1 , 967.Xr xo_emit 3 968.Sh HISTORY 969The 970.Nm libxo 971library first appeared in 972.Fx 11.0 . 973.Sh AUTHORS 974.Nm libxo 975was written by 976.An Phil Shafer Aq Mt phil@freebsd.org . 977 978