Language.SexpGrammar

Write your grammar once and get both parser and pretty-printer, for free.

data Person = Person
  { pName    :: String
  , pAddress :: String
  , pAge     :: Maybe Int
  } deriving (Show)

personGrammar :: SexpG Person
personGrammar =
  $(grammarFor 'Person) .               -- construct Person from
    list (                              -- a list with
      el (sym "person") >>>             -- symbol "person",
      el string'        >>>             -- some string,
      props (                           -- and properties
        Kw "address" .:  string' >>>    -- :address with string value,
        Kw "age"     .:? int ))         -- and optional :age int property

So now we can use personGrammar to parse S-expessions to Person record and pretty-print any Person back to S-expression.

(person "John Doe" :address "42 Whatever str." :age 25)

will parse into:

Person {pName = "John Doe", pAddress = "42 Whatever str.", pAge = Just 25}

and the record will pretty-print back into:

(person "John Doe" :address "42 Whatever str." :age 25)

Grammar types diagram:

    --------------------------------------
    |              AtomGrammar           |
    --------------------------------------
        ^
        |  atomic grammar combinators
        v
------------------------------------------------------
|                      SexpGrammar                   |
------------------------------------------------------
        | list, vect     ^              ^
        v                | el, rest     |
    ----------------------------------  |
    |           SeqGrammar           |  |
    ----------------------------------  | (.:)
             | props                    | (.:?)
             v                          |
         -------------------------------------
         |             PropGrammar           |
         -------------------------------------

Documentation

data Sexp

Sexp ADT

Constructors

Atom !Position !Atom

List !Position [Sexp]

Vector !Position [Sexp]

Quoted !Position Sexp

Instances

Eq Sexp

Methods

(==) :: Sexp -> Sexp -> Bool

(/=) :: Sexp -> Sexp -> Bool

Ord Sexp

Methods

compare :: Sexp -> Sexp -> Ordering

(<) :: Sexp -> Sexp -> Bool

(<=) :: Sexp -> Sexp -> Bool

(>) :: Sexp -> Sexp -> Bool

(>=) :: Sexp -> Sexp -> Bool

max :: Sexp -> Sexp -> Sexp

min :: Sexp -> Sexp -> Sexp

Show Sexp

Methods

showsPrec :: Int -> Sexp -> ShowS

show :: Sexp -> String

showList :: [Sexp] -> ShowS

data Atom

Sexp atom types

Constructors

AtomBool Bool

AtomInt Integer

AtomReal Scientific

AtomString Text

AtomSymbol Text

AtomKeyword Kw

Instances

Eq Atom

Methods

(==) :: Atom -> Atom -> Bool

(/=) :: Atom -> Atom -> Bool

Ord Atom

Methods

compare :: Atom -> Atom -> Ordering

(<) :: Atom -> Atom -> Bool

(<=) :: Atom -> Atom -> Bool

(>) :: Atom -> Atom -> Bool

(>=) :: Atom -> Atom -> Bool

max :: Atom -> Atom -> Atom

min :: Atom -> Atom -> Atom

Show Atom

Methods

showsPrec :: Int -> Atom -> ShowS

show :: Atom -> String

showList :: [Atom] -> ShowS

newtype Kw

Keyword newtype wrapper to distinguish keywords from symbols

Constructors

Kw

Fields

• unKw :: Text

Instances

Eq Kw

Methods

(==) :: Kw -> Kw -> Bool

(/=) :: Kw -> Kw -> Bool

Ord Kw

Methods

compare :: Kw -> Kw -> Ordering

(<) :: Kw -> Kw -> Bool

(<=) :: Kw -> Kw -> Bool

(>) :: Kw -> Kw -> Bool

(>=) :: Kw -> Kw -> Bool

max :: Kw -> Kw -> Kw

min :: Kw -> Kw -> Kw

Show Kw

Methods

showsPrec :: Int -> Kw -> ShowS

show :: Kw -> String

showList :: [Kw] -> ShowS

data Grammar g t t'

Instances

Category * (Grammar c)

Methods

id :: cat a a

(.) :: cat b c -> cat a b -> cat a c

Semigroup (Grammar c t1 t2)

Methods

(<>) :: Grammar c t1 t2 -> Grammar c t1 t2 -> Grammar c t1 t2

sconcat :: NonEmpty (Grammar c t1 t2) -> Grammar c t1 t2

stimes :: Integral b => b -> Grammar c t1 t2 -> Grammar c t1 t2

type SexpG a = forall t. Grammar SexpGrammar (Sexp :- t) (a :- t)

Grammar which matches Sexp to a value of type a and vice versa.

type SexpG_ = forall t. Grammar SexpGrammar (Sexp :- t) t

Grammar which pattern matches Sexp and produces nothing, or consumes nothing but generates some Sexp.

data h :- t infixr 5

Constructors

h :- t infixr 5

Instances

Functor ((:-) h)

Methods

fmap :: (a -> b) -> (h :- a) -> h :- b

(<$) :: a -> (h :- b) -> h :- a

(Eq t, Eq h) => Eq ((:-) h t)

Methods

(==) :: (h :- t) -> (h :- t) -> Bool

(/=) :: (h :- t) -> (h :- t) -> Bool

(Show t, Show h) => Show ((:-) h t)

Methods

showsPrec :: Int -> (h :- t) -> ShowS

show :: (h :- t) -> String

showList :: [h :- t] -> ShowS

Combinators

Primitive grammars

iso :: (a -> b) -> (b -> a) -> Grammar g (a :- t) (b :- t)

Make a grammar from a total isomorphism on top element of stack

osi :: (b -> a) -> (a -> b) -> Grammar g (a :- t) (b :- t)

Make a grammar from a total isomorphism on top element of stack (flipped)

partialIso :: String -> (a -> b) -> (b -> Either Mismatch a) -> Grammar g (a :- t) (b :- t)

Make a grammar from a partial isomorphism which can fail during backward run

partialOsi :: String -> (b -> a) -> (a -> Either Mismatch b) -> Grammar g (a :- t) (b :- t)

Make a grammar from a partial isomorphism which can fail during forward run

push :: Eq a => a -> Grammar g t (a :- t)

Unconditionally push given value on stack, i.e. it does not consume anything on parsing. However such grammar expects the same value as given one on the stack during backward run.

pushForget :: a -> Grammar g t (a :- t)

Same as push except it does not check the value on stack during backward run. Potentially unsafe as it "forgets" some data.

Atom grammars

bool :: SexpG Bool

Define an atomic Bool grammar

integer :: SexpG Integer

Define an atomic Integer grammar

int :: SexpG Int

Define an atomic Int grammar

real :: SexpG Scientific

Define an atomic real number (Scientific) grammar

double :: SexpG Double

Define an atomic double precision floating point number (Double) grammar

string :: SexpG Text

Define an atomic string (Text) grammar

symbol :: SexpG Text

Define a grammar for a symbol (Text)

keyword :: SexpG Kw

Define a grammar for a keyword

string' :: SexpG String

Define an atomic string ([Char]) grammar

symbol' :: SexpG String

Define a grammar for a symbol ([Char])

enum :: (Enum a, Bounded a, Eq a, Data a) => SexpG a

Define a grammar for an enumeration type. Automatically derives all symbol names from data constructor names and "lispifies" them.

sym :: Text -> SexpG_

Define a grammar for a constant symbol

kw :: Kw -> SexpG_

Define a grammar for a constant keyword

Complex grammars

list :: Grammar SeqGrammar t t' -> Grammar SexpGrammar (Sexp :- t) t'

Define a sequence grammar inside a list

vect :: Grammar SeqGrammar t t' -> Grammar SexpGrammar (Sexp :- t) t'

Define a sequence grammar inside a vector

Sequence grammars

el :: Grammar SexpGrammar (Sexp :- a) b -> Grammar SeqGrammar a b

Define a sequence element grammar

rest :: Grammar SexpGrammar (Sexp :- a) (b :- a) -> Grammar SeqGrammar a ([b] :- a)

Define a grammar for rest of the sequence

props :: Grammar PropGrammar a b -> Grammar SeqGrammar a b

Define a property list grammar on the rest of the sequence. The remaining sequence must be empty or start with a keyword and its corresponding value and continue with the sequence built by the same rules.

E.g.

:kw1 <val1> :kw2 <val2> ... :kwN <valN>

Property grammars

(.:) :: Kw -> Grammar SexpGrammar (Sexp :- t) (a :- t) -> Grammar PropGrammar t (a :- t)

Define property pair grammar

(.:?) :: Kw -> Grammar SexpGrammar (Sexp :- t) (a :- t) -> Grammar PropGrammar t (Maybe a :- t)

Define optional property pair grammar

Utility grammars

position :: Grammar SexpGrammar (Sexp :- t) (Position :- (Sexp :- t))

Get position of Sexp. Doesn't consume Sexp and doesn't have any effect on backward run.

pair :: Grammar g (b :- (a :- t)) ((a, b) :- t)

Construct pair from two top elements of stack

unpair :: Grammar g ((a, b) :- t) (b :- (a :- t))

Deconstruct pair into two top elements of stack

swap :: Grammar g (b :- (a :- t)) (a :- (b :- t))

Swap two top elements of stack. Useful for defining grammars for data constructors with inconvenient field order.

E.g. consider a data type, which has field order different from what would like to display to user:

data Command = Command { args :: [String], executable :: FilePath }

In S-expression executable should go first:

commandGrammar =
  $(grammarFor 'Command) .
    list ( el (sym "call") >>>  -- symbol "call"
           el string'      >>>  -- executable name
           rest string'    >>>  -- arguments
           swap )

coproduct :: [Grammar g a b] -> Grammar g a b

Combine several alternative grammars into one grammar. Useful for defining grammars for sum types.

E.g. consider a data type:

data Maybe a = Nothing | Just a

A total grammar which would handle both cases should be constructed with coproduct combinator or with Semigroup's instance.

maybeGrammar :: SexpG a -> SexpG (Maybe a)
maybeGrammar g =
  coproduct
    [ $(grammarFor 'Nothing) . kw (Kw "nil")
    , $(grammarFor 'Just)    . g
    ]

Grammar types

data SexpGrammar a b

data AtomGrammar a b

data SeqGrammar a b

data PropGrammar a b

Decoding and encoding (machine-oriented)

decode :: SexpIso a => Text -> Either String a

Deserialize a value from a lazy ByteString. The input must contain exactly one S-expression. Comments are ignored.

decodeWith :: SexpG a -> Text -> Either String a

Like decode but uses specified grammar.

encode :: SexpIso a => a -> Either String ByteString

Serialize a value as a lazy ByteString with a non-formatted S-expression

encodeWith :: SexpG a -> a -> Either String ByteString

Like encode but uses specified grammar.

Parsing and printing (human-oriented)

decodeNamed :: SexpIso a => FilePath -> Text -> Either String a

Parse a value from ByteString. The input must contain exactly one S-expression. Unlike decode it takes an additional argument with a file name which is being parsed. It is used for error messages.

decodeNamedWith :: SexpG a -> FilePath -> Text -> Either String a

Like decodeNamed but uses specified grammar.

encodePretty :: SexpIso a => a -> Either String Text

Pretty-prints a value serialized to a lazy ByteString.

encodePrettyWith :: SexpG a -> a -> Either String Text

Like encodePretty but uses specified grammar.

Parsing and encoding to Sexp

parseSexp :: SexpG a -> Sexp -> Either String a

Run grammar in parsing direction

genSexp :: SexpG a -> a -> Either String Sexp

Run grammar in generating direction

data Mismatch

Data type to encode mismatches during parsing or generation, kept abstract. It is suggested to use expected and unexpected constructors to build a mismatch report.

Instances

Eq Mismatch

Methods

(==) :: Mismatch -> Mismatch -> Bool

(/=) :: Mismatch -> Mismatch -> Bool

Show Mismatch

Methods

showsPrec :: Int -> Mismatch -> ShowS

show :: Mismatch -> String

showList :: [Mismatch] -> ShowS

Semigroup Mismatch

Methods

(<>) :: Mismatch -> Mismatch -> Mismatch

sconcat :: NonEmpty Mismatch -> Mismatch

stimes :: Integral b => b -> Mismatch -> Mismatch

Monoid Mismatch

Methods

mempty :: Mismatch

mappend :: Mismatch -> Mismatch -> Mismatch

mconcat :: [Mismatch] -> Mismatch

Pretty Mismatch

Methods

pretty :: Mismatch -> Doc

prettyList :: [Mismatch] -> Doc

expected :: Text -> Mismatch

Construct a mismatch report with specified expectation. Can be appended to other expectations and unexpected reports to clarify a mismatch.

unexpected :: Text -> Mismatch

Construct a mismatch report with information what has been occurred during processing but is not expected.

Typeclass for Sexp grammars

class SexpIso a where

Methods

sexpIso :: SexpG a

sexpIso :: (Enum a, Bounded a, Eq a, Data a) => SexpG a

Instances

SexpIso Bool

Methods

sexpIso :: SexpG Bool

SexpIso Double

Methods

sexpIso :: SexpG Double

SexpIso Int

Methods

sexpIso :: SexpG Int

SexpIso Integer

Methods

sexpIso :: SexpG Integer

SexpIso Scientific

Methods

sexpIso :: SexpG Scientific

SexpIso Text

Methods

sexpIso :: SexpG Text

SexpIso a => SexpIso [a]

Methods

sexpIso :: SexpG [a]

SexpIso a => SexpIso (Maybe a)

Methods

sexpIso :: SexpG (Maybe a)

SexpIso a => SexpIso (NonEmpty a)

Methods

sexpIso :: SexpG (NonEmpty a)

(Ord a, SexpIso a) => SexpIso (Set a)

Methods

sexpIso :: SexpG (Set a)

(SexpIso a, SexpIso b) => SexpIso (a, b)

Methods

sexpIso :: SexpG (a, b)

(Ord k, SexpIso k, SexpIso v) => SexpIso (Map k v)

Methods

sexpIso :: SexpG (Map k v)