Colonnade.Encode

Most users of this library do not need this module. The functions here are used to build functions that apply a Colonnade to a collection of values, building a table from them. Ultimately, a function that applies a Colonnade Headed MyCell a to data will have roughly the following type:

myTableRenderer :: Foldable g => Colonnade Headed MyCell a -> g a -> MyContent

In the companion packages yesod-colonnade and reflex-dom-colonnade, functions with similar type signatures are readily available. These packages use the functions provided here in the implementations of their rendering functions. It is recommended that users who believe they may need this module look at the source of the companion packages to see an example of how this module's functions are used. Other backends are encouraged to use these functions to build monadic or monoidal content from a Colonnade.

The functions exported here take a Colonnade and convert it to a fragment of content. The functions whose names start with row take at least a Colonnade f c a and an a value to generate a row of content. The functions whose names start with header need the Colonnade f c a but not an a value since a value is not needed to build a header.

Colonnade

Types

newtype Colonnade h a c

An columnar encoding of a. The type variable h determines what is present in each column in the header row. It is typically instantiated to Headed and occasionally to Headless. There is nothing that restricts it to these two types, although they satisfy the majority of use cases. The type variable c is the content type. This can be Text, String, or ByteString. In the companion libraries reflex-dom-colonnade and yesod-colonnade, additional types that represent HTML with element attributes are provided that serve as the content type. Presented more visually:

            +---- Value consumed to build a row
            |
            v
Colonnade h a c
          ^   ^
          |   |
          |   +-- Content (Text, ByteString, Html, etc.)
          |
          +------ Headedness (Headed or Headless)

Internally, a Colonnade is represented as a Vector of individual column encodings. It is possible to use any collection type with Alternative and Foldable instances. However, Vector was chosen to optimize the data structure for the use case of building the structure once and then folding over it many times. It is recommended that Colonnades are defined at the top-level so that GHC avoids reconstructing them every time they are used.

Constructors

Colonnade

Fields

• getColonnade :: Vector (OneColonnade h a c)

Instances

Functor h => Profunctor (Colonnade h)

Defined in Colonnade.Encode

Methods

dimap :: (a -> b) -> (c -> d) -> Colonnade h b c -> Colonnade h a d

lmap :: (a -> b) -> Colonnade h b c -> Colonnade h a c

rmap :: (b -> c) -> Colonnade h a b -> Colonnade h a c

(#.) :: Coercible c b => q b c -> Colonnade h a b -> Colonnade h a c

(.#) :: Coercible b a => Colonnade h b c -> q a b -> Colonnade h a c

Functor h => Functor (Colonnade h a)

Defined in Colonnade.Encode

Methods

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

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

Semigroup (Colonnade h a c)

Defined in Colonnade.Encode

Methods

(<>) :: Colonnade h a c -> Colonnade h a c -> Colonnade h a c

sconcat :: NonEmpty (Colonnade h a c) -> Colonnade h a c

stimes :: Integral b => b -> Colonnade h a c -> Colonnade h a c

Monoid (Colonnade h a c)

Defined in Colonnade.Encode

Methods

mempty :: Colonnade h a c

mappend :: Colonnade h a c -> Colonnade h a c -> Colonnade h a c

mconcat :: [Colonnade h a c] -> Colonnade h a c

data OneColonnade h a c

Encodes a header and a cell.

Constructors

OneColonnade

Fields

• oneColonnadeHead :: !(h c)
• oneColonnadeEncode :: !(a -> c)

Instances

Functor h => Profunctor (OneColonnade h)

Defined in Colonnade.Encode

Methods

dimap :: (a -> b) -> (c -> d) -> OneColonnade h b c -> OneColonnade h a d

lmap :: (a -> b) -> OneColonnade h b c -> OneColonnade h a c

rmap :: (b -> c) -> OneColonnade h a b -> OneColonnade h a c

(#.) :: Coercible c b => q b c -> OneColonnade h a b -> OneColonnade h a c

(.#) :: Coercible b a => OneColonnade h b c -> q a b -> OneColonnade h a c

Functor h => Functor (OneColonnade h a)

Defined in Colonnade.Encode

Methods

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

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

newtype Headed a

As the first argument to the Colonnade type constructor, this indictates that the columnar encoding has a header. This type is isomorphic to Identity but is given a new name to clarify its intent:

example :: Colonnade Headed Foo Text

The term example represents a columnar encoding of Foo in which the columns have headings.

Constructors

Headed

Fields

• getHeaded :: a

Instances

Functor Headed

Defined in Colonnade.Encode

Methods

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

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

Applicative Headed

Defined in Colonnade.Encode

Methods

pure :: a -> Headed a

(<*>) :: Headed (a -> b) -> Headed a -> Headed b

liftA2 :: (a -> b -> c) -> Headed a -> Headed b -> Headed c

(*>) :: Headed a -> Headed b -> Headed b

(<*) :: Headed a -> Headed b -> Headed a

Foldable Headed

Defined in Colonnade.Encode

Methods

fold :: Monoid m => Headed m -> m

foldMap :: Monoid m => (a -> m) -> Headed a -> m

foldr :: (a -> b -> b) -> b -> Headed a -> b

foldr' :: (a -> b -> b) -> b -> Headed a -> b

foldl :: (b -> a -> b) -> b -> Headed a -> b

foldl' :: (b -> a -> b) -> b -> Headed a -> b

foldr1 :: (a -> a -> a) -> Headed a -> a

foldl1 :: (a -> a -> a) -> Headed a -> a

toList :: Headed a -> [a]

null :: Headed a -> Bool

length :: Headed a -> Int

elem :: Eq a => a -> Headed a -> Bool

maximum :: Ord a => Headed a -> a

minimum :: Ord a => Headed a -> a

sum :: Num a => Headed a -> a

product :: Num a => Headed a -> a

Headedness Headed

Defined in Colonnade.Encode

Methods

headednessPure :: a -> Headed a

headednessExtract :: Maybe (Headed a -> a)

headednessExtractForall :: Maybe (ExtractForall Headed)

Eq a => Eq (Headed a)

Defined in Colonnade.Encode

Methods

(==) :: Headed a -> Headed a -> Bool

(/=) :: Headed a -> Headed a -> Bool

Ord a => Ord (Headed a)

Defined in Colonnade.Encode

Methods

compare :: Headed a -> Headed a -> Ordering

(<) :: Headed a -> Headed a -> Bool

(<=) :: Headed a -> Headed a -> Bool

(>) :: Headed a -> Headed a -> Bool

(>=) :: Headed a -> Headed a -> Bool

max :: Headed a -> Headed a -> Headed a

min :: Headed a -> Headed a -> Headed a

Read a => Read (Headed a)

Defined in Colonnade.Encode

Methods

readsPrec :: Int -> ReadS (Headed a)

readList :: ReadS [Headed a]

readPrec :: ReadPrec (Headed a)

readListPrec :: ReadPrec [Headed a]

Show a => Show (Headed a)

Defined in Colonnade.Encode

Methods

showsPrec :: Int -> Headed a -> ShowS

show :: Headed a -> String

showList :: [Headed a] -> ShowS

data Headless a

As the first argument to the Colonnade type constructor, this indictates that the columnar encoding does not have a header. This type is isomorphic to Proxy but is given a new name to clarify its intent:

example :: Colonnade Headless Foo Text

The term example represents a columnar encoding of Foo in which the columns do not have headings.

Constructors

Headless

Instances

Functor Headless

Defined in Colonnade.Encode

Methods

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

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

Applicative Headless

Defined in Colonnade.Encode

Methods

pure :: a -> Headless a

(<*>) :: Headless (a -> b) -> Headless a -> Headless b

liftA2 :: (a -> b -> c) -> Headless a -> Headless b -> Headless c

(*>) :: Headless a -> Headless b -> Headless b

(<*) :: Headless a -> Headless b -> Headless a

Foldable Headless

Defined in Colonnade.Encode

Methods

fold :: Monoid m => Headless m -> m

foldMap :: Monoid m => (a -> m) -> Headless a -> m

foldr :: (a -> b -> b) -> b -> Headless a -> b

foldr' :: (a -> b -> b) -> b -> Headless a -> b

foldl :: (b -> a -> b) -> b -> Headless a -> b

foldl' :: (b -> a -> b) -> b -> Headless a -> b

foldr1 :: (a -> a -> a) -> Headless a -> a

foldl1 :: (a -> a -> a) -> Headless a -> a

toList :: Headless a -> [a]

null :: Headless a -> Bool

length :: Headless a -> Int

elem :: Eq a => a -> Headless a -> Bool

maximum :: Ord a => Headless a -> a

minimum :: Ord a => Headless a -> a

sum :: Num a => Headless a -> a

product :: Num a => Headless a -> a

Contravariant Headless

Defined in Colonnade.Encode

Methods

contramap :: (a -> b) -> Headless b -> Headless a

(>$) :: b -> Headless b -> Headless a

Headedness Headless

Defined in Colonnade.Encode

Methods

headednessPure :: a -> Headless a

headednessExtract :: Maybe (Headless a -> a)

headednessExtractForall :: Maybe (ExtractForall Headless)

Eq (Headless a)

Defined in Colonnade.Encode

Methods

(==) :: Headless a -> Headless a -> Bool

(/=) :: Headless a -> Headless a -> Bool

Ord (Headless a)

Defined in Colonnade.Encode

Methods

compare :: Headless a -> Headless a -> Ordering

(<) :: Headless a -> Headless a -> Bool

(<=) :: Headless a -> Headless a -> Bool

(>) :: Headless a -> Headless a -> Bool

(>=) :: Headless a -> Headless a -> Bool

max :: Headless a -> Headless a -> Headless a

min :: Headless a -> Headless a -> Headless a

Read (Headless a)

Defined in Colonnade.Encode

Methods

readsPrec :: Int -> ReadS (Headless a)

readList :: ReadS [Headless a]

readPrec :: ReadPrec (Headless a)

readListPrec :: ReadPrec [Headless a]

Show (Headless a)

Defined in Colonnade.Encode

Methods

showsPrec :: Int -> Headless a -> ShowS

show :: Headless a -> String

showList :: [Headless a] -> ShowS

data Sized sz f a

Constructors

Sized

Fields

• sizedSize :: !sz
• sizedContent :: !(f a)

Instances

Functor f => Functor (Sized sz f)

Defined in Colonnade.Encode

Methods

fmap :: (a -> b) -> Sized sz f a -> Sized sz f b

(<$) :: a -> Sized sz f b -> Sized sz f a

Foldable f => Foldable (Sized sz f)

Defined in Colonnade.Encode

Methods

fold :: Monoid m => Sized sz f m -> m

foldMap :: Monoid m => (a -> m) -> Sized sz f a -> m

foldr :: (a -> b -> b) -> b -> Sized sz f a -> b

foldr' :: (a -> b -> b) -> b -> Sized sz f a -> b

foldl :: (b -> a -> b) -> b -> Sized sz f a -> b

foldl' :: (b -> a -> b) -> b -> Sized sz f a -> b

foldr1 :: (a -> a -> a) -> Sized sz f a -> a

foldl1 :: (a -> a -> a) -> Sized sz f a -> a

toList :: Sized sz f a -> [a]

null :: Sized sz f a -> Bool

length :: Sized sz f a -> Int

elem :: Eq a => a -> Sized sz f a -> Bool

maximum :: Ord a => Sized sz f a -> a

minimum :: Ord a => Sized sz f a -> a

sum :: Num a => Sized sz f a -> a

product :: Num a => Sized sz f a -> a

newtype ExtractForall h

Constructors

ExtractForall

Fields

• runExtractForall :: forall a. h a -> a

Typeclasses

class Headedness h where

This class communicates that a container holds either zero elements or one element. Furthermore, all inhabitants of the type must hold the same number of elements. Both Headed and Headless have instances. The following law accompanies any instances:

maybe x (\f -> f (headednessPure x)) headednessContents == x
todo: come up with another law that relates to Traversable

Consequently, there is no instance for Maybe, which cannot satisfy the laws since it has inhabitants which hold different numbers of elements. Nothing holds 0 elements and Just holds 1 element.

Methods

headednessPure :: a -> h a

headednessExtract :: Maybe (h a -> a)

headednessExtractForall :: Maybe (ExtractForall h)

Instances

Headedness Headless

Defined in Colonnade.Encode

Methods

headednessPure :: a -> Headless a

headednessExtract :: Maybe (Headless a -> a)

headednessExtractForall :: Maybe (ExtractForall Headless)

Headedness Headed

Defined in Colonnade.Encode

Methods

headednessPure :: a -> Headed a

headednessExtract :: Maybe (Headed a -> a)

headednessExtractForall :: Maybe (ExtractForall Headed)

Row

row :: (c1 -> c2) -> Colonnade f a c1 -> a -> Vector c2

Consider providing a variant the produces a list instead. It may allow more things to get inlined in to a loop.

rowMonadic :: (Monad m, Monoid b) => Colonnade f a c -> (c -> m b) -> a -> m b

rowMonadic_ :: Monad m => Colonnade f a c -> (c -> m b) -> a -> m ()

rowMonadicWith :: Monad m => b -> (b -> b -> b) -> Colonnade f a c -> (c -> m b) -> a -> m b

rowMonoidal :: Monoid m => Colonnade h a c -> (c -> m) -> a -> m

rowMonoidalHeader :: Monoid m => Colonnade h a c -> (h c -> c -> m) -> a -> m

Header

header :: (c1 -> c2) -> Colonnade Headed a c1 -> Vector c2

headerMonadic :: (Monad m, Monoid b) => Colonnade Headed a c -> (c -> m b) -> m b

headerMonadic_ :: Monad m => Colonnade Headed a c -> (c -> m b) -> m ()

headerMonadicGeneral :: (Monad m, Monoid b, Foldable h) => Colonnade h a c -> (c -> m b) -> m b

This function is a helper for abusing Foldable to optionally render a header. Its future is uncertain.

headerMonadicGeneral_ :: (Monad m, Headedness h) => Colonnade h a c -> (c -> m b) -> m ()

headerMonoidalGeneral :: (Monoid m, Foldable h) => Colonnade h a c -> (c -> m) -> m

headerMonoidalFull :: Monoid m => Colonnade h a c -> (h c -> m) -> m

Other

bothMonadic_ :: Monad m => Colonnade Headed a c -> (c -> c -> m b) -> a -> m ()

sizeColumns

Arguments

:: (Foldable f, Foldable h)

=> (c -> Int)

Get size from content

-> f a

-> Colonnade h a c

-> Colonnade (Sized (Maybe Int) h) a c

Cornice

Types

data Cornice h (p :: Pillar) a c where

Constructors

CorniceBase :: !(Colonnade h a c) -> Cornice h Base a c

CorniceCap :: !(Vector (OneCornice (Cornice h) p a c)) -> Cornice h (Cap p) a c

Instances

Functor h => Profunctor (Cornice h p)

Defined in Colonnade.Encode

Methods

dimap :: (a -> b) -> (c -> d) -> Cornice h p b c -> Cornice h p a d

lmap :: (a -> b) -> Cornice h p b c -> Cornice h p a c

rmap :: (b -> c) -> Cornice h p a b -> Cornice h p a c

(#.) :: Coercible c b => q b c -> Cornice h p a b -> Cornice h p a c

(.#) :: Coercible b a => Cornice h p b c -> q a b -> Cornice h p a c

Functor h => Functor (Cornice h p a)

Defined in Colonnade.Encode

Methods

fmap :: (a0 -> b) -> Cornice h p a a0 -> Cornice h p a b

(<$) :: a0 -> Cornice h p a b -> Cornice h p a a0

Semigroup (Cornice h p a c)

Defined in Colonnade.Encode

Methods

(<>) :: Cornice h p a c -> Cornice h p a c -> Cornice h p a c

sconcat :: NonEmpty (Cornice h p a c) -> Cornice h p a c

stimes :: Integral b => b -> Cornice h p a c -> Cornice h p a c

ToEmptyCornice p => Monoid (Cornice h p a c)

Defined in Colonnade.Encode

Methods

mempty :: Cornice h p a c

mappend :: Cornice h p a c -> Cornice h p a c -> Cornice h p a c

mconcat :: [Cornice h p a c] -> Cornice h p a c

data AnnotatedCornice sz h (p :: Pillar) a c where

Constructors

AnnotatedCorniceBase :: !sz -> !(Colonnade (Sized sz h) a c) -> AnnotatedCornice sz h Base a c

AnnotatedCorniceCap :: !sz -> !(Vector (OneCornice (AnnotatedCornice sz h) p a c)) -> AnnotatedCornice sz h (Cap p) a c

data OneCornice k (p :: Pillar) a c

Constructors

OneCornice

Fields

• oneCorniceHead :: !c
• oneCorniceBody :: !(k p a c)

Instances

Functor (k p a) => Functor (OneCornice k p a)

Defined in Colonnade.Encode

Methods

fmap :: (a0 -> b) -> OneCornice k p a a0 -> OneCornice k p a b

(<$) :: a0 -> OneCornice k p a b -> OneCornice k p a a0

data Pillar

Isomorphic to the natural numbers. Only the promoted version of this type is used.

Constructors

Cap !Pillar

Base

class ToEmptyCornice (p :: Pillar) where

Methods

toEmptyCornice :: Cornice h p a c

Instances

ToEmptyCornice Base

Defined in Colonnade.Encode

Methods

toEmptyCornice :: Cornice h Base a c

ToEmptyCornice (Cap p)

Defined in Colonnade.Encode

Methods

toEmptyCornice :: Cornice h (Cap p) a c

data Fascia (p :: Pillar) r where

Constructors

FasciaBase :: !r -> Fascia Base r

FasciaCap :: !r -> Fascia p r -> Fascia (Cap p) r

Encoding

annotate :: Cornice Headed p a c -> AnnotatedCornice (Maybe Int) Headed p a c

annotateFinely

Arguments

:: Foldable f

=> (Int -> Int -> Int)

fold function

-> (Int -> Int)

finalize

-> (c -> Int)

Get size from content

-> f a

-> Cornice Headed p a c

-> AnnotatedCornice (Maybe Int) Headed p a c

size :: AnnotatedCornice sz h p a c -> sz

This is an O(1) operation, sort of

endow :: forall p a c. (c -> c -> c) -> Cornice Headed p a c -> Colonnade Headed a c

discard :: Cornice h p a c -> Colonnade h a c

headersMonoidal

Arguments

:: (Monoid m, Headedness h)

=> Maybe (Fascia p r, r -> m -> m)

Apply the Fascia header row content

-> [(sz -> c -> m, m -> m)]

Build content from cell content and size

-> AnnotatedCornice sz h p a c

-> m

uncapAnnotated :: forall sz p a c h. AnnotatedCornice sz h p a c -> Colonnade (Sized sz h) a c