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