Changeset 9260 in project


Ignore:
Timestamp:
03/07/08 20:33:09 (12 years ago)
Author:
Kon Lovett
Message:

Updated doc to add entries for all exported procedures.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/format-modular

    r6454 r9260  
    55
    66Code to generate format functions. It is relatively flexible, supporting inheritance and allowing you to extend your formatters. It is accompanied by an implementation of Common Lisp's format function which is thread safe and extendible (meaning you could define new format characters).
    7 
    8 == Example
    9 
    10 === format
    11 
    12 <enscript highlight=scheme>
    13 (use format-modular)
    14 (format #f "Found: [~D]: ~A~%" 12 "objects")
    15 </enscript>
    16 
    17 === make-format-function
    18 
    19 <enscript highlight=scheme>
    20 (use format-modular)
    21 
    22 (define fprintf
    23   (make-format-function #f #\%
    24     `(((#\d ,(formatter-padded display))
    25        (#\s ,(formatter-padded write))))))
    26 
    27 (fprintf #t "Found: [%d]: %s\n" 12 "objects")
    28 </enscript>
    29 
    30 == Known limitations
    31 
    32 Chicken doesn't have support for output port column position. Since a new state is created upon each invocation
    33 the format output column position has no "memory", thus {{~&}} is accurate only within a single invocation.
    347
    358== make-format-function
     
    5629by escape, is found in the format string.
    5730
    58 To produce the functions included in the formatters, use {{(formatter-function
    59 PROC)}}, where {{PROC}} is a procedure that receives the following parameters:
    60 
    61 ; state : A structure with internal information. You won't normally inspect this directly but rather pass it to other functions that require it (such as {{*formatter-out-char}} and {{*formatter-out-string}}).
     31To produce the functions included in the formatters, use {{formatter-function}} procedure.
     32
     33To output info at the current position, the formatter functions should use the
     34{{*formatter-out-foo}} procedures.
     35
     36For convenience, you can also use {{formatter-padded}} procedure when you
     37want to create a function to display an object with padding.
     38
     39== formatter-function
     40
     41 [procedure] (formatter-function PROC)
     42
     43{{PROC}} is a procedure that receives the following parameters:
     44
     45; state : A structure with internal information. You won't normally inspect this directly but rather pass it to other functions that require it (such as {{*formatter-out-foo}} procedures).
    6246; start : The position in the format string where the beginning of the escape sequence was found. You'll normally just ignore this.
    6347; params : A list with paramters that occur between {{escape}} and {{char}} (for example, in a format string such as {{~23,33,12A}}).
    6448; colon, atsign : Booleans indicating whether those characters occur between {{escape}} and {{char}}.
    6549
    66 To output info at the current position, the formatter functions should use the
    67 {{*formatter-out-char}} and {{*formatter-out-string}} functions. They receive
    68 the {{state}} parameter (as passed to the formatter function) and a character
    69 and string respectively.
    70 
    71 For convenience, you can also use {{(formatter-padded PROC)}} when you
    72 want to create a function to display an object in some representation.
    73 In this case, {{PROC}} should be a procedure receiving one argument,
    74 an object, and write the desired representation to the current output
    75 port.
     50== formatter-padded
     51
     52 [procedure] (formatter-padded SHOW-FUNC)
     53
     54{{SHOW-FUNC}} is a one-argument function, the object, which should write (to the
     55current-output-port) a representation of the object.
     56
     57The object representation is padded according to the padding parameters - {{mincol,colinc,minpad,padchar}}.
     58
     59== *formatter-out-char
     60
     61 [procedure] (*formatter-out-char STATE CHAR)
     62
     63Output the {{CHAR}}. {{STATE}} is the internal formatter state object as passed to a {{formatter-function}}.
     64
     65== *formatter-out-char-times
     66
     67 [procedure] (*formatter-out-char-times STATE TIMES CHAR)
     68
     69Output the {{CHAR}} N {{TIMES}}. {{STATE}} is the internal formatter state object as passed to a {{formatter-function}}.
     70
     71== *formatter-out-char-list
     72
     73 [procedure] (*formatter-out-char-list STATE LIST-OF-CHAR)
     74
     75Output the {{LIST-OF-CHAR}}. {{STATE}} is the internal formatter state object as passed to a {{formatter-function}}.
     76
     77== *formatter-out-string
     78
     79 [procedure] (*formatter-out-string STATE STRING)
     80
     81Output the {{STRING}}. {{STATE}} is the internal formatter state object as passed to a {{formatter-function}}.
    7682
    7783== format
     
    434440;{{*formatter-cl*}}: All of the above.
    435441
     442== Example
     443
     444=== format
     445
     446<enscript highlight=scheme>
     447(use format-modular)
     448(format #f "Found: [~D]: ~A~%" 12 "objects")
     449</enscript>
     450
     451=== make-format-function
     452
     453<enscript highlight=scheme>
     454(use format-modular)
     455
     456(define fprintf
     457  (make-format-function #f #\%
     458    `(((#\d ,(formatter-padded display))
     459       (#\s ,(formatter-padded write))))))
     460
     461(fprintf #t "Found: [%d]: %s\n" 12 "objects")
     462</enscript>
     463
     464== Known limitations
     465
     466Chicken doesn't have support for output port column position. Since a new state is created upon each invocation
     467the format output column position has no "memory", thus {{~&}} is accurate only within a single invocation.
     468
    436469== History
    437470
Note: See TracChangeset for help on using the changeset viewer.