kozross / static-text

Lists, Texts, ByteStrings and Vectors with type-encoded length

static-text: lists, Texts, ByteStrings and Vectors of statically known length

static-text provides type-level safety for basic operations on string-like types (finite lists of elements), such as Data.Text, String (and all lists), Data.ByteString and Data.Vector. Use it when you need static guarantee on lengths of strings produced in your code.

An example application would be a network exchange protocol built of packets with fixed-width fields:

{-# LANGUAGE DataKinds #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE TemplateHaskell #-}
import Data.ByteString.Char8 (ByteString, pack)
import Data.StaticText

mkPacket :: ByteString -> Static ByteString 32
mkPacket inp =
  -- 5-character version signature
  $(st "PKT10") `append`
  -- 25-character payload
  payload `append`
  -- 2-character payload checksum
  checksum
  where
    payload = createLeft 0x20 inp
    checksum :: Static ByteString 2
    checksum = createLeft 0x20 $
               pack $ show $ Data.StaticText.length payload `mod` 100

message :: Static ByteString 64
message = mkPacket "Hello" `append` mkPacket "world"

main :: IO ()
main = print message

Please consult the Hackage page for static-text for documentation and examples.

Alternatives

The emphasis of static-text is on type-safe padding/truncation and type-safe string literals. Other similar libraries may suit different use cases:

• vector-sized and fixed-vector: full support for Vector API, but not string-like types.