Description

extended formatting procedures

Author

elf

Version

Requires

Usage

(require-extension eformat)

Download

eformat.egg

Documentation

This extension provides extended formatting procedures. It is intended as a high-speed, simpler replacement for traditional text formatting procedures while keeping much of the same feel and functionality. While not every directive from Common Lisp's (format) is implemented, those directives that are should cover most of the use cases. In addition, there are several new directives to simplify frequently occurring patterns. Any suggestions for additional functionality are welcomed.

The eformat package has two major components: eformat and wrap-text. eformat outputs formatted text according to a format-string and a list of arguments. wrap-text is a flexible means of wrapping and indenting arbitrary blocks of text. Several useful auxiliary procedures have also been exported. All procedures should be thread-safe.

Core Procedures

These procedures form the core of the eformat functionality. See [Output Directives] for a list and explanation of all valid eformat format-string directives.

procedure: (eformat DESTINATION FMTSTRING [ARG ...])

Creates an output string from the FMTSTRING, substituting ARGs for the corresponding format directives. The number of ARG values must be equivalent to the number required by FMTSTRING or an error is signalled. See [Output Directives] for an explanation of all valid output directives and the number of arguments each requires. FMTSTRING must be a non-null string or an error is signalled.

DESTINATION determines how the final generated string (<ostr>) is handled according to the following table:

DESTINATION Handler Return Val Description
#f <ostr>

string

returns the generated string

#t (display <ostr>)

unspecified

displays <ostr> to (current-output-port)

2 (display <ostr> (current-error-port))

unspecified

displays <ostr> to (current-error-port)

<output-port> (display <ostr> <output-port>)

unspecified

displays <ostr> to the given output-port

<anything else> error

error

signals an error

procedure: (wrap-text STRING WRAP-COLUMN [INDENT-SPACES 0] [PRESERVE-STRUCTURE #t])

Wraps (i.e., adds implicit newlines to) STRING at the whitespace character nearest to (equivalent or less than) WRAP-COLUMN. Implicit newlines cause the following line to be indented by INDENT-SPACES. An error is signalled if INDENT-SPACES is not strictly less than WRAP-COLUMN.

Explicit newlines are any newline (or newline-equivalent) characters in the initial STRING. See the table below for descriptions of all newline-equiv whitespace. If the optional PRESERVE-STRUCTURE argument is given and #f, all whitespace chars are converted to spaces before processing. Excess whitespace is always removed from the ends of lines. After implicit newlines, whitespace is removed from the beginning of the following line as well (before adding INDENT-SPACES spaces). All whitespace characters are correctly handled, including vertical tabs and form-feeds.

Colour codes in strings (ESC [ codes m) are now properly handled for line-length calculations.

Output Directives

All directives start with a ~ (tilde). All text besides directives is added to the output-string via display. It is an error for a tilde to appear in the format string except as the start of a directive.

All modifiers are optional except where otherwise indicated. All directives are of the following form (without whitespace or brackets) and have the given default semantics:

~ [ - ] [ @ ] [ 0 ] [ & ] [ M ] [ , X ] [ . C ] D

Symbol Name Input Value Default Value Requires Forbids Description
~ (tilde)

start-indicator

 ~ NONE NONE NONE

Indicates the beginning of a format directive.

- (hyphen)

right-justify-modifier

 - NONE M @

Aligns the directive's output with the right field margin (default is left). Requires the min-length-modifier to be given.

@ (at-sign)

center-justify-modifier

 @ NONE M -

Aligns the directive's output in the center of the field (default is left). Requires the min-length-modifier to be given.

0 (zero)

zero-pad-modifier

 0 NONE M &

Pads with zeros (default is spaces). Requires the min-length-modifier to be given.

& (ampersand)

char-pad-modifier

 & NONE M 0

Pads with a character given on the command line (default is spaces). Requires the min-length-modifier to be given.

M

min-length-modifier

 exact int > 0 OR * NONE NONE NONE

Minimum field length. Will pad with the pad character (above, default is space) if the field is smaller than the size. If given as *, length is read from the argument list.

X

max-length-modifier

 exact int > 0 OR * NONE NONE NONE

Maximum field length. Trims a field to a maximum length of the given argument. If given as *, length is read from the argument list. If min-length-modifier is also given and larger than max-length-modifier, max-length-modifier takes precedence.

C

count-repeat-modifier

 exact int > 0 OR * 1 NONE NONE

Repetition count modifier. After applying all other modifiers, displays final string count times. If given as *, count is read from the argument list.

D

format-directive

 (see below) NONE NONE NONE

Format directive. REQUIRED in all cases. The table below gives all format directives and their meanings.

Each valid output directive is given below:

Directive Mnemonic Requires Forbids Ignores Args Read Action
A or a

display

 NONE NONE NONE 1

Adds the next argument to the output string via display.

S or s

write

 NONE NONE NONE 1

Adds the next argument to the output string via write.

P or p

pad

 M XC -@ 0

Adds M pad-characters (space by default, or as given by 0 or &) to the output string via display.

L or l

list display

 NONE NONE NONE 2

First arg must be a list/pair/vector (LPV). Second arg is any object to be used as a separator (SEP). Each element of LPV is added to the output string via display, with SEP added between elements.

W or w

list write

 NONE NONE NONE 2

Equivalent to L or l above, except that elements are added via write instead of display. SEP is still added via display.

B or b

binary

 NONE NONE NONE 1

Adds the next argument (an exact integer) to the output string as its binary representation. Negative numbers are translated to their twos-complement form. The number is padded to a multiple of 8 characters.

O or o

octal

 NONE NONE NONE 1

Adds the next argument (an exact integer) to the output string as its octal representation. Negative numbers are translated to their twos-complement form. The number is padded to a multiple of 3 characters. If given as O, a zero or seven (depending on sign) is always prepended to the number.

X or x

hex

 NONE NONE NONE 1

Adds the next argument (an exact integer) to the output string as its hexadecimal representation. Negative numbers are translated to their twos-complement form. The number is padded to a multiple of 2 characters. If given as X, the output will be in upper case.

H or h

hex-prefix

 NONE NONE NONE 1

Equivalent to X or x above, except that a 0x is prepended before case checking.

D or d

decimal

 NONE NONE NONE 1

Adds the next argument (an exact integer) to the output string as its decimal representation.

I or i

unsigned decimal

 NONE NONE NONE 1

Adds the next argument (an exact integer) to the output string as its decimal representation. Negative numbers are translated to their twos-complement form.

G or g

float

 MXC NONE NONE 1

Adds the next argument (a real number) to the output string. The M modifier determines the minimum field length of the integral digits. The X modifier determines the maximum field length of the integral digits. The C modifier determines the minimum number of fractional digits.

F or f

subformat

 C NONE NONE 1+C

Recursive format call. First argument must be a valid format-string. The C modifier determines the number of extra arguments to take from the list for the subformat, and may be zero.

T or t

list subformat

 C NONE NONE 3

Recursive list/vector/pair format call. First argument must be a list/vector/pair. Second argument must be any object to act as separator. Third argument must be a valid format-string. If the element(s) of LVP are LVPs, then eformat is applied to the format-string arg with the sub-LVP elements as args. Otherwise, eformat is applied to the format-string arg with the LVP arg as a single argument.

R or r

text wrap

 MXC NONE NONE 0

Wraps text. This can only occur once, and only as the first element in the format-string. (However, as subformat directives are separate calls, it may occur in subformat strings as well.) The modifiers are mapped to the arguments for wrap-text, above, in the same order.

C or c

colour code

 NONE -@0&MXC NONE 1

Inserts a colour code into text. The argument must be a colour code list, as given below. Note: an explicit reset must be given at the end of the string, or the colouration will continue.

~

tilde

 NONE -@0&MXC NONE 0

Adds a literal tilde to the output string.

Whitespace Sequences

The following table describes the whitespace characters/sequences recognised and how they are handled. The Column heading is the output column value after the whitespace is processed. All newline-equivalent sequencesgenerate explicit newlines (#\newline) rather than the original char(s).

Char(s) newline-equiv Column Description
#\space

N

 (+ column 1)

adds a single space

#\htab

N

 (+ column (- 8 (modulo column 8)))

adds spaces until an 8-space mark

#\newline

Y

 0

adds a single newline

#\return

Y

 0

adds a single newline

#\return#\newline

Y

 0

special case: adds only one newline

#\formfeed

Y

 column

adds a newline, then pads to <column> spaces

#\vtab

Y

 column

adds a newline, then pads to <column> spaces

Colour Code Lists

Colour codes are given as lists of the form:

( [ RESET ] [ ATTRIB ... ] [ FCOL [ BCOL ] ] )

All arguments are optional. It is an error for no arguments to be given. The semantics for each argument are given below. All values are symbols.

Argument Description
RESET

Specifies whether to add a colour reset before the new colour code. If RESET is set to no-reset or noreset, a reset is not added. If RESET is set to reset or default, then a colour reset is added. As resets are done by default, specifying reset is generally only necessary at the end of a string.

ATTRIB

Specifies colour/text attributes. Valid attributes are:

Attribute Description
bold

Bold colours.

underline

Underline text (may not work on all terminals).

blink

Blinking text (usually equivalent to bold).

inverse

Invert background and foreground colours.

invis or hide

Hide this text (will not work on most terminals).

standout

Equivalent to bold and inverse together.

normal

Reverses the effect of bold.

no-underline

Reverses the effect of underline.

steady

Reverses the effect of blink.

positive

Reverses the effect of inverse.

visible

Reverses the effect of invis.

FCOL

Sets the foreground colour, according to the list given below.

BCOL

Sets the background colour, according to the list given below.

Colour values may be:

  • black
  • red
  • green
  • yellow
  • blue
  • magenta
  • cyan
  • white
  • cdefault (default foreground/background colour for the terminal)

Utility Procedures

These are some (hopefully useful) utility procedures built from the eformat functionality.

procedure: (char->num DIGIT [(ORIG 0) [(OP +)]])

Applies OP to the numeric representation of DIGIT (a char in the range #\0 to #\9) and (10 * ORIG). The default behaviour (if OP is not given) allows a sequence of character digits to be translated into their numeric equivalent, respecting order of magnitude.

procedure: (errformat CALLING-PROC RETURN-ARGS FMTSTR [ARG ...])

Creates nicely-formatted error messages and signals an error. Equivalent to

(apply error (string-append "(" CALLING-PROC ") " (eformat #f FMTSTR [ARG ...])) RETURN-ARGS)

except that CALLING-PROC may be an object other than a string.

Bugs

None known

Licence

Copyright (C) 2007-2008, Lenny Frank.  All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the Software),
to deal in the Software without restriction, including without limitation 
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the 
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED AS-IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR 
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.