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