The text-format-heavy package

[ Tags: bsd3, library, text ] [ Propose Tags ]

This package contains full-featured string formatting function, similar to Python's string.format. Features include:

This package prefers functionality over "light weight" and (probably) performance. It also exposes all required interfaces to extend and customize it.

For more details, please refer to Wiki. See also the examples/ directory.

[Skip to Readme]


Change log
Dependencies base (>=4.8 && <5), bytestring (>=0.10), containers (>=0.5), data-default (>=0.7), parsec (==3.1.*), text (==1.2.*), time (>=1.5) [details]
License BSD3
Author Ilya Portnov
Category Text
Source repository head: git clone
Uploaded Tue Oct 24 12:22:08 UTC 2017 by IlyaPortnov
Distributions NixOS:
Downloads 266 total (57 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2017-10-24 [all 1 reports]
Hackage Matrix CI




Maintainer's Corner

For package maintainers and hackage trustees

Readme for text-format-heavy-

[back to package description]

text-format-heavy README

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 and examples/ directory in this repo. There are also some examples in haddock documentation.

License: BSD3.