fmt

A new formatting library

http://github.com/cdornan/fmt

LTS Haskell 22.42:0.6.3.0
Stackage Nightly 2024-11-18:0.6.3.0
Latest on Hackage:0.6.3.0

See all snapshots fmt appears in

BSD-3-Clause licensed by Artyom Kazak, Dmitry Kovanikov
Maintained by Chris Dornan
This version can be pinned in stack with:fmt-0.6.3.0@sha256:2c10630e2fd36a652273973f60e72dcd52867559d0e5f4f08030ef5b5c6c4c47,5370

Module documentation for 0.6.3.0

Used by 4 packages in nightly-2022-11-17(full list with versions):
columnar, enum-text, optparse-enum, rg

A new formatting library that tries to be simple to understand while still being powerful and providing more convenience features than other libraries (like functions for pretty-printing maps and lists, or a function for printing arbitrary datatypes using generics).

A comparison with other libraries:

  • printf (from Text.Printf) takes a formatting string and uses some type tricks to accept the rest of the arguments polyvariadically. It's very concise, but there are some drawbacks – it can't produce Text (you'd have to T.pack it every time) and it doesn't warn you at compile-time if you pass wrong arguments or not enough of them.

  • text-format takes a formatting string with curly braces denoting places where arguments would be substituted (the arguments themselves are provided via a tuple). If you want to apply formatting to some of the arguments, you have to use one of the provided formatters. Like printf, it can fail at runtime, but at least the formatters are first-class (and you can add new ones).

  • formatting takes a formatting template consisting of pieces of strings interleaved with formatters; this ensures that arguments always match their placeholders. formatting provides lots of formatters and generally seems to be the most popular formatting library here. Unfortunately, at least in my experience writing new formatters can be awkward and people sometimes have troubles understanding how formatting works.

  • fmt (i.e. this library) provides formatters that are ordinary functions, and a bunch of operators for concatenating formatted strings; those operators also do automatic conversion. There are some convenience formatters which aren't present in formatting (like ones for formatting maps, lists, converting to base64, etc). Some find the operator syntax annoying, while others like it.

Changes

0.6.3.0

  • Add support for deriving ... via GenericBuildable T

0.6.2.0

  • Cleared hspec upper bound
  • Qualified all Data.List imports
  • Fixed tests to work with newer (>=0.4) neat-interpolation (#30)
  • Adjusted lower bounds of formatting dependency to avoid unsigned 0 issues (#31)
  • fixed floatF handling of negative numbers (#36)
  • unconfused ||++| and |++|| (#29)

0.6.1.2

  • Bumped the hspec upper bound.
  • Fixed doctests.

0.6.1.1

  • Added HasCallStack to partial functions.

0.6.1

  • Added instance FromBuilder ByteString (for both lazy and strict bytestrings) and instance FromBuilder BS.Builder. These instances generate UTF8-encoded bytestrings. This allows producing formatting strings for various HTTP libraries that are intent on using ByteString for text.

  • Added pretty :: (Buildable a, FromBuilder b) => a -> b for formatting anything as Buildable. There’s also prettyLn for consistency with fmt and fmtLn.

0.6

  • Switched to Buildable from formatting (since text-format is unmaintained).

  • Removed the double-conversion dependency (which was sometimes causing compilation issues). As the result, exptF, fixedF and floatF have become slower.

  • The precF formatter was removed completely because its semantics was too confusing. You can use Numeric.showGFloat to achieve a similar effect.

  • floatF now always prints a point, even if the number is integral.

  • tupleLikeF has been removed. TupleF now has an additional instance that lets tupleF be used to format lists.

  • The base16-bytestring dependency was removed.

  • Compatibility with GHC 7.6 and 7.8 was dropped.

0.5.0.0

  • From this version on, blockListF never puts blank lines between items. If you want blank lines between items, I’m afraid that you’ll have to add them manually (by e.g. adding a blank line to each item).

  • Now blockListF' can be used to create lists with custom bullets.

  • Added unwordsF and unlinesF.

  • Added the F suffix to indent and indent'.

0.4.0.0

  • Renamed #| and |# to +| and |+ because HLint can’t handle #| and everyone uses HLint apparently.

0.3.0.0

  • Added time formatters (see Fmt.Time).

0.2.0.0

  • Changed format and formatLn to be polyvariadic.

0.1.0.0

  • Added genericF for formatting arbitrary data.

  • Changed %< and >% to #| and |# because they turn out to be easier to type.

  • Added a migration guide from formatting.

  • Changed output of eitherF.

  • Added bechmarks.

0.0.0.4

  • Added format from text-format, because in some cases it’s nicer than brackets.

  • Renamed padCenterF to padBothF.

  • Modified indent and indent' to always add newlines.

0.0.0.3

  • Wrote documentation.

  • Added some formatters:

    • indent
    • formatters for lists, maps and tuples (listF, etc)
    • octF, binF, baseF and floating-point formatters
    • hexF which works on both numbers and bytestrings
    • ordinalF and commaizeF
    • padding and trimming formatters
    • base64F and base64UrlF
    • conditionals (whenF and unlessF)

  • Merged Fmt.IO with Fmt because orphan instances are controversial.

  • Exported internal classes and functions from Fmt.Internal.

  • Added fmt and fmtLn.

  • Made all operators associate to the right (Builder documentation says it’s faster than the opposite).

  • Reexported Buildable and Builder.

0.0.0.2

  • Added >%%< so that it’d be possible to write %<a>%%<b>% instead of weird %<a%<b>%.

  • Added %<< ... >>%, which work work Show instead of Buildable. If you don’t care about speed and just want to output something, use them.

  • Added an IO () instance in Fmt.IO. If you import that module, raw formatted strings would print themselves.

  • Added tests.

  • Changed fixities of operators so that %<n+1>% would work.

  • Changed license to BSD3 since all our dependencies are BSD3 and we can’t use MIT.

0.0.0.1

First (completely experimental) release.