Sometimes the cons-based interface is too low level, and we'd rather have the lists themselves exposed. In this case, we have RSList to represent a well-formed cons list, and RSDotted to represent an improper list of the form (a b c . d). This representation is based on the structure of the parsed S-Expression, and not on how it was originally represented: thus, (a . (b)) is going to be represented as RSList[RSAtom a, RSAtom b] despite having been originally represented as a dotted list.

It should always be true that

fromRich (toRich x) == x

and that

toRich (fromRich x) == x

This follows the same laws as toRich.

Combine the two s-expressions into a new one.

>>> cons (A "el") (L [A "eph", A "ant"])
L [A "el",A "eph",A "ant"]

Produce the head and tail of the s-expression (if possible).

>>> uncons (L [A "el", A "eph", A "ant"])
Just (A "el",L [A "eph",A "ant"])

A shorter infix alias to grab the head and tail of an RSList.

>>> A "one" ::: L [A "two", A "three"]
RSList [RSAtom "one",RSAtom "two",RSAtom "three"]

A shorter alias for RSAtom

>>> A "elephant"
RSAtom "elephant"

A shorter alias for RSList

>>> L [A "pachy", A "derm"]
RSList [RSAtom "pachy",RSAtom "derm"]

A shorter alias for RSDotted

>>> DL [A "pachy"] "derm"
RSDotted [RSAtom "pachy"] "derm"

A shorter alias for RSList []

>>> Nil
RSList []

A traversal with access to the first element of a pair.

>>> import Lens.Family
>>> set _car (A "elephant") (L [A "one", A "two", A "three"])
L [A "elelphant",A "two",A "three"]
>>> set _car (L [A "two", A "three"]) (DL [A "one"] "elephant")
DL [L[A "two",A "three"]] "elephant"

A traversal with access to the second element of a pair. Using this to modify an s-expression may result in changing the constructor used, changing a list to a dotted list or vice versa.

>>> import Lens.Family
>>> set _cdr (A "elephant") (L [A "one", A "two", A "three"])
DL [A "one"] "elephant"
>>> set _cdr (L [A "two", A "three"]) (DL [A "one"] "elephant")
L [A "one",A "two",A "three"]

Utility function for parsing a pair of things: this parses a two-element list, and not a cons pair.

>>> fromPair (isAtom "pachy") (asAtom return) (L [A "pachy", A "derm"])
Right ((), "derm")
>>> fromPair (isAtom "pachy") fromAtom (L [A "pachy"])
Left "Expected two-element list"

Utility function for parsing a proper list of things.

>>> fromList fromAtom (L [A "this", A "that", A "the-other"])
Right ["this","that","the-other"]
>>> fromList fromAtom (DL [A "this", A "that"] "the-other"])
Left "asList: expected proper list; found dotted list"

Utility function for parsing a single atom

>>> fromAtom (A "elephant")
Right "elephant"
>>> fromAtom (L [A "elephant"])
Left "fromAtom: expected atom; found list"

Parses a two-element list using the provided function.

>>> let go (A l) (A r) = return (l ++ r); go _ _ = Left "expected atoms"
>>> asPair go (L [A "pachy", A "derm"])
Right "pachyderm"
>>> asPair go (L [A "elephant"])
Left "asPair: expected two-element list; found list of length 1"

Parse an arbitrary-length list using the provided function.

>>> let go xs = concat <$> mapM fromAtom xs
>>> asList go (L [A "el", A "eph", A "ant"])
Right "elephant"
>>> asList go (DL [A "el", A "eph"] "ant")
Left "asList: expected list; found dotted list"

Match a given literal atom, failing otherwise.

>>> isAtom "elephant" (A "elephant")
Right ()
>>> isAtom "elephant" (L [A "elephant"])
Left "isAtom: expected atom; found list"

Match an empty list, failing otherwise.

>>> isNil (L [])
Right ()
>>> isNil (A "elephant")
Left "isNil: expected nil; found atom"

Parse an atom using the provided function.

>>> import Data.Char (toUpper)
>>> asAtom (return . map toUpper) (A "elephant")
Right "ELEPHANT"
>>> asAtom (return . map toUpper) (L [])
Left "asAtom: expected atom; found list"

Parse an assoc-list using the provided function.

>>> let def (x, y) = do { a <- fromAtom x; b <- fromAtom y; return (a ++ ": " ++ b) }
>>> let defList xs = do { defs <- mapM def xs; return (unlines defs) }
>>> asAssoc defList (L [ L [A "legs", A "four"], L [ A "trunk", A "one"] ])
Right "legs: four\ntrunk: one\n"
>>> asAssoc defList (L [ L [A "legs", A "four"], L [ A "elephant"] ])
Left "asAssoc: expected pair; found list of length 1"