GNU Info

(librep.info)Formatted Output

---

Prev: Output Functions Up: Streams

---

Enter node , (file) or (file)node

Formatted Output
----------------

 - Function: format stream template #!rest values
     Writes to a stream, STREAM, a string constructed from the format
     string, TEMPLATE, and list of arguments VALUES.

     If STREAM is false the resulting string will be returned, not
     written to a stream.

     TEMPLATE is a template for the output string, any `%' characters
     introduce a substitution, using the next unused argument.  The
     substitutions have the following syntax,

          %[INDEX$][FLAGS][FIELD-WIDTH]CONVERSION

     INDEX is an optional decimal number specifying exactly which of
     the VALUES this conversion refers to (with the first at position
     one), and is usually used when translating messages; by default the
     next value is used.

     FIELD-WIDTH is a positive decimal integer, defining the size in
     characters of the substitution output.

     CONVERSION is a character defining how to convert the
     corresponding argument value to text. The default options are:

    `s'
          Write the printed representation of the value without quoting
          (as if from the `princ' function).

    `S'
          Write the printed representation _with_ quoting enabled (like
          the `prin1' function).

    `d'
          Output the value as a decimal number.

    `o'
          Write the value in octal.

    `x'
    `X'
          In hexadecimal.

    `c'
          Write the character specified by the value.

    `%'
          Print a literal percent character. None of the VALUES are
          used.

     FLAGS is a sequence of zero or more of the following characters,

    `_'
          Left justify the substitution within the field.

    `^'
          Truncate the substitution at the size of the field.

    `0'
          Pad the field with zeros instead of spaces.

    `+'
          For `d', `x', and `o' conversions, output a leading plus sign
          if the argument is positive.

    ` ' (a space)
          For `d', `x', and `o' conversions, if the result doesn't
          start with a plus or minus sign, output a leading space.

     The list of CONVERSIONS can be extended through the
     `format-hooks-alist' variable; the strings created by these extra
     conversions are formatted as if by the `s' conversion.

     Note that the FIELD-WIDTH and all flags currently have no effect
     on the `S' conversion, (or the `s' conversion when the argument
     isn't a string).

     If STREAM isn't false (in which case the created string is
     returned) the value of STREAM is returned.

          (format nil "foo %S bar 0x%x" '(x . y) 255)
              => "foo (x . y) bar 0xff"
          
          (format standard-output "The %2$s is %1$s!" "purple" "dog")
              -| The dog is purple!
              => #<buffer *jade*>

 - Variable: format-hooks-alist
     This variable is an association-list, each element being `(CHAR .
     FUNCTION)', defining extra conversions for the `format' function.

     If a conversion `%X' is given, and the alist contains an element
     whose car is the character X, the the associated function is
     called with one value, the next argument to be formatted. It should
     return the string to be inserted.