text-format-heavy README
========================
[](https://travis-ci.org/portnov/text-format-heavy)
This is Haskell string formatting library, which prefers functionality and
extendability over light weight and (probably, in some cases) performance.
This library is more or less analog of Python's string.format function, and
has similar syntax. It also exposes all required interfaces to extend and
customize it.
Most notable features are:
* Automatically numbered variable placeholders (`{}`);
* Positional variable placeholders (`{1}`);
* Named variable placeholders (`{name}`);
* Placeholders can be used in any order; one variable can be used several
times or not used at all.
* Specific format can be used for each variable substitution (`{0:+8.4}`).
Formatting strings are present by `Format` type. Values of this type can be
parsed from lazy Text, or can be entered as string literals, since `Format`
implements `IsString`.
There are two syntaxes of formatting strings defined by this package:
* Default Python-like syntax, which is generally described as "anything in
braces is a variable substitution". `instance IsString Format` uses this
syntax.
* Alternative Shell-like syntax, which is generally described as "anything
after dollar sign is a variable substitution".
It is possible to implement custom syntaxes of format strings: you just need to
parse instances of `Format` type from some sort of strings.
The `format` function takes a `Format` specification and a container with
variables. Container types are generalized by `VarContainer` type class.
Standard container implementations include:
* `Single` type for case when you need to pass only one variable.
* Tuples and lists. These contain numbered variables, i.e. `{0}`, `{1}`, etc.
* `[(Text, a)]` and `Map Text a`. These contain named variables, i.e.
`{name}`.
One can implement custom variable containers, for example some record types.
Types of variables that can be used for subsitiution are generalized by
`Formatable` type class. Each implementation defines default value formatting
rules, and a syntax of variable format specification. For example, for
integers, floats and strings, python-like syntax is used. Standard set of
variable types includes:
* Integers (`Int`, `Integer`, `Int8..64`, `Word8..64`, others can be easily added);
* Floats (`Float` and `Double`);
* Strings (`String`, lazy and strict `ByteString`, lazy and strict `Text`);
* Booleans;
* Time/date values from Data.Time.
* Any instance of `Show` type class can be used by packing it into `Shown`
constructor.
One can implement custom variable types.
For examples, please refer to [GitHub wiki][1] and `examples/`
directory in this repo. There are also some examples in haddock documentation.
License: BSD3.
[1]: https://github.com/portnov/text-format-heavy/wiki