| xo_format.5 (290445) | xo_format.5 (298083) |
|---|---|
| 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 --- 37 unchanged lines hidden (view full) --- 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 | 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 --- 37 unchanged lines hidden (view full) --- 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 '{' [ role | modifier ]* [',' long-names ]* ':' [ content ] 55 [ '/' field-format [ '/' encoding-format ]] '}' | 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. | 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. | 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 | 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 | 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 | 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); | 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 | 78.Ed 79.Pp 80This single line of code can generate text ("In stock: 65\\n"), XML |
| 81("<in-stock>65</in-stock>"), JSON ('"in-stock": 65'), or HTML (too | 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 | 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: | 88single\-character values: |
| 89.Bd -literal -offset indent | 89.Bd -literal -offset indent |
| 90 xo_emit("{L,white,colon:In stock}{,key:in-stock/%u}\n", 65); | 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" | 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)" | 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" | 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" | 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: | 110.El 111.Bd -literal -offset indent 112 EXAMPLE: |
| 113 xo_emit("{L:Free}{D::}{P: }{:free/%u} {U:Blocks}\n", | 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 preceeded by 120a comma: 121.Bd -literal -offset indent 122 EXAMPLE: 123 xo_emit("{,label:Free}{,decoration::}{,padding: }" | 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 preceeded by 120a comma: 121.Bd -literal -offset indent 122 EXAMPLE: 123 xo_emit("{,label:Free}{,decoration::}{,padding: }" |
| 124 "{,value:free/%u} {,units:Blocks}\n", | 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 | 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); | 131 xo_emit("{C:bold}{:value}{C:no\-bold}\\n", value); |
| 132.Ed 133.Pp | 132.Ed 133.Pp |
| 134Colors and effects remain in effect until modified by other "C"-role | 134Colors and effects remain in effect until modified by other "C"\-role |
| 135fields. 136.Bd -literal -offset indent | 135fields. 136.Bd -literal -offset indent |
| 137 xo_emit("{C:bold}{C:inverse}both{C:no-bold}only inverse\n"); | 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 | 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); | 142 xo_emit("{C:both,underline}{:value}{C:}\\n", value); |
| 143.Ed 144.Pp | 143.Ed 144.Pp |
| 145The content should be a comma-separated list of zero or more colors or | 145The content should be a comma\-separated list of zero or more colors or |
| 146display effects. 147.Bd -literal -offset indent | 146display effects. 147.Bd -literal -offset indent |
| 148 xo_emit("{C:bold,underline,inverse}All three{C:no-bold,no-inverse}\n"); | 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 | 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, | 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 | 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 | 159Color names are prefixed with either "fg\-" or "bg\-" to change the |
| 160foreground and background colors, respectively. 161.Bd -literal -offset indent | 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", | 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: | 163 fg_color, bg_color, cost); 164.Ed 165.Pp 166The following table lists the supported effects: |
| 167.Bl -column "no-underline" | 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: | 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" | 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, | 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 | 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 --- 9 unchanged lines hidden (view full) --- 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 | 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 --- 9 unchanged lines hidden (view full) --- 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 223the "xopo -f <input> -o <output>" command. | 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 | 224.Bd -literal -offset indent |
| 225 xo_emit("{G:}Invalid token\n"); | 225 xo_emit("{G:}Invalid token\\n"); |
| 226.Ed | 226.Ed |
| 227.Pp |
|
| 227The {G:} role allows a domain name to be set. 228.Fn gettext 229calls will 230continue to use that domain name until the current format string 231processing is complete, enabling a library function to emit strings | 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 |
| 232using it's own catalog. | 233using it\(aqs own catalog. |
| 233The domain name can be either static as the 234content of the field, or a format can be used to get the domain name 235from the arguments. 236.Bd -literal -offset indent | 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 |
| 237 xo_emit("{G:libc}Service unavailable in restricted mode\n"); | 238 xo_emit("{G:libc}Service unavailable in restricted mode\\n"); |
| 238.Ed 239.Ss "The Label Role ({L:})" 240Labels are text that appears before a value. 241.Bd -literal -offset indent 242 xo_emit("{Lwc:Cost}{:cost/%u}\\n", cost); 243.Ed 244.Ss "The Note Role ({N:})" 245Notes are text that appears after a value. 246.Bd -literal -offset indent 247 xo_emit("{:cost/%u} {N:per year}\\n", cost); 248.Ed 249.Ss "The Padding Role ({P:})" 250Padding represents whitespace used before and between fields. 251The padding content can be either static, when placed directly within | 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 |
| 252the field descriptor, or a printf-style format descriptor can be used, | 253the field descriptor, or a printf\-style format descriptor can be used, |
| 253if preceded by a slash ("/"): 254.Bd -literal -offset indent 255 xo_emit("{P: }{Lwc:Cost}{:cost/%u}\\n", cost); 256 xo_emit("{P:/30s}{Lwc:Cost}{:cost/%u}\\n", "", cost); 257.Ed 258.Ss "The Title Role ({T:})" 259Titles are heading or column headers that are meant to be displayed to 260the user. 261The title can be either static, when placed directly within | 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 |
| 262the field descriptor, or a printf-style format descriptor can be used, | 263the field descriptor, or a printf\-style format descriptor can be used, |
| 263if preceded by a slash ("/"): 264.Bd -literal -offset indent 265 xo_emit("{T:Interface Statistics}\\n"); 266 xo_emit("{T:/%20.20s}{T:/%6.6s}\\n", "Item Name", "Cost"); 267.Ed 268.Ss "The Units Role ({U:})" 269Units are the dimension by which values are measured, such as degrees, 270miles, bytes, and decibels. 271The units field carries this information 272for the previous value field. 273.Bd -literal -offset indent 274 xo_emit("{Lwc:Distance}{:distance/%u}{Uw:miles}\\n", miles); 275.Ed 276.Pp | 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 |
| 277Note that the sense of the 'w' modifier is reversed for units; | 278Note that the sense of the \(aqw\(aq modifier is reversed for units; |
| 278a blank is added before the contents, rather than after it. 279.Pp 280When the 281.Dv XOF_UNITS 282flag is set, units are rendered in XML as the 283.Dq units 284attribute: 285.Bd -literal -offset indent 286 <distance units="miles">50</distance> 287.Ed 288.Pp | 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 |
| 289Units can also be rendered in HTML as the "data-units" attribute: | 290Units can also be rendered in HTML as the "data\-units" attribute: |
| 290.Bd -literal -offset indent | 291.Bd -literal -offset indent |
| 291 <div class="data" data-tag="distance" data-units="miles" 292 data-xpath="/top/data/distance">50 | 292 <div class="data" data\-tag="distance" data\-units="miles" 293 data\-xpath="/top/data/distance">50</div> |
| 293.Ed 294.Ss "The Value Role ({V:} and {:})" 295The value role is used to represent the a data value that is | 294.Ed 295.Ss "The Value Role ({V:} and {:})" 296The value role is used to represent the a data value that is |
| 296interesting for the non-display output styles (XML and JSON). | 297interesting for the non\-display output styles (XML and JSON). |
| 297Value 298is the default role; if no other role designation is given, the field 299is a value. 300The field name must appear within the field descriptor, 301followed by one or two format descriptors. 302The first format 303descriptor is used for display styles (TEXT and HTML), while the 304second one is used for encoding styles (XML and JSON). --- 46 unchanged lines hidden (view full) --- 351If 352.Dv XOF_WARN 353is set, a warning will be generated. 354.Ss "Field Modifiers" 355Field modifiers are flags which modify the way content emitted for 356particular output styles: 357.Bl -column M "Name123456789" 358.It Sy M "Name " "Description" | 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). --- 46 unchanged lines hidden (view full) --- 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" |
|
| 359.It c "colon " "A colon ("":"") is appended after the label" 360.It d "display " "Only emit field for display styles (text/HTML)" 361.It e "encoding " "Only emit for encoding styles (XML/JSON)" | 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)" |
| 362.It h "humanize (hn) " "Format large numbers in human-readable style" 363.It " " "hn-space " "Humanize: Place space between numeric and unit" 364.It " " "hn-decimal " "Humanize: Add a decimal digit, if number < 10" 365.It " " "hn-1000 " "Humanize: Use 1000 as divisor instead of 1024" | 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" |
| 366.It k "key " "Field is a key, suitable for XPath predicates" | 368.It k "key " "Field is a key, suitable for XPath predicates" |
| 367.It l "leaf-list " "Field is a leaf-list, a list of leaf values" 368.It n "no-quotes " "Do not quote the field when using JSON style" | 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" |
| 369.It q "quotes " "Quote the field when using JSON style" 370.It t "trim " "Trim leading and trailing whitespace" 371.It w "white space " "A blank ("" "") is appended after the label" 372.El 373.Pp 374For example, the modifier string "Lwc" means the field has a label 375role (text that describes the next field) and should be followed by a | 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 |
| 376colon ('c') and a space ('w'). | 378colon (\(aqc\(aq) and a space (\(aqw\(aq). |
| 377The modifier string "Vkq" means the 378field has a value role, that it is a key for the current instance, and 379that the value should be quoted when encoded for JSON. 380.Pp 381Roles and modifiers can also use more verbose names, when preceeded by 382a comma. 383For example, the modifier string "Lwc" (or "L,white,colon") 384means the field has a label role (text that describes the next field) | 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 preceeded 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) |
| 385and should be followed by a colon ('c') and a space ('w'). | 387and should be followed by a colon (\(aqc\(aq) and a space (\(aqw\(aq). |
| 386The modifier string "Vkq" (or ":key,quote") means the field has a value 387role (the default role), that it is a key for the current instance, 388and that the value should be quoted when encoded for JSON. | 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}". |
|
| 389.Ss "The Colon Modifier ({c:})" 390The colon modifier appends a single colon to the data value: 391.Bd -literal -offset indent 392 EXAMPLE: 393 xo_emit("{Lc:Name}{:name}\\n", "phil"); 394 TEXT: 395 Name:phil 396.Ed 397.Pp 398The colon modifier is only used for the TEXT and HTML output 399styles. | 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. |
| 400It is commonly combined with the space modifier ('{w:}'). | 423It is commonly combined with the space modifier (\(aq{w:}\(aq). |
| 401It is purely a convenience feature. 402.Ss "The Display Modifier ({d:})" 403The display modifier indicated the field should only be generated for 404the display output styles, TEXT and HTML. 405.Bd -literal -offset indent 406 EXAMPLE: 407 xo_emit("{Lcw:Name}{d:name} {:id/%d}\\n", "phil", 1); 408 TEXT: --- 15 unchanged lines hidden (view full) --- 424 XML: 425 <name>phil</name><id>1</id> 426.Ed 427.Pp 428The encoding modifier is the opposite of the display modifier, and 429they are often used to give to distinct views of the underlying data. 430.Ss "The Humanize Modifier ({h:})" 431The humanize modifier is used to render large numbers as in a | 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: --- 15 unchanged lines hidden (view full) --- 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 |
| 432human-readable format. | 455human\-readable format. |
| 433While numbers like "44470272" are completely readable to computers and 434savants, humans will generally find "44M" more meaningful. 435.Pp 436"hn" can be used as an alias for "humanize". 437.Pp 438The humanize modifier only affects display styles (TEXT and HMTL). | 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). |
| 439The "no-humanize" option will block the function of the humanize modifier. | 462The "no\-humanize" option will block the function of the humanize modifier. |
| 440.Pp 441There are a number of modifiers that affect details of humanization. 442These are only available in as full names, not single characters. | 463.Pp 464There are a number of modifiers that affect details of humanization. 465These are only available in as full names, not single characters. |
| 443The "hn-space" modifier places a space between the number and any | 466The "hn\-space" modifier places a space between the number and any |
| 444multiplier symbol, such as "M" or "K" (ex: "44 K"). | 467multiplier symbol, such as "M" or "K" (ex: "44 K"). |
| 445The "hn-decimal" modifier will add a decimal point and a single tenths digit | 468The "hn\-decimal" modifier will add a decimal point and a single tenths digit |
| 446when the number is less than 10 (ex: "4.4K"). | 469when the number is less than 10 (ex: "4.4K"). |
| 447The "hn-1000" modifier will use 1000 as divisor instead of 1024, following the 448JEDEC-standard instead of the more natural binary powers-of-two | 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 |
| 449tradition. 450.Bd -literal -offset indent 451 EXAMPLE: | 472tradition. 473.Bd -literal -offset indent 474 EXAMPLE: |
| 452 xo_emit("{h:input/%u}, {h,hn-space:output/%u}, " 453 "{h,hn-decimal:errors/%u}, {h,hn-1000:capacity/%u}, " 454 "{h,hn-decimal:remaining/%u}\n", | 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", |
| 455 input, output, errors, capacity, remaining); 456 TEXT: 457 21, 57 K, 96M, 44M, 1.2G 458.Ed 459.Pp 460In the HTML style, the original numeric value is rendered in the | 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 |
| 461"data-number" attribute on the element: | 484"data\-number" attribute on the <div> element: |
| 462.Bd -literal -offset indent | 485.Bd -literal -offset indent |
| 463 464 data-number="100663296">96M | 486 <div class="data" data\-tag="errors" 487 data\-number="100663296">96M</div> |
| 465.Ed 466.Ss "The Gettext Modifier ({g:})" 467The gettext modifier is used to translate individual fields using the 468gettext domain (typically set using the "{G:}" role) and current 469language settings. 470Once libxo renders the field value, it is passed 471to 472.Xr gettext 3 , 473where it is used as a key to find the native language 474translation. 475.Pp 476In the following example, the strings "State" and "full" are passed 477to 478.Fn gettext | 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 |
| 479to find locale-based translated strings. | 502to find locale\-based translated strings. |
| 480.Bd -literal -offset indent | 503.Bd -literal -offset indent |
| 481 xo_emit("{Lgwc:State}{g:state}\n", "full"); | 504 xo_emit("{Lgwc:State}{g:state}\\n", "full"); |
| 482.Ed 483.Ss "The Key Modifier ({k:})" 484The key modifier is used to indicate that a particular field helps 485uniquely identify an instance of list data. 486.Bd -literal -offset indent 487 EXAMPLE: 488 xo_open_list("user"); 489 for (i = 0; i < num_users; i++) { --- 4 unchanged lines hidden (view full) --- 494 } 495 xo_close_list("user"); 496.Ed 497.Pp 498Currently the key modifier is only used when generating XPath values 499for the HTML output style when 500.Dv XOF_XPATH 501is set, but other uses are likely in the near future. | 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++) { --- 4 unchanged lines hidden (view full) --- 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. |
| 502.Ss "The Leaf-List Modifier ({l:})" 503The leaf-list modifier is used to distinguish lists where each | 525.Ss "The Leaf\-List Modifier ({l:})" 526The leaf\-list modifier is used to distinguish lists where each |
| 504instance consists of only a single value. In XML, these are 505rendered as single elements, where JSON renders them as arrays. 506.Bd -literal -offset indent 507 EXAMPLE: 508 xo_open_list("user"); 509 for (i = 0; i < num_users; i++) { | 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++) { |
| 510 xo_emit("Member {l:name}\n", user[i].u_name); | 533 xo_emit("Member {l:name}\\n", user[i].u_name); |
| 511 } 512 xo_close_list("user"); 513 XML: 514 <user>phil</user> 515 <user>pallavi</user> 516 JSON: 517 "user": [ "phil", "pallavi" ] 518.Ed | 534 } 535 xo_close_list("user"); 536 XML: 537 <user>phil</user> 538 <user>pallavi</user> 539 JSON: 540 "user": [ "phil", "pallavi" ] 541.Ed |
| 519.Ss "The No-Quotes Modifier ({n:})" 520The no-quotes modifier (and its twin, the 'quotes' modifier) affect | 542.Ss "The No\-Quotes Modifier ({n:})" 543The no\-quotes modifier (and its twin, the \(aqquotes\(aq modifier) affect |
| 521the quoting of values in the JSON output style. 522JSON uses quotes for 523string values, but no quotes for numeric, boolean, and null data. 524.Xr xo_emit 3 525applies a simple heuristic to determine whether quotes are 526needed, but often this needs to be controlled by the caller. 527.Bd -literal -offset indent 528 EXAMPLE: --- 4 unchanged lines hidden (view full) --- 533.Ed 534.Ss "The Plural Modifier ({p:})" 535The plural modifier selects the appropriate plural form of an 536expression based on the most recent number emitted and the current 537language settings. 538The contents of the field should be the singular 539and plural English values, separated by a comma: 540.Bd -literal -offset indent | 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: --- 4 unchanged lines hidden (view full) --- 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 |
| 541 xo_emit("{:bytes} {Ngp:byte,bytes}\n", bytes); | 564 xo_emit("{:bytes} {Ngp:byte,bytes}\\n", bytes); |
| 542.Ed | 565.Ed |
| 566.Pp |
|
| 543The plural modifier is meant to work with the gettext modifier ({g:}) 544but can work independently. 545.Pp 546When used without the gettext modifier or when the message does not 547appear in the message catalog, the first token is chosen when the last 548numeric value is equal to 1; otherwise the second value is used, 549mimicking the simple pluralization rules of English. 550.Pp 551When used with the gettext modifier, the 552.Xr ngettext 3 553function is 554called to handle the heavy lifting, using the message catalog to 555convert the singular and plural forms into the native language. 556.Ss "The Quotes Modifier ({q:})" | 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:})" |
| 557The quotes modifier (and its twin, the 'no-quotes' modifier) affect | 581The quotes modifier (and its twin, the \(aqno-quotes\(aq modifier) affect |
| 558the quoting of values in the JSON output style. 559JSON uses quotes for 560string values, but no quotes for numeric, boolean, and null data. 561.Xr xo_emit 3 562applies a simple heuristic to determine whether quotes are 563needed, but often this needs to be controlled by the caller. 564.Bd -literal -offset indent 565 EXAMPLE: --- 7 unchanged lines hidden (view full) --- 573 EXAMPLE: 574 xo_emit("{Lw:Name}{:name}\\n", "phil"); 575 TEXT: 576 Name phil 577.Ed 578.Pp 579The white space modifier is only used for the TEXT and HTML output 580styles. | 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: --- 7 unchanged lines hidden (view full) --- 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. |
| 581It is commonly combined with the colon modifier ('{c:}'). | 605It is commonly combined with the colon modifier (\(aq{c:}\(aq). |
| 582It is purely a convenience feature. 583.Pp | 606It is purely a convenience feature. 607.Pp |
| 584Note that the sense of the 'w' modifier is reversed for the units role | 608Note that the sense of the \(aqw\(aq modifier is reversed for the units role |
| 585({Uw:}); a blank is added before the contents, rather than after it. 586.Ss "Field Formatting" 587The field format is similar to the format string for 588.Xr printf 3 . 589Its use varies based on the role of the field, but generally is used to | 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 |
| 590format the field's contents. | 614format the field\(aqs contents. |
| 591.Pp 592If the format string is not provided for a value field, it defaults 593to "%s". 594.Pp | 615.Pp 616If the format string is not provided for a value field, it defaults 617to "%s". 618.Pp |
| 595Note a field definition can contain zero or more printf-style | 619Note a field definition can contain zero or more printf\-style |
| 596.Dq directives , | 620.Dq directives , |
| 597which are sequences that start with a '%' and end with | 621which are sequences that start with a \(aq%\(aq and end with |
| 598one of following characters: "diouxXDOUeEfFgGaAcCsSp". 599Each directive 600is matched by one of more arguments to the 601.Xr xo_emit 3 602function. 603.Pp 604The format string has the form: 605.Bd -literal -offset indent | 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 |
| 606 '%' format-modifier * format-character | 630 \(aq%\(aq format\-modifier * format\-character |
| 607.Ed 608.Pp | 631.Ed 632.Pp |
| 609The format- modifier can be: | 633The format\- modifier can be: |
| 610.Bl -bullet 611.It | 634.Bl -bullet 635.It |
| 612a '#' character, indicating the output value should be prefixed with | 636a \(aq#\(aq character, indicating the output value should be prefixed with |
| 613"0x", typically to indicate a base 16 (hex) value. 614.It | 637"0x", typically to indicate a base 16 (hex) value. 638.It |
| 615a minus sign ('-'), indicating the output value should be padded on | 639a minus sign (\(aq\-\(aq), indicating the output value should be padded on |
| 616the right instead of the left. 617.It | 640the right instead of the left. 641.It |
| 618a leading zero ('0') indicating the output value should be padded on the 619left with zeroes instead of spaces (' '). | 642a leading zero (\(aq0\(aq) indicating the output value should be padded on the 643left with zeroes instead of spaces (\(aq \(aq). |
| 620.It | 644.It |
| 621one or more digits ('0' - '9') indicating the minimum width of the | 645one or more digits (\(aq0\(aq \- \(aq9\(aq) indicating the minimum width of the |
| 622argument. 623If the width in columns of the output value is less than 624the minimum width, the value will be padded to reach the minimum. 625.It 626a period followed by one or more digits indicating the maximum 627number of bytes which will be examined for a string argument, or the maximum | 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 |
| 628width for a non-string argument. | 652width for a non\-string argument. |
| 629When handling ASCII strings this | 653When handling ASCII strings this |
| 630functions as the field width but for multi-byte characters, a single | 654functions as the field width but for multi\-byte characters, a single |
| 631character may be composed of multiple bytes. 632.Xr xo_emit 3 633will never dereference memory beyond the given number of bytes. 634.It 635a second period followed by one or more digits indicating the maximum 636width for a string argument. | 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. |
| 637This modifier cannot be given for non-string arguments. | 661This modifier cannot be given for non\-string arguments. |
| 638.It | 662.It |
| 639one or more 'h' characters, indicating shorter input data. | 663one or more \(aqh\(aq characters, indicating shorter input data. |
| 640.It | 664.It |
| 641one or more 'l' characters, indicating longer input data. | 665one or more \(aql\(aq characters, indicating longer input data. |
| 642.It | 666.It |
| 643a 'z' character, indicating a 'size_t' argument. | 667a \(aqz\(aq character, indicating a \(aqsize_t\(aq argument. |
| 644.It | 668.It |
| 645a 't' character, indicating a 'ptrdiff_t' argument. | 669a \(aqt\(aq character, indicating a \(aqptrdiff_t\(aq argument. |
| 646.It | 670.It |
| 647a ' ' character, indicating a space should be emitted before | 671a \(aq \(aq character, indicating a space should be emitted before |
| 648positive numbers. 649.It | 672positive numbers. 673.It |
| 650a '+' character, indicating sign should emitted before any number. | 674a \(aq+\(aq character, indicating sign should emitted before any number. |
| 651.El 652.Pp | 675.El 676.Pp |
| 653Note that 'q', 'D', 'O', and 'U' are considered deprecated and will be | 677Note that \(aqq\(aq, \(aqD\(aq, \(aqO\(aq, and \(aqU\(aq are considered deprecated and will be |
| 654removed eventually. 655.Pp 656The format character is described in the following table: 657.Bl -column C "Argument Type12" 658.It Sy "C" "Argument Type " "Format" 659.It d "int " "base 10 (decimal)" 660.It i "int " "base 10 (decimal)" 661.It o "int " "base 8 (octal)" 662.It u "unsigned " "base 10 (decimal)" 663.It x "unsigned " "base 16 (hex)" 664.It X "unsigned long " "base 16 (hex)" 665.It D "long " "base 10 (decimal)" 666.It O "unsigned long " "base 8 (octal)" 667.It U "unsigned long " "base 10 (decimal)" | 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)" |
| 668.It e "double " "[-]d.ddde+-dd" 669.It E "double " "[-]d.dddE+-dd" 670.It f "double " "[-]ddd.ddd" 671.It F "double " "[-]ddd.ddd" 672.It g "double " "as 'e' or 'f'" 673.It G "double " "as 'E' or 'F'" 674.It a "double " "[-]0xh.hhhp[+-]d" 675.It A "double " "[-]0Xh.hhhp[+-]d" | 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" |
| 676.It c "unsigned char " "a character" 677.It C "wint_t " "a character" | 700.It c "unsigned char " "a character" 701.It C "wint_t " "a character" |
| 678.It s "char * " "a UTF-8 string" | 702.It s "char * " "a UTF\-8 string" |
| 679.It S "wchar_t * " "a unicode/WCS string" | 703.It S "wchar_t * " "a unicode/WCS string" |
| 680.It p "void * " "'%#lx'" | 704.It p "void * " "\(aq%#lx\(aq" |
| 681.El 682.Pp | 705.El 706.Pp |
| 683The 'h' and 'l' modifiers affect the size and treatment of the | 707The \(aqh\(aq and \(aql\(aq modifiers affect the size and treatment of the |
| 684argument: 685.Bl -column "Mod" "d, i " "o, u, x, X " 686.It Sy "Mod" "d, i " "o, u, x, X" 687.It "hh " "signed char " "unsigned char" 688.It "h " "short " "unsigned short" 689.It "l " "long " "unsigned long" 690.It "ll " "long long " "unsigned long long" 691.It "j " "intmax_t " "uintmax_t" 692.It "t " "ptrdiff_t " "ptrdiff_t" 693.It "z " "size_t " "size_t" 694.It "q " "quad_t " "u_quad_t" 695.El | 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 |
| 696.Ss "UTF-8 and Locale Strings" | 720.Ss "UTF\-8 and Locale Strings" |
| 697All strings for 698.Nm libxo | 721All strings for 722.Nm libxo |
| 699must be UTF-8. | 723must be UTF\-8. |
| 700.Nm libxo 701will handle turning them | 724.Nm libxo 725will handle turning them |
| 702into locale-based strings for display to the user. | 726into locale\-based strings for display to the user. |
| 703.Pp | 727.Pp |
| 704For strings, the 'h' and 'l' modifiers affect the interpretation of | 728For strings, the \(aqh\(aq and \(aql\(aq modifiers affect the interpretation of |
| 705the bytes pointed to argument. | 729the bytes pointed to argument. |
| 706The default '%s' string is a 'char *' 707pointer to a string encoded as UTF-8. 708Since UTF-8 is compatible with | 730The default \(aq%s\(aq string is a \(aqchar *\(aq 731pointer to a string encoded as UTF\-8. 732Since UTF\-8 is compatible with |
| 709.Em ASCII | 733.Em ASCII |
| 710data, a normal 7-bit | 734data, a normal 7\-bit |
| 711.Em ASCII 712string can be used. 713"%ls" expects a | 735.Em ASCII 736string can be used. 737"%ls" expects a |
| 714"wchar_t *" pointer to a wide-character string, encoded as 32-bit | 738"wchar_t *" pointer to a wide\-character string, encoded as 32\-bit |
| 715Unicode values. | 739Unicode values. |
| 716"%hs" expects a "char *" pointer to a multi-byte | 740"%hs" expects a "char *" pointer to a multi\-byte |
| 717string encoded with the current locale, as given by the 718.Ev LC_CTYPE , 719.Ev LANG , 720or 721.Ev LC_ALL 722environment variables. 723The first of this list of 724variables is used and if none of the variables are set, the locale defaults to | 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 |
| 725.Em UTF-8 . | 749.Em UTF\-8 . |
| 726.Pp 727.Nm libxo 728will | 750.Pp 751.Nm libxo 752will |
| 729convert these arguments as needed to either UTF-8 (for XML, JSON, and 730HTML styles) or locale-based strings for display in text style. | 753convert these arguments as needed to either UTF\-8 (for XML, JSON, and 754HTML styles) or locale\-based strings for display in text style. |
| 731.Bd -literal -offset indent | 755.Bd -literal -offset indent |
| 732 xo_emit("All strings are utf-8 content {:tag/%ls}", | 756 xo_emit("All strings are utf\-8 content {:tag/%ls}", |
| 733 L"except for wide strings"); 734.Ed 735.Pp 736"%S" is equivalent to "%ls". 737.Pp | 757 L"except for wide strings"); 758.Ed 759.Pp 760"%S" is equivalent to "%ls". 761.Pp |
| 738For example, a function is passed a locale-base name, a hat size, | 762For example, a function is passed a locale\-base name, a hat size, |
| 739and a time value. | 763and a time value. |
| 740The hat size is formatted in a UTF-8 (ASCII) | 764The hat size is formatted in a UTF\-8 (ASCII) |
| 741string, and the time value is formatted into a wchar_t string. 742.Bd -literal -offset indent 743 void print_order (const char *name, int size, 744 struct tm *timep) { 745 char buf[32]; 746 const char *size_val = "unknown"; 747 748 if (size > 0) 749 snprintf(buf, sizeof(buf), "%d", size); 750 size_val = buf; 751 } 752 753 wchar_t when[32]; 754 wcsftime(when, sizeof(when), L"%d%b%y", timep); 755 756 xo_emit("The hat for {:name/%hs} is {:size/%s}.\\n", 757 name, size_val); | 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); |
| 758 xo_emit("It was ordered on {:order-time/%ls}.\\n", | 782 xo_emit("It was ordered on {:order\-time/%ls}.\\n", |
| 759 when); 760 } 761.Ed 762.Pp 763It is important to note that 764.Xr xo_emit 3 765will perform the conversion 766required to make appropriate output. 767Text style output uses the 768current locale (as described above), while XML, JSON, and HTML use | 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 |
| 769UTF-8. | 793UTF\-8. |
| 770.Pp | 794.Pp |
| 771UTF-8 and locale-encoded strings can use multiple bytes to encode one | 795UTF\-8 and locale\-encoded strings can use multiple bytes to encode one |
| 772column of data. | 796column of data. |
| 773The traditional "precision'" (aka "max-width") value | 797The traditional "precision" (aka "max\-width") value |
| 774for "%s" printf formatting becomes overloaded since it specifies both 775the number of bytes that can be safely referenced and the maximum 776number of columns to emit. 777.Xr xo_emit 3 778uses the precision as the former, 779and adds a third value for specifying the maximum number of columns. 780.Pp 781In this example, the name field is printed with a minimum of 3 columns --- 13 unchanged lines hidden (view full) --- 795 TEXT: 796 The hat is extra small. 797 XML: 798 <size>extra small</size> 799 JSON: 800 "size": "extra small" 801 HTML: 802 <div class="text">The hat is </div> | 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 --- 13 unchanged lines hidden (view full) --- 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> |
| 803 extra small | 827 <div class="data" data\-tag="size">extra small</div> |
| 804 <div class="text">.</div> 805.Ed | 828 <div class="text">.</div> 829.Ed |
| 806.Ss "'%n' is Not Supported" | 830.Ss "\(aq%n\(aq is Not Supported" |
| 807.Nm libxo | 831.Nm libxo |
| 808does not support the '%n' directive. | 832does not support the \(aq%n\(aq directive. |
| 809It is a bad idea and we 810just do not do it. 811.Ss "The Encoding Format (eformat)" 812The "eformat" string is the format string used when encoding the field 813for JSON and XML. 814If not provided, it defaults to the primary format 815with any minimum width removed. 816If the primary is not given, both default to "%s". 817.Sh EXAMPLE 818In this example, the value for the number of items in stock is emitted: 819.Bd -literal -offset indent | 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 |
| 820 xo_emit("{P: }{Lwc:In stock}{:in-stock/%u}\\n", | 844 xo_emit("{P: }{Lwc:In stock}{:in\-stock/%u}\\n", |
| 821 instock); 822.Ed 823.Pp 824This call will generate the following output: 825.Bd -literal -offset indent 826 TEXT: 827 In stock: 144 828 XML: | 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: |
| 829 <in-stock>144</in-stock> | 853 <in\-stock>144</in\-stock> |
| 830 JSON: | 854 JSON: |
| 831 "in-stock": 144, | 855 "in\-stock": 144, |
| 832 HTML: 833 <div class="line"> 834 <div class="padding"> </div> 835 <div class="label">In stock</div> 836 <div class="decoration">:</div> 837 <div class="padding"> </div> | 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> |
| 838 <div class="data" data-tag="in-stock">144</div> | 862 <div class="data" data\-tag="in\-stock">144</div> |
| 839 </div> 840.Ed 841.Pp 842Clearly HTML wins the verbosity award, and this output does 843not include 844.Dv XOF_XPATH 845or 846.Dv XOF_INFO 847data, which would expand the penultimate line to: 848.Bd -literal -offset indent | 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 |
| 849 <div class="data" data-tag="in-stock" 850 data-xpath="/top/data/item/in-stock" 851 data-type="number" 852 data-help="Number of items in stock">144 | 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> |
| 853.Ed 854.Sh WHAT MAKES A GOOD FIELD NAME? 855To make useful, consistent field names, follow these guidelines: 856.Ss "Use lower case, even for TLAs" 857Lower case is more civilized. 858Even TLAs should be lower case 859to avoid scenarios where the differences between "XPath" and 860"Xpath" drive your users crazy. 861Using "xpath" is simpler and better. 862.Ss "Use hyphens, not underscores" 863Use of hyphens is traditional in XML, and the 864.Dv XOF_UNDERSCORES 865flag can be used to generate underscores in JSON, if desired. 866But the raw field name should use hyphens. 867.Ss "Use full words" 868Do not abbreviate especially when the abbreviation is not obvious or 869not widely used. | 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. |
| 870Use "data-size", not "dsz" or "dsize". | 894Use "data\-size", not "dsz" or "dsize". |
| 871Use | 895Use |
| 872"interface" instead of "ifname", "if-name", "iface", "if", or "intf". 873.Ss "Use 874Using the form <verb>-<units> or <verb>-<classifier>-<units> helps in | 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 |
| 875making consistent, useful names, avoiding the situation where one app | 899making consistent, useful names, avoiding the situation where one app |
| 876uses "sent-packet" and another "packets-sent" and another 877"packets-we-have-sent". | 900uses "sent\-packet" and another "packets\-sent" and another 901"packets\-we\-have\-sent". |
| 878The <units> can be dropped when it is 879obvious, as can obvious words in the classification. | 902The <units> can be dropped when it is 903obvious, as can obvious words in the classification. |
| 880Use "receive-after-window-packets" instead of 881"received-packets-of-data-after-window". | 904Use "receive\-after\-window\-packets" instead of 905"received\-packets\-of\-data\-after\-window". |
| 882.Ss "Reuse existing field names" 883Nothing is worse than writing expressions like: 884.Bd -literal -offset indent 885 if ($src1/process[pid == $pid]/name == | 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 == |
| 886 $src2/proc-table/proc/p[process-id == $pid]/proc-name) { | 910 $src2/proc\-table/proc/p[process\-id == $pid]/proc\-name) { |
| 887 ... 888 } 889.Ed 890.Pp 891Find someone else who is expressing similar data and follow their 892fields and hierarchy. 893Remember the quote is not 894.Dq "Consistency is the hobgoblin of little minds" 895but 896.Dq "A foolish consistency is the hobgoblin of little minds" . 897.Ss "Think about your users" 898Have empathy for your users, choosing clear and useful fields that 899contain clear and useful data. 900You may need to augment the display content with 901.Xr xo_attr 3 902calls or "{e:}" fields to make the data useful. 903.Ss "Do not use an arbitrary number postfix" 904What does "errors2" mean? 905No one will know. | 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. |
| 906"errors-after-restart" would be a better choice. | 930"errors\-after\-restart" would be a better choice. |
| 907Think of your users, and think of the future. 908If you make "errors2", the next guy will happily make 909"errors3" and before you know it, someone will be asking what is the 910difference between errors37 and errors63. 911.Ss "Be consistent, uniform, unsurprising, and predictable" 912Think of your field vocabulary as an API. 913You want it useful, 914expressive, meaningful, direct, and obvious. 915You want the client | 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 |
| 916application's programmer to move between without the need to | 940application\(aqs programmer to move between without the need to |
| 917understand a variety of opinions on how fields are named. 918They should 919see the system as a single cohesive whole, not a sack of cats. 920.Pp 921Field names constitute the means by which client programmers interact 922with our system. 923By choosing wise names now, you are making their lives better. 924.Pp 925After using 926.Xr xolint 1 927to find errors in your field descriptors, use | 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 |
| 928.Dq "xolint -V" | 952.Dq "xolint \-V" |
| 929to spell check your field names and to detect different 930names for the same data. | 953to spell check your field names and to detect different 954names for the same data. |
| 931.Dq dropped-short | 955.Dq dropped\-short |
| 932and | 956and |
| 933.Dq dropped-too-short | 957.Dq dropped\-too\-short |
| 934are both reasonable names, but using them both will lead users to ask the 935difference between the two fields. 936If there is no difference, 937use only one of the field names. 938If there is a difference, change the 939names to make that difference more obvious. 940.Sh SEE ALSO 941.Xr libxo 3 , 942.Xr xolint 1 , 943.Xr xo_emit 3 | 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 |