1 2.. index:: Field Roles 3.. _field-roles: 4 5Field Roles 6~~~~~~~~~~~ 7 8Field roles are optional, and indicate the role and formatting of the 9content. The roles are listed below; only one role is permitted: 10 11 === ============== ================================================= 12 R Name Description 13 === ============== ================================================= 14 C color Field has color and effect controls 15 D decoration Field is non-text (e.g., colon, comma) 16 E error Field is an error message 17 G gettext Call gettext(3) on the format string 18 L label Field is text that prefixes a value 19 N note Field is text that follows a value 20 P padding Field is spaces needed for vertical alignment 21 T title Field is a title value for headings 22 U units Field is the units for the previous value field 23 V value Field is the name of field (the default) 24 W warning Field is a warning message 25 [ start-anchor Begin a section of anchored variable-width text 26 ] stop-anchor End a section of anchored variable-width text 27 === ============== ================================================= 28 29:: 30 31 EXAMPLE: 32 xo_emit("{L:Free}{D::}{P: }{:free/%u} {U:Blocks}\n", 33 free_blocks); 34 35When a role is not provided, the "*value*" role is used as the default. 36 37Roles and modifiers can also use more verbose names, when preceded by 38a comma:: 39 40 EXAMPLE: 41 xo_emit("{,label:Free}{,decoration::}{,padding: }" 42 "{,value:free/%u} {,units:Blocks}\n", 43 free_blocks); 44 45.. index:: Field Roles; Color 46.. _color-role: 47 48The Color Role ({C:}) 49+++++++++++++++++++++ 50 51Colors and effects control how text values are displayed; they are 52used for display styles (TEXT and HTML):: 53 54 xo_emit("{C:bold}{:value}{C:no-bold}\n", value); 55 56Colors and effects remain in effect until modified by other "C"-role 57fields:: 58 59 xo_emit("{C:bold}{C:inverse}both{C:no-bold}only inverse\n"); 60 61If the content is empty, the "*reset*" action is performed:: 62 63 xo_emit("{C:both,underline}{:value}{C:}\n", value); 64 65The content should be a comma-separated list of zero or more colors or 66display effects:: 67 68 xo_emit("{C:bold,inverse}Ugly{C:no-bold,no-inverse}\n"); 69 70The color content can be either static, when placed directly within 71the field descriptor, or a printf-style format descriptor can be used, 72if preceded by a slash ("/"): 73 74 xo_emit("{C:/%s%s}{:value}{C:}", need_bold ? "bold" : "", 75 need_underline ? "underline" : "", value); 76 77Color names are prefixed with either "fg-" or "bg-" to change the 78foreground and background colors, respectively:: 79 80 xo_emit("{C:/fg-%s,bg-%s}{Lwc:Cost}{:cost/%u}{C:reset}\n", 81 fg_color, bg_color, cost); 82 83The following table lists the supported effects: 84 85 =============== ================================================= 86 Name Description 87 =============== ================================================= 88 bg-XXXXX Change background color 89 bold Start bold text effect 90 fg-XXXXX Change foreground color 91 inverse Start inverse (aka reverse) text effect 92 no-bold Stop bold text effect 93 no-inverse Stop inverse (aka reverse) text effect 94 no-underline Stop underline text effect 95 normal Reset effects (only) 96 reset Reset colors and effects (restore defaults) 97 underline Start underline text effect 98 =============== ================================================= 99 100The following color names are supported: 101 102 ========= ============================================ 103 Name Description 104 ========= ============================================ 105 black 106 blue 107 cyan 108 default Default color for foreground or background 109 green 110 magenta 111 red 112 white 113 yellow 114 ========= ============================================ 115 116When using colors, the developer should remember that users will 117change the foreground and background colors of terminal session 118according to their own tastes, so assuming that "blue" looks nice is 119never safe, and is a constant annoyance to your dear author. In 120addition, a significant percentage of users (1 in 12) will be color 121blind. Depending on color to convey critical information is not a 122good idea. Color should enhance output, but should not be used as the 123sole means of encoding information. 124 125.. index:: Field Roles; Decoration 126.. _decoration-role: 127 128The Decoration Role ({D:}) 129++++++++++++++++++++++++++ 130 131Decorations are typically punctuation marks such as colons, 132semi-colons, and commas used to decorate the text and make it simpler 133for human readers. By marking these distinctly, HTML usage scenarios 134can use CSS to direct their display parameters:: 135 136 xo_emit("{D:((}{:name}{D:))}\n", name); 137 138.. index:: Field Roles; Gettext 139.. _gettext-role: 140 141The Gettext Role ({G:}) 142+++++++++++++++++++++++ 143 144libxo supports internationalization (i18n) through its use of 145gettext(3). Use the "{G:}" role to request that the remaining part of 146the format string, following the "{G:}" field, be handled using 147gettext(). 148 149Since gettext() uses the string as the key into the message catalog, 150libxo uses a simplified version of the format string that removes 151unimportant field formatting and modifiers, stopping minor formatting 152changes from impacting the expensive translation process. A developer 153change such as changing "/%06d" to "/%08d" should not force hand 154inspection of all .po files. 155 156The simplified version can be generated for a single message using the 157"`xopo -s $text`" command, or an entire .pot can be translated using 158the "`xopo -f $input -o $output`" command. 159 160 xo_emit("{G:}Invalid token\n"); 161 162The {G:} role allows a domain name to be set. gettext calls will 163continue to use that domain name until the current format string 164processing is complete, enabling a library function to emit strings 165using it's own catalog. The domain name can be either static as the 166content of the field, or a format can be used to get the domain name 167from the arguments. 168 169 xo_emit("{G:libc}Service unavailable in restricted mode\n"); 170 171See :ref:`i18n` for additional details. 172 173.. index:: Field Roles; Label 174.. _label-role: 175 176The Label Role ({L:}) 177+++++++++++++++++++++ 178 179Labels are text that appears before a value:: 180 181 xo_emit("{Lwc:Cost}{:cost/%u}\n", cost); 182 183.. index:: Field Roles; Note 184.. _note-role: 185 186The Note Role ({N:}) 187++++++++++++++++++++ 188 189Notes are text that appears after a value:: 190 191 xo_emit("{:cost/%u} {N:per year}\n", cost); 192 193.. index:: Field Roles; Padding 194.. _padding-role: 195 196The Padding Role ({P:}) 197+++++++++++++++++++++++ 198 199Padding represents whitespace used before and between fields. 200 201The padding content can be either static, when placed directly within 202the field descriptor, or a printf-style format descriptor can be used, 203if preceded by a slash ("/"):: 204 205 xo_emit("{P: }{Lwc:Cost}{:cost/%u}\n", cost); 206 xo_emit("{P:/%30s}{Lwc:Cost}{:cost/%u}\n", "", cost); 207 208.. index:: Field Roles; Title 209.. _title-role: 210 211The Title Role ({T:}) 212+++++++++++++++++++++ 213 214Title are heading or column headers that are meant to be displayed to 215the user. The title can be either static, when placed directly within 216the field descriptor, or a printf-style format descriptor can be used, 217if preceded by a slash ("/"):: 218 219 xo_emit("{T:Interface Statistics}\n"); 220 xo_emit("{T:/%20.20s}{T:/%6.6s}\n", "Item Name", "Cost"); 221 222Title fields have an extra convenience feature; if both content and 223format are specified, instead of looking to the argument list for a 224value, the content is used, allowing a mixture of format and content 225within the field descriptor:: 226 227 xo_emit("{T:Name/%20s}{T:Count/%6s}\n"); 228 229Since the incoming argument is a string, the format must be "%s" or 230something suitable. 231 232.. index:: Field Roles; Units 233.. index:: XOF_UNITS 234.. _units-role: 235 236The Units Role ({U:}) 237+++++++++++++++++++++ 238 239Units are the dimension by which values are measured, such as degrees, 240miles, bytes, and decibels. The units field carries this information 241for the previous value field:: 242 243 xo_emit("{Lwc:Distance}{:distance/%u}{Uw:miles}\n", miles); 244 245Note that the sense of the 'w' modifier is reversed for units; 246a blank is added before the contents, rather than after it. 247 248When the XOF_UNITS flag is set, units are rendered in XML as the 249"units" attribute:: 250 251 <distance units="miles">50</distance> 252 253Units can also be rendered in HTML as the "data-units" attribute:: 254 255 <div class="data" data-tag="distance" data-units="miles" 256 data-xpath="/top/data/distance">50</div> 257 258.. index:: Field Roles; Value 259.. _value-role: 260 261The Value Role ({V:} and {:}) 262+++++++++++++++++++++++++++++ 263 264The value role is used to represent the a data value that is 265interesting for the non-display output styles (XML and JSON). Value 266is the default role; if no other role designation is given, the field 267is a value. The field name must appear within the field descriptor, 268followed by one or two format descriptors. The first format 269descriptor is used for display styles (TEXT and HTML), while the 270second one is used for encoding styles (XML and JSON). If no second 271format is given, the encoding format defaults to the first format, 272with any minimum width removed. If no first format is given, both 273format descriptors default to "%s":: 274 275 xo_emit("{:length/%02u}x{:width/%02u}x{:height/%02u}\n", 276 length, width, height); 277 xo_emit("{:author} wrote \"{:poem}\" in {:year/%4d}\n, 278 author, poem, year); 279 280.. index:: Field Roles; Anchor 281.. _anchor-role: 282 283The Anchor Roles ({[:} and {]:}) 284++++++++++++++++++++++++++++++++ 285 286The anchor roles allow a set of strings by be padded as a group, 287but still be visible to xo_emit as distinct fields. Either the start 288or stop anchor can give a field width and it can be either directly in 289the descriptor or passed as an argument. Any fields between the start 290and stop anchor are padded to meet the minimum width given. 291 292To give a width directly, encode it as the content of the anchor tag:: 293 294 xo_emit("({[:10}{:min/%d}/{:max/%d}{]:})\n", min, max); 295 296To pass a width as an argument, use "%d" as the format, which must 297appear after the "/". Note that only "%d" is supported for widths. 298Using any other value could ruin your day:: 299 300 xo_emit("({[:/%d}{:min/%d}/{:max/%d}{]:})\n", width, min, max); 301 302If the width is negative, padding will be added on the right, suitable 303for left justification. Otherwise the padding will be added to the 304left of the fields between the start and stop anchors, suitable for 305right justification. If the width is zero, nothing happens. If the 306number of columns of output between the start and stop anchors is less 307than the absolute value of the given width, nothing happens. 308 309.. index:: XOF_WARN 310 311Widths over 8k are considered probable errors and not supported. If 312XOF_WARN is set, a warning will be generated. 313