Core.Encoding.External

Quite frequently you will find yourself needing to convert between a rich semantic Haskell data type and a textual representation of that type which we call the external representation of a value. The external representation of the value is authoriative and is meant to be re-readable even in the face of changing implemetations on the program side.

Note that externalizing is not quite the same as serializing. If you have more complex data structures (ie rich types or nesting) then a simple text string will probably not be sufficient to convey sufficient information to represent it accurately. Serializing is focused on both performance encoding and decoding, and efficiency of the representation when transmitted over the wire. Of course, the obvious benefits of efficiency didn't stop the entire computer industry from near universal adoption of JSON as an interchange format, so there is, perhaps, no hope for us.

You can, however, regain some of your sanity by ensuring that the individual fields of a larger structure are safe, and that's where the externalizing machinery in this module comes in.

If you have read this far and think we are describing something similar to Haskell's Show, Python's repr() or Java's toString() you would be correct, but at the level of primative and simple types we are providing the ability to marshall them to a clean UTF-8 representation and to unmarshall them back into Haskell values again.

The other major use case for this module is as a helper to read user input; see queryOptionValue' for an example that makes use of this.

Notes for implementators

Postel's dictum to "be conservative in what you produce but liberal in what you accept" describes the intent of this module. If you are implementing an instance of Externalize then you might consider being flexible as possible when parsing with parseExternal, within the constraints of having to read a given value with exact fidelity. But when outputing a value with formatExternal you should be correcting the representation of the value to a canonical, stable form, even if the original input was written differently. See the discussion of creating Time types from varying inputs for an example.

Documentation

class Externalize ξ where

Convert between the internal Haskell representation of a data type and an external, textual form suitable for visualization, onward transmission, or archival storage.

It is expected that a valid instance of Externalize allows you to round-trip through it:

>>> formatExternal (42 :: Int))
"42"

>>> fromJust (parseExternal "42") :: Int
42

with the usual caveat about needing to ensure you've given enough information to the type-checker to know which instance you're asking for.

There is a general implementatation that goes though Show and Read via String but if you know you have a direct way to render or parse a type into a sequence of characters then you can offer an instance of Externalize which does so more efficiently.

Since: 0.3.4

Methods

formatExternal :: ξ -> Rope

Convert a value into an authoritative, stable textual representation for use externally.

parseExternal :: Rope -> Maybe ξ

Attempt to read an external textual representation into a Haskell value.

Instances

Externalize Int16

Integers are represented in decimal:

42

Defined in Core.Encoding.External

Methods

formatExternal :: Int16 -> Rope

parseExternal :: Rope -> Maybe Int16

Externalize Int32

Integers are represented in decimal:

42

Defined in Core.Encoding.External

Methods

formatExternal :: Int32 -> Rope

parseExternal :: Rope -> Maybe Int32

Externalize Int64

Integers are represented in decimal:

42

Defined in Core.Encoding.External

Methods

formatExternal :: Int64 -> Rope

parseExternal :: Rope -> Maybe Int64

Externalize Int8

Integers are represented in decimal:

42

Defined in Core.Encoding.External

Methods

formatExternal :: Int8 -> Rope

parseExternal :: Rope -> Maybe Int8

Externalize Word16

Words are likewise represented in decimal:

65535

Defined in Core.Encoding.External

Methods

formatExternal :: Word16 -> Rope

parseExternal :: Rope -> Maybe Word16

Externalize Word32

Words are likewise represented in decimal:

4294967295

Defined in Core.Encoding.External

Methods

formatExternal :: Word32 -> Rope

parseExternal :: Rope -> Maybe Word32

Externalize Word64

Words are likewise represented in decimal:

18446744073709551615

Defined in Core.Encoding.External

Methods

formatExternal :: Word64 -> Rope

parseExternal :: Rope -> Maybe Word64

Externalize Word8

Words are likewise represented in decimal:

255

Defined in Core.Encoding.External

Methods

formatExternal :: Word8 -> Rope

parseExternal :: Rope -> Maybe Word8

Externalize Time

Timestamps are formatted as per ISO 8601:

2022-06-20T14:51:23.544826062Z

Defined in Core.Encoding.External

Methods

formatExternal :: Time -> Rope

parseExternal :: Rope -> Maybe Time

Externalize Rope

Defined in Core.Encoding.External

Methods

formatExternal :: Rope -> Rope

parseExternal :: Rope -> Maybe Rope

Externalize Scientific

Numbers are converted to scientific notation:

2.99792458e8

Defined in Core.Encoding.External

Methods

formatExternal :: Scientific -> Rope

parseExternal :: Rope -> Maybe Scientific

Externalize Day

Days are formatted as per ISO 8601:

2022-06-20

Defined in Core.Encoding.External

Methods

formatExternal :: Day -> Rope

parseExternal :: Rope -> Maybe Day

Externalize UUID

Unique identifiers are formatted as per RFC 4122:

6937e157-d041-4919-8690-4d6c12b7e0e3

Defined in Core.Encoding.External

Methods

formatExternal :: UUID -> Rope

parseExternal :: Rope -> Maybe UUID

Externalize String

Defined in Core.Encoding.External

Methods

formatExternal :: String -> Rope

parseExternal :: Rope -> Maybe String

Externalize Double

IEEE 754 floating point:

3.141592653589793

Defined in Core.Encoding.External

Methods

formatExternal :: Double -> Rope

parseExternal :: Rope -> Maybe Double

Externalize Float

IEEE 754 floating point:

3.1415927

Defined in Core.Encoding.External

Methods

formatExternal :: Float -> Rope

parseExternal :: Rope -> Maybe Float

Externalize Int

Integers are represented in decimal:

42

Defined in Core.Encoding.External

Methods

formatExternal :: Int -> Rope

parseExternal :: Rope -> Maybe Int

(Read a, Show a) => Externalize a

Defined in Core.Encoding.External

Methods

formatExternal :: a -> Rope

parseExternal :: Rope -> Maybe a