1 2.. index:: Format Strings 3.. _format-strings: 4 5Format Strings 6-------------- 7 8libxo uses format strings to control the rendering of data into the 9various output styles. Each format string contains a set of zero or 10more field descriptions, which describe independent data fields. Each 11field description contains a set of modifiers, a content string, and 12zero, one, or two format descriptors. The modifiers tell libxo what 13the field is and how to treat it, while the format descriptors are 14formatting instructions using printf-style format strings, telling 15libxo how to format the field. The field description is placed inside 16a set of braces, with a colon (":") after the modifiers and a slash 17("/") before each format descriptors. Text may be intermixed with 18field descriptions within the format string. 19 20The field description is given as follows:: 21 22 '{' [ role | modifier ]* [',' long-names ]* ':' [ content ] 23 [ '/' field-format [ '/' encoding-format ]] '}' 24 25The role describes the function of the field, while the modifiers 26enable optional behaviors. The contents, field-format, and 27encoding-format are used in varying ways, based on the role. These 28are described in the following sections. 29 30In the following example, three field descriptors appear. The first 31is a padding field containing three spaces of padding, the second is a 32label ("In stock"), and the third is a value field ("in-stock"). The 33in-stock field has a "%u" format that will parse the next argument 34passed to the xo_emit function as an unsigned integer:: 35 36 xo_emit("{P: }{Lwc:In stock}{:in-stock/%u}\n", 65); 37 38This single line of code can generate text (" In stock: 65\n"), XML 39("<in-stock>65</in-stock>"), JSON ('"in-stock": 6'), or HTML (too 40lengthy to be listed here). 41 42While roles and modifiers typically use single character for brevity, 43there are alternative names for each which allow more verbose 44formatting strings. These names must be preceded by a comma, and may 45follow any single-character values:: 46 47 xo_emit("{L,white,colon:In stock}{,key:in-stock/%u}\n", 65); 48