Data Structures
struct	_formathandler
	Structure used to generate chains of format handlers. More...

struct	format_interface_t
	Interface returned to other modules which require integration with the pipeline. More...

Typedefs
typedef struct _formathandler	formathandler_t
	Opaque handle to the format handler. More...

Detailed Description

The format module exposes formatting capability to modules. This permits the centralisation of all formatting functionality.

The format module permits chains of formatters to built with the output of one formatter being the input to the next in the chain.

It should be loaded into the transformer using the following configuration option in transformer.conf:

add-module format

Examples

format_interface_t *format_interface;
...
formathandler_t *format = format_interface->format_parse("strip:where=start,where=end;align:width=10,align=centre;");
char *ret = format_interface->format_apply(format,"      HELLO    ");
assert(strcmp(ret,"  HELLO   ") == 0);
...
free(ret);

This example shows a sample usage of the format API and demonstrates chaining of format handlers together to perform a complex formatting action, in this case removing white space from the start and end of the string, and then placing the stripped text in the centre of a window 10 characters wide.

Alignment

The align:; formatter performs alignment within a given window size

Name	Default	Desc
width	-	Width of the window in which to perform the alignment</tr
align	-	Alignment: "centre","left", "right"

Timestamp formatter

The date:; formatter permits the transformation of timestamps between various formats as well as being able to format the current time into any timestamp format

No timezone conversions take place however.

Name	Default	Desc
from	-	The format of the incoming timestamp. If none is given then the current time is taken.
to	-	The format for the outgoing timestamp

Example

The format below will transform: "27.06.2005 13:18:01" into "13:18"

date:from=%d.%m.%Y %H:%M:%S,to=%H:%M;

The following conversion formats should be supported:

Format string	Explanation
%a	is replaced by the locale's abbreviated weekday name.
%A	is replaced by the locale's full weekday name.
%b	is replaced by the locale's abbreviated month name.
%B	is replaced by the locale's full month name.
%c	is replaced by the locale's appropriate date and time representation.
%C	is replaced by the century number (the year divided by 100 and truncated to an integer) as a decimal number [00-99].
%d	is replaced by the day of the month as a decimal number [01,31].
%D	same as m/d/y.
%e	is replaced by the day of the month as a decimal number [1,31]; a single digit is preceded by a space.
%h	same as b.
%H	is replaced by the hour (24-hour clock) as a decimal number [00,23].
%I	is replaced by the hour (12-hour clock) as a decimal number [01,12].
%j	is replaced by the day of the year as a decimal number [001,366].
%m	is replaced by the month as a decimal number [01,12].
%M	is replaced by the minute as a decimal number [00,59].
%n	is replaced by a newline character.
%p	is replaced by the locale's equivalent of either a.m. or p.m.
%r	is replaced by the time in a.m. and p.m. notation; in the POSIX locale this is equivalent to I:M:S p.
%R	is replaced by the time in 24 hour notation (H:M).
%s	can be used to parse the time in seconds since the epoch.
%S	is replaced by the second as a decimal number [00,61].
%t	is replaced by a tab character.
%T	is replaced by the time (H:M:S).
%u	is replaced by the weekday as a decimal number [1,7], with 1 representing Monday.
%U	is replaced by the week number of the year (Sunday as the first day of the week) as a decimal number [00,53].
%V	is replaced by the week number of the year (Monday as the first day of the week) as a decimal number [01,53]. If the week containing 1 January has four or more days in the new year, then it is considered week 1. Otherwise, it is the last week of the previous year, and the next week is week 1.
%w	is replaced by the weekday as a decimal number [0,6], with 0 representing Sunday.
%W	is replaced by the week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Monday are considered to be in week 0.
%x	is replaced by the locale's appropriate date representation.
%X	is replaced by the locale's appropriate time representation.
%y	is replaced by the year without century as a decimal number [00,99].
%Y	is replaced by the year with century as a decimal number.
%Z	is replaced by the timezone name or abbreviation, or by no bytes if no timezone information exists.
%%	is replaced by %.

If a conversion specification does not correspond to any of the above, the behaviour is undefined.

Decimal place formatter

The dp:; formatter formats numbers to a defined number of decimal places

Arguments

Name	Default	Desc
precision	-	Number of decimal places to convert the result to (must be defined)
places	-	An alias for precision
mode	truncation	Mode of operation: "round" or "truncation"

Example

The following format will format a numerical value to 5 decimal places, performing rounding to calculate the last decimal place:

dp:places=5,mode=round;

It's recommended that the dp: formatter is combined with the frac: formatter to ensure that the number is decimal before calculating the decimal places, for example:

frac:;dp:places=5,mode=round;

Fraction formatter

The frac:; formatter resolves fractions into decimals.

Arguments

Name	Default	Desc
precision	10	Number of decimal places to convert the result to

Significant figures formatter

The sigfig:; formatter formats numbers to a defined number of figures

Arguments

Name	Default	Desc
places	-	Number of significant figures to convert the result to (must be defined)

Example

The following format will format a numerical value to 4 signficant figures

sigfig:places=4;

It's recommended that the dp: formatter is combined with the frac: formatter to ensure that the number is decimal before calculating the decimal places, for example:

frac:;sigfig:places=4;

will format an input of "1" to an output value of "1.000"

The space stripping format

The stripspace:; formatter can remove space from the start or the end of a string

Name	Default	Desc
where	-	Where to strip the space from: "start" or "end". Multiple where parameters can be specified in a format string.
at	-	Synonym for "where"
minlen	-	The minimum length of the string after white space has been removed. If it's less than this then the formatter fails.

Uppercase formatter

The strupper:; formatter permits the transformation of string to uppercase. Characters which aren't lower case will be ignored.

Arguments

None

Lowercase formatter

The strlower:; formatter permits the transformation of string to lowercase. Characters which aren't upper case will be ignored.

Arguments

None

The zero replacement formatter

The zero:; formatter can replace non-numeric values or empty strings with a 0.

Name	Default	Desc
when	-	When to replace the value with a "0", can be either "empty" or "nonnumeric". Multiple when parameters may be specified within a format string.
if	-	Synomym for "when"

Care should be taken when using the zero:; formatter, fractions will not be recognised as a number and as such will be replaced with a zero. Thus when constructing formatter chains, it's recommended that the frac: formatter is earlier in the chain than zero:

Typedef Documentation

typedef struct _formathandler formathandler_t

Opaque handle to the format handler.

Data Structures

Typedefs

Detailed Description

Typedef Documentation