Text.Transf

Basic types

type Line = String

A single line of text.

type Lines = String

Multiple lines of text.

type RelativePath = FilePath

  A relative file path.

The Context type

type Context = ContextT IO

  The Context monad defines the context of a transformation.

The main purpose of this type is to restrict the the number of functions you can pass to transform.

data ContextT m a

Instances

Monad m => MonadError String (ContextT m)

Monad m => Monad (ContextT m)

Functor m => Functor (ContextT m)

Monad m => MonadPlus (ContextT m)

MonadIO m => MonadIO (ContextT m)

runContext :: Context a -> IO (Either String a)

Run a computation in the Context monad.

runContextT :: Monad m => ContextT m a -> m (Either String a)

Transformormations

data Transform

A transformation.

Instances

Monoid Transform

Semigroup Transform

transform :: String -> (Lines -> Context Lines) -> Transform

Create a new transformation.

This transformation processes everything in between lines containing a fence such as

 ~~~name
 ~~~

or

 ```name
 ```

where name is the name of the transformation.

To create a suitable change function, use the combinators defined below.

Running transformations

runTransform :: Transform -> String -> Context String

  Run a transformation in the Context monad.

Combinators

Input/output

readFile :: RelativePath -> Context String

Read a file.

writeFile :: RelativePath -> String -> Context ()

Write to a file.

inform :: String -> Context ()

Write to the standard error stream.

Evaluation

eval :: Typeable a => String -> Context a

Evaluate a Haskell expression.

evalWith :: Typeable a => [String] -> String -> Context a

Evaluate a Haskell expression with the given modules in scope. Note that Prelude is not implicitly imported.

All requested modules must be present on the system or the computation will fail. Also, the string must be a valid Haskell expression using constructs which in scope after loading the given modules.

Errors can be caught using catchError.

addPost :: Context () -> Context ()

Register an action to be run after text processing has finished. This can be used to optimize tasks such as external file generations.

Note that addPost does not work trasitively, i.e. post actions of post actions are thrown away.

Transformormations

printT :: Transform

This named transformation posts its input to the standard error stream and returns nothing.

evalT :: Transform

This named transformation evaluates its input as a Haskell expression of type String and returns the value of the expression.

For example the input

 ~~~haskell
 "The number is " ++ show $ 3 + 2
 ~~~

Will be transformed into

 The number is 6

musicT :: Transform

This named transformation evaluates its input as a music expression.

The music is rendered as an .ly file and a .mid fiel, then lilypond and convert is run to render a .png file. A markdown image tag and a HTML play and stop button is returned.

The expression must return a value of type Score Note. The Music.Prelude.Basic module is implicitly imported.

data MusicOpts

Constructors

MusicOpts

Fields

format :: String

resolution :: Int

resize :: Int

Instances

Default MusicOpts

musicT' :: MusicOpts -> Transform

haskellT :: Transform

This named transformation passes everything through and retains the source.

musicHaskellT :: Transform

This named transformation runs the music transformation and retains the source.

musicHaskellT' :: MusicOpts -> Transform

musicExtraT :: Transform

This named transformation includes stuff needed for music playback.

It should be used exactly once in the document.