Frames.TH

Code generation of types relevant to Frames use-cases. Generation may be driven by an automated inference process or manual use of the individual helpers.

Documentation

recDec :: [Type] -> Type

Generate a column type.

mkColSynDec :: TypeQ -> Name -> DecQ

Declare a type synonym for a column.

mkColLensDec :: Name -> Type -> Text -> DecsQ

Declare lenses for working with a column.

lowerHead :: Text -> Maybe Text

colDec :: Text -> String -> Text -> Either (String -> Q [Dec]) Type -> Q (Type, [Dec])

For each column, we declare a type synonym for its type, and a Proxy value of that type.

declareColumn :: Text -> Name -> DecsQ

Splice for manually declaring a column of a given type. For example, declareColumn "x2" ''Double will declare a type synonym type X2 = "x2" :-> Double and a lens x2.

declarePrefixedColumn :: Text -> Text -> Name -> DecsQ

Splice for manually declaring a column of a given type in which the generated type synonym's name has a prefix applied to the column name. For example, declarePrefixedColumn "x2" "my" ''Double will declare a type synonym type MyX2 = "x2" :-> Double and a lens myX2.

Default CSV Parsing

data RowGen (a :: [Type])

Control how row and named column types are generated. The type argument is a type-level list of the possible column types.

Constructors

RowGen

Fields

• columnNames :: [String]

  Use these column names. If empty, expect a header row in the data file to provide column names.

• tablePrefix :: String

  A common prefix to use for every generated declaration.

• separator :: Separator

  The string that separates the columns on a row.

• rowTypeName :: String

  The row type that enumerates all columns.

• columnUniverse :: Proxy a

  A record field that mentions the phantom type list of possible column types. Having this field prevents record update syntax from losing track of the type argument.

• inferencePrefix :: Int

  Number of rows to inspect to infer a type for each column. Defaults to 1000.

• lineReader :: Separator -> Producer [Text] (SafeT IO) ()

  A producer of rows of ’T.Text’ values that were separated by a Separator value.

colQ :: Name -> Q Exp

rowGen :: FilePath -> RowGen CommonColumns

A default RowGen. This instructs the type inference engine to get column names from the data file, use the default column separator (a comma), infer column types from the default Columns set of types, and produce a row type with name Row.

rowGenCat :: FilePath -> RowGen CommonColumnsCat

Like rowGen, but will also generate custom data types for Categorical variables with up to 8 distinct variants.

tableTypes :: String -> FilePath -> DecsQ

Generate types for a row of a table. This will be something like Record ["x" :-> a, "y" :-> b, "z" :-> c]. This splice additionally generates a type synonym for each column, and a proxy value of that type. If the CSV file has column names "foo", "bar", and "baz", then this will declare type Foo = "foo" :-> Int, for example, foo = rlens @Foo, and foo' = rlens' @Foo.

See tableTypes' if you need to customize parsing to do things like override the separator character (default is a single comma), or supply column names.

Customized Data Set Parsing

prefixSize :: Int

Inspect no more than this many lines when inferring column types.

colNamesP :: Monad m => Producer [Text] m () -> m [Text]

Generate a type for a row of a table. This will be something like Record ["x" :-> a, "y" :-> b, "z" :-> c]. Column type synonyms are not generated (see tableTypes'). tableType' :: forall a. (ColumnTypeable a, Monoid a) => RowGen a -> DecsQ tableType' (RowGen {..}) = pure . TySynD (mkName rowTypeName) [] $ (runIO (P.runSafeT (readColHeaders opts lineSource)) >>= recDec') where recDec' = recDec . map (second colType) :: [(T.Text, a)] -> Q Type colNames' | null columnNames = Nothing | otherwise = Just (map T.pack columnNames) opts = ParserOptions colNames' separator (RFC4180Quoting '"') lineSource = lineReader separator >-> P.take prefixSize

Tokenize the first line of a ’P.Producer’.

tableTypesText' :: forall a c. (c ~ CoRec ColInfo a, ColumnTypeable c, Semigroup c) => RowGen a -> DecsQ

Generate a type for a row of a table all of whose columns remain unparsed Text values.

tableTypes' :: forall a c. (c ~ CoRec ColInfo a, ColumnTypeable c, Semigroup c, RPureConstrained (ShowF ColInfo) a) => RowGen a -> DecsQ

Generate a type for a row of a table. This will be something like Record ["x" :-> a, "y" :-> b, "z" :-> c]. Additionally generates a type synonym for each column, and a proxy value of that type. If the CSV file has column names "foo", "bar", and "baz", then this will declare type Foo = "foo" :-> Int, for example, foo = rlens @Foo, and foo' = rlens' @Foo.

The supplied RowGen value is also used to produce a value of type ParserOptions that can be passed to functions like readTableOpt. This is useful if you need to customize parsing to support something like a special separator string. This value of type ParserOptions will be given a name based on the row type name. If the row type is Row, then thsi splice will generate a value rowParser :: ParserOptions.