The format-string-builder Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The format-string-builder Reference Manual

This is the format-string-builder Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 11:05:57 2020 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

A simple package implementing a DSL for generating format strings.

Introduction

Hello World

CL-USER> (define-message hello (name)
           "Hello " :str)
CL-USER> (hello "world")
Hello world
NIL

(make-format-string '(:str)) #| ==> "~a" |#
(make-format-string '((:map () :str))) #| ==> "~{~a~}" |#

(define-message print-comma-separated (values)
  (:map () :str))

Api Reference

(make-format-string spec) #| function |#

Takes a format string specification and turns it into a string.

(format* stream spec &rest args) #| macro |#

Use like CL:FORMAT, except translate a format specification to a string at macroexpansion time.

(define-message (stream-symbol &rest format-args) &body spec) #| macro |#

Defines a function that takes a stream and the arguments to be formatted and then formats the arguments to the stream. The spec is compiled to a string at macroexpansion time, so this should be reasonably efficient.

TODO: document the API for defining directives.

DSL Reference

A spec consists of operators and literals. Literals are either strings, characters or integers and they are formatted as-is via princ. There are two kinds of operators: simple operators and compound ones. Simple operators correspond to format control directives and represented in the spec by keywords such as ~A or by lists (keyword . modifiers) and they expand to the corresponding directives. Compound operators correspond to format directives that can contain other directives such as ~{~}. In a spec, these are formatted like flet function definitions:

(keyword (&rest modifiers) &body spec)

Compound operators are further divided into sectioned operators and non-sectioned ones. The difference is that, in non sectioned operators, the body is treated just as a normal spec. In sectioned ones, the body is treated as a list of items to be divided with ~;. See CLHS 22.3 for a full guide to the modifiers for the various format directives.

Simple Format Operations

Compound Format Operations

Iteration

Conditional Output (Sectioned Operators)

Case Control

Justification

TODO: finish documenting this and switch them to sectioned operators.

Miscellaneous

These are not part of Format, but are defined just to be helpful


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 format-string-builder

Author

fiddlerwoaroof

License

MIT

Description

A DSL wrapping cl:format’s syntax with something more lispy.

Dependencies
Source

format-string-builder.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 format-string-builder.asd

Location

format-string-builder.asd

Systems

format-string-builder (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 format-string-builder/package.lisp

Parent

format-string-builder (system)

Location

package.lisp

Packages

format-string-builder


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 format-string-builder/format-string-builder.lisp

Dependency

package.lisp (file)

Parent

format-string-builder (system)

Location

format-string-builder.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 format-string-builder

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: define-message NAME (STREAM-ARG &rest ARGS) &body SPEC

Define a function called NAME that takes a stream argument and a variable argument list that formats the arguments according to the spec passed as the body.

Package

format-string-builder

Source

format-string-builder.lisp (file)

Macro: format* STREAM FORMAT-SPEC &rest ARGS
Package

format-string-builder

Source

format-string-builder.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: make-format-string FORMS
Package

format-string-builder

Source

format-string-builder.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *format-string-registry*
Package

format-string-builder

Source

format-string-builder.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Macros

Macro: define-compound-format-chars &body SPECS
Package

format-string-builder

Source

format-string-builder.lisp (file)

Macro: define-format-chars &body BODY
Package

format-string-builder

Source

format-string-builder.lisp (file)

Macro: define-simple-format-chars &body SPECS
Package

format-string-builder

Source

format-string-builder.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: convert-modifier MODIFIER
Package

format-string-builder

Source

format-string-builder.lisp (file)

Function: define-compound-format-char NAME START-CHAR END-CHAR &key AT-P COLON-P
Package

format-string-builder

Source

format-string-builder.lisp (file)

Function: define-sectioned-format-char NAME START-CHAR END-CHAR &key AT-P COLON-P
Package

format-string-builder

Source

format-string-builder.lisp (file)

Function: define-simple-format-char NAME FORMAT-CHAR &key AT-P COLON-P
Package

format-string-builder

Source

format-string-builder.lisp (file)

Function: form-step FORM
Package

format-string-builder

Source

format-string-builder.lisp (file)

Function: generate-function-defs ()
Package

format-string-builder

Source

format-string-builder.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Generic functions

Generic Function: at-p OBJECT
Generic Function: (setf at-p) NEW-VALUE OBJECT
Package

format-string-builder

Methods
Method: at-p (FORMAT-STRING-COMMAND format-string-command)

automatically generated reader method

Source

format-string-builder.lisp (file)

Method: (setf at-p) NEW-VALUE (FORMAT-STRING-COMMAND format-string-command)

automatically generated writer method

Source

format-string-builder.lisp (file)

Generic Function: colon-p OBJECT
Generic Function: (setf colon-p) NEW-VALUE OBJECT
Package

format-string-builder

Methods
Method: colon-p (FORMAT-STRING-COMMAND format-string-command)

automatically generated reader method

Source

format-string-builder.lisp (file)

Method: (setf colon-p) NEW-VALUE (FORMAT-STRING-COMMAND format-string-command)

automatically generated writer method

Source

format-string-builder.lisp (file)

Generic Function: contents OBJECT
Generic Function: (setf contents) NEW-VALUE OBJECT
Package

format-string-builder

Methods
Method: contents (COMPOUND-FORMAT-STRING-COMMAND compound-format-string-command)

automatically generated reader method

Source

format-string-builder.lisp (file)

Method: (setf contents) NEW-VALUE (COMPOUND-FORMAT-STRING-COMMAND compound-format-string-command)

automatically generated writer method

Source

format-string-builder.lisp (file)

Generic Function: dispatch-command COMMAND ARGS
Package

format-string-builder

Source

format-string-builder.lisp (file)

Methods
Method: dispatch-command (COMMAND simple-format-string-command) ARGS
Method: dispatch-command (COMMAND compound-format-string-command) ARGS
Generic Function: end-char OBJECT
Generic Function: (setf end-char) NEW-VALUE OBJECT
Package

format-string-builder

Methods
Method: end-char (COMPOUND-FORMAT-STRING-COMMAND compound-format-string-command)

automatically generated reader method

Source

format-string-builder.lisp (file)

Method: (setf end-char) NEW-VALUE (COMPOUND-FORMAT-STRING-COMMAND compound-format-string-command)

automatically generated writer method

Source

format-string-builder.lisp (file)

Generic Function: format-char OBJECT
Generic Function: (setf format-char) NEW-VALUE OBJECT
Package

format-string-builder

Methods
Method: format-char (SIMPLE-FORMAT-STRING-COMMAND simple-format-string-command)

automatically generated reader method

Source

format-string-builder.lisp (file)

Method: (setf format-char) NEW-VALUE (SIMPLE-FORMAT-STRING-COMMAND simple-format-string-command)

automatically generated writer method

Source

format-string-builder.lisp (file)

Generic Function: modifiers OBJECT
Generic Function: (setf modifiers) NEW-VALUE OBJECT
Package

format-string-builder

Methods
Method: modifiers (COMPOUND-FORMAT-STRING-COMMAND compound-format-string-command)

automatically generated reader method

Source

format-string-builder.lisp (file)

Method: (setf modifiers) NEW-VALUE (COMPOUND-FORMAT-STRING-COMMAND compound-format-string-command)

automatically generated writer method

Source

format-string-builder.lisp (file)

Method: modifiers (SIMPLE-FORMAT-STRING-COMMAND simple-format-string-command)

automatically generated reader method

Source

format-string-builder.lisp (file)

Method: (setf modifiers) NEW-VALUE (SIMPLE-FORMAT-STRING-COMMAND simple-format-string-command)

automatically generated writer method

Source

format-string-builder.lisp (file)

Generic Function: print-format-modifiers COMMAND STREAM
Package

format-string-builder

Source

format-string-builder.lisp (file)

Methods
Method: print-format-modifiers (COMMAND format-string-command) S
Generic Function: print-format-representation COMMAND STREAM

Prints the appropriate control sequence to the stream passed in The :before method will print the Tilde.

Package

format-string-builder

Source

format-string-builder.lisp (file)

Methods
Method: print-format-representation (COMMAND sectioned-format-string-command) S
Method: print-format-representation (COMMAND compound-format-string-command) S after
Method: print-format-representation (COMMAND compound-format-string-command) S
Method: print-format-representation (COMMAND compound-format-string-command) S before
Method: print-format-representation (COMMAND simple-format-string-command) S
Method: print-format-representation (COMMAND format-string-command) S around
Method: print-format-representation (LITERAL string) S
Method: print-format-representation (LITERAL integer) S
Method: print-format-representation (LITERAL character) S
Method: print-format-representation (COMMANDS list) S
Generic Function: start-char OBJECT
Generic Function: (setf start-char) NEW-VALUE OBJECT
Package

format-string-builder

Methods
Method: start-char (COMPOUND-FORMAT-STRING-COMMAND compound-format-string-command)

automatically generated reader method

Source

format-string-builder.lisp (file)

Method: (setf start-char) NEW-VALUE (COMPOUND-FORMAT-STRING-COMMAND compound-format-string-command)

automatically generated writer method

Source

format-string-builder.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.5 Classes

Class: compound-format-string-command ()
Package

format-string-builder

Source

format-string-builder.lisp (file)

Direct superclasses

format-string-command (class)

Direct subclasses

sectioned-format-string-command (class)

Direct methods
Direct slots
Slot: start-char
Initargs

:start-char

Readers

start-char (generic function)

Writers

(setf start-char) (generic function)

Slot: contents
Initargs

:contents

Readers

contents (generic function)

Writers

(setf contents) (generic function)

Slot: end-char
Initargs

:end-char

Readers

end-char (generic function)

Writers

(setf end-char) (generic function)

Slot: modifiers
Initargs

:modifiers

Readers

modifiers (generic function)

Writers

(setf modifiers) (generic function)

Class: format-string-command ()
Package

format-string-builder

Source

format-string-builder.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses
Direct methods
Direct slots
Slot: at-p
Initargs

:at-p

Readers

at-p (generic function)

Writers

(setf at-p) (generic function)

Slot: colon-p
Initargs

:colon-p

Readers

colon-p (generic function)

Writers

(setf colon-p) (generic function)

Class: sectioned-format-string-command ()
Package

format-string-builder

Source

format-string-builder.lisp (file)

Direct superclasses

compound-format-string-command (class)

Direct methods

print-format-representation (method)

Class: simple-format-string-command ()
Package

format-string-builder

Source

format-string-builder.lisp (file)

Direct superclasses

format-string-command (class)

Direct methods
Direct slots
Slot: format-char
Initargs

:format-char

Readers

format-char (generic function)

Writers

(setf format-char) (generic function)

Slot: modifiers
Initargs

:modifiers

Readers

modifiers (generic function)

Writers

(setf modifiers) (generic function)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L  
Index Entry  Section

F
File, Lisp, format-string-builder.asd: The format-string-builder․asd file
File, Lisp, format-string-builder/format-string-builder.lisp: The format-string-builder/format-string-builder․lisp file
File, Lisp, format-string-builder/package.lisp: The format-string-builder/package․lisp file
format-string-builder.asd: The format-string-builder․asd file
format-string-builder/format-string-builder.lisp: The format-string-builder/format-string-builder․lisp file
format-string-builder/package.lisp: The format-string-builder/package․lisp file

L
Lisp File, format-string-builder.asd: The format-string-builder․asd file
Lisp File, format-string-builder/format-string-builder.lisp: The format-string-builder/format-string-builder․lisp file
Lisp File, format-string-builder/package.lisp: The format-string-builder/package․lisp file

Jump to:   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
A   C   D   E   F   G   M   P   S  
Index Entry  Section

(
(setf at-p): Internal generic functions
(setf at-p): Internal generic functions
(setf colon-p): Internal generic functions
(setf colon-p): Internal generic functions
(setf contents): Internal generic functions
(setf contents): Internal generic functions
(setf end-char): Internal generic functions
(setf end-char): Internal generic functions
(setf format-char): Internal generic functions
(setf format-char): Internal generic functions
(setf modifiers): Internal generic functions
(setf modifiers): Internal generic functions
(setf modifiers): Internal generic functions
(setf start-char): Internal generic functions
(setf start-char): Internal generic functions

A
at-p: Internal generic functions
at-p: Internal generic functions

C
colon-p: Internal generic functions
colon-p: Internal generic functions
contents: Internal generic functions
contents: Internal generic functions
convert-modifier: Internal functions

D
define-compound-format-char: Internal functions
define-compound-format-chars: Internal macros
define-format-chars: Internal macros
define-message: Exported macros
define-sectioned-format-char: Internal functions
define-simple-format-char: Internal functions
define-simple-format-chars: Internal macros
dispatch-command: Internal generic functions
dispatch-command: Internal generic functions
dispatch-command: Internal generic functions

E
end-char: Internal generic functions
end-char: Internal generic functions

F
form-step: Internal functions
format*: Exported macros
format-char: Internal generic functions
format-char: Internal generic functions
Function, convert-modifier: Internal functions
Function, define-compound-format-char: Internal functions
Function, define-sectioned-format-char: Internal functions
Function, define-simple-format-char: Internal functions
Function, form-step: Internal functions
Function, generate-function-defs: Internal functions
Function, make-format-string: Exported functions

G
generate-function-defs: Internal functions
Generic Function, (setf at-p): Internal generic functions
Generic Function, (setf colon-p): Internal generic functions
Generic Function, (setf contents): Internal generic functions
Generic Function, (setf end-char): Internal generic functions
Generic Function, (setf format-char): Internal generic functions
Generic Function, (setf modifiers): Internal generic functions
Generic Function, (setf start-char): Internal generic functions
Generic Function, at-p: Internal generic functions
Generic Function, colon-p: Internal generic functions
Generic Function, contents: Internal generic functions
Generic Function, dispatch-command: Internal generic functions
Generic Function, end-char: Internal generic functions
Generic Function, format-char: Internal generic functions
Generic Function, modifiers: Internal generic functions
Generic Function, print-format-modifiers: Internal generic functions
Generic Function, print-format-representation: Internal generic functions
Generic Function, start-char: Internal generic functions

M
Macro, define-compound-format-chars: Internal macros
Macro, define-format-chars: Internal macros
Macro, define-message: Exported macros
Macro, define-simple-format-chars: Internal macros
Macro, format*: Exported macros
make-format-string: Exported functions
Method, (setf at-p): Internal generic functions
Method, (setf colon-p): Internal generic functions
Method, (setf contents): Internal generic functions
Method, (setf end-char): Internal generic functions
Method, (setf format-char): Internal generic functions
Method, (setf modifiers): Internal generic functions
Method, (setf modifiers): Internal generic functions
Method, (setf start-char): Internal generic functions
Method, at-p: Internal generic functions
Method, colon-p: Internal generic functions
Method, contents: Internal generic functions
Method, dispatch-command: Internal generic functions
Method, dispatch-command: Internal generic functions
Method, end-char: Internal generic functions
Method, format-char: Internal generic functions
Method, modifiers: Internal generic functions
Method, modifiers: Internal generic functions
Method, print-format-modifiers: Internal generic functions
Method, print-format-representation: Internal generic functions
Method, print-format-representation: Internal generic functions
Method, print-format-representation: Internal generic functions
Method, print-format-representation: Internal generic functions
Method, print-format-representation: Internal generic functions
Method, print-format-representation: Internal generic functions
Method, print-format-representation: Internal generic functions
Method, print-format-representation: Internal generic functions
Method, print-format-representation: Internal generic functions
Method, print-format-representation: Internal generic functions
Method, start-char: Internal generic functions
modifiers: Internal generic functions
modifiers: Internal generic functions
modifiers: Internal generic functions

P
print-format-modifiers: Internal generic functions
print-format-modifiers: Internal generic functions
print-format-representation: Internal generic functions
print-format-representation: Internal generic functions
print-format-representation: Internal generic functions
print-format-representation: Internal generic functions
print-format-representation: Internal generic functions
print-format-representation: Internal generic functions
print-format-representation: Internal generic functions
print-format-representation: Internal generic functions
print-format-representation: Internal generic functions
print-format-representation: Internal generic functions
print-format-representation: Internal generic functions

S
start-char: Internal generic functions
start-char: Internal generic functions

Jump to:   (  
A   C   D   E   F   G   M   P   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
A   C   E   F   M   S  
Index Entry  Section

*
*format-string-registry*: Internal special variables

A
at-p: Internal classes

C
colon-p: Internal classes
contents: Internal classes

E
end-char: Internal classes

F
format-char: Internal classes

M
modifiers: Internal classes
modifiers: Internal classes

S
Slot, at-p: Internal classes
Slot, colon-p: Internal classes
Slot, contents: Internal classes
Slot, end-char: Internal classes
Slot, format-char: Internal classes
Slot, modifiers: Internal classes
Slot, modifiers: Internal classes
Slot, start-char: Internal classes
Special Variable, *format-string-registry*: Internal special variables
start-char: Internal classes

Jump to:   *  
A   C   E   F   M   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   F   P   S  
Index Entry  Section

C
Class, compound-format-string-command: Internal classes
Class, format-string-command: Internal classes
Class, sectioned-format-string-command: Internal classes
Class, simple-format-string-command: Internal classes
compound-format-string-command: Internal classes

F
format-string-builder: The format-string-builder system
format-string-builder: The format-string-builder package
format-string-command: Internal classes

P
Package, format-string-builder: The format-string-builder package

S
sectioned-format-string-command: Internal classes
simple-format-string-command: Internal classes
System, format-string-builder: The format-string-builder system

Jump to:   C   F   P   S