-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A tool for posting Haskelly articles to blogs
--   
--   Write blog posts in Markdown format, then use BlogLiterately to do
--   syntax highlighting, format ghci sessions, and upload to any blog
--   supporting the metaWeblog API (such as Wordpress).
--   
--   To get started, use the provided executable <tt>BlogLiterately</tt>;
--   see <a>http://byorgey.wordpress.com/blogliterately/</a> for complete
--   documentation.
--   
--   To make further customization possible, the internals of the
--   executable are made available as a library. In particular, it is easy
--   to create your own executable which adds extra custom transformations;
--   see <a>Text.BlogLiterately.Run</a>.
--   
--   Note that BlogLiterately depends on blaze-html-0.5. Pandoc 1.9.3 and
--   later can depend on either blaze-html-0.4 or blaze-html-0.5, but the
--   latter only in case the blaze_html_0_5 flag is set. If pandoc is
--   installed as a dependency of BlogLiterately, everything should work
--   out fine, since cabal's constraint solver will figure out to set that
--   flag. But if pandoc is already installed against blaze-html-0.4 you
--   may need to reinstall it with the blaze_html_0_5 flag explicitly set.
@package BlogLiterately
@version 0.5.1


-- | Utilities for working with embedded LaTeX.
module Text.BlogLiterately.LaTeX

-- | WordPress can render LaTeX, but expects it in a special non-standard
--   format (<tt>$latex foo$</tt>). The <tt>wpTeXify</tt> function formats
--   LaTeX code using this format so that it can be processed by WordPress.
wpTeXify :: Pandoc -> Pandoc


-- | Utilities for working with code blocks.
module Text.BlogLiterately.Block

-- | Given a block, if begins with a tag in square brackets, strip off the
--   tag and return a pair consisting of the tag and de-tagged block.
--   Otherwise, return <tt>Nothing</tt> and the unchanged block.
unTag :: String -> (Maybe String, String)


-- | Format specially marked blocks as interactive ghci sessions. Uses some
--   ugly but effective code for interacting with an external ghci process
--   taken from lhs2TeX.
module Text.BlogLiterately.Ghci

-- | Information about a running process: stdin, stdout, stderr, and a
--   handle.
type ProcessInfo = (Handle, Handle, Handle, ProcessHandle)

-- | Evaluate an expression using an external <tt>ghci</tt> process.
ghciEval :: GhciInput -> ReaderT ProcessInfo IO GhciOutput

-- | Start an external ghci process, run a computation with access to it,
--   and finally stop the process.
withGhciProcess :: FilePath -> ReaderT ProcessInfo IO a -> IO a

-- | Poor man's check to see whether we have a literate Haskell file.
isLiterate :: FilePath -> IO Bool

-- | Stop a ghci process by passing it <tt>:q</tt> and waiting for it to
--   exit.
stopGhci :: ProcessInfo -> IO ()

-- | There is nothing magic about the magic string.
magic :: String
extract' :: Handle -> IO String
extract :: String -> String
breaks :: ([a] -> Bool) -> [a] -> ([a], [a])

-- | Given the path to the <tt>.lhs</tt> source and its representation as a
--   <tt>Pandoc</tt> document, <tt>formatInlineGhci</tt> finds any
--   <tt>[ghci]</tt> blocks in it, runs them through <tt>ghci</tt>, and
--   formats the results as an interactive <tt>ghci</tt> session.
--   
--   Lines beginning in the first column of the block are interpreted as
--   inputs. Lines indented by one or more space are interpreted as
--   <i>expected outputs</i>. Consecutive indented lines are interpreted as
--   one multi-line expected output, with a number of spaces removed from
--   the beginning of each line equal to the number of spaces at the start
--   of the first indented line.
--   
--   If the output for a given input is the same as the expected output (or
--   if no expected output is given), the result is typeset normally. If
--   the actual and expected outputs differ, the actual output is typeset
--   first in red, then the expected output in blue.
formatInlineGhci :: FilePath -> Pandoc -> IO Pandoc
instance Show GhciInput
instance Show GhciOutput
instance Show GhciLine


-- | Syntax highlighting.
module Text.BlogLiterately.Highlight

-- | Four modes for highlighting Haskell.
data HsHighlight

-- | Use hscolour and inline the styles.
HsColourInline :: StylePrefs -> HsHighlight

-- | Use hscolour in conjunction with an external CSS style sheet.
HsColourCSS :: HsHighlight

-- | Use highlighting-kate.
HsKate :: HsHighlight

-- | Do not highlight Haskell.
HsNoHighlight :: HsHighlight

-- | Use hscolour to syntax highlight some Haskell code. The first argument
--   indicates whether the code is literate Haskell.
colourIt :: Bool -> String -> String

-- | Prepend literate Haskell markers to some source code.
litify :: String -> String

-- | Style preferences are specified as a list of mappings from class
--   attributes to CSS style attributes.
type StylePrefs = [(String, String)]

-- | A default style that produces something that looks like the source
--   listings on Hackage.
defaultStylePrefs :: StylePrefs

-- | Read style preferences in from a file using the <tt>Read</tt> instance
--   for <tt>StylePrefs</tt>, or return the default style if the file name
--   is empty.
getStylePrefs :: FilePath -> IO StylePrefs

-- | Take a <tt>String</tt> of HTML produced by hscolour, and "bake" styles
--   into it by replacing class attributes with appropriate style
--   attributes.
bakeStyles :: StylePrefs -> String -> String

-- | Replace <tt>&lt;br/&gt;</tt> tags with newlines.
replaceBreaks :: String -> String

-- | Transform a <tt>CodeBlock</tt> into a <tt>RawHtml</tt> block, where
--   the content contains marked up Haskell (possibly with literate
--   markers), or marked up non-Haskell, if highlighting of non-Haskell has
--   been selected.
colouriseCodeBlock :: HsHighlight -> Bool -> Block -> Block

-- | Perform syntax highlighting on an entire Pandoc document.
colourisePandoc :: HsHighlight -> Bool -> Pandoc -> Pandoc
instance Typeable HsHighlight
instance Data HsHighlight
instance Show HsHighlight
instance Eq HsHighlight


-- | Configuation and command-line options.
module Text.BlogLiterately.Options

-- | Configuration record (and command-line options) for
--   <tt>BlogLiterately</tt>.
data BlogLiterately
BlogLiterately :: String -> HsHighlight -> Bool -> Bool -> Bool -> Bool -> [String] -> [String] -> String -> Maybe String -> String -> Maybe String -> String -> String -> Maybe String -> Bool -> Bool -> [String] -> BlogLiterately

-- | Name of a style file
style :: BlogLiterately -> String

-- | Haskell highlighting mode
hsHighlight :: BlogLiterately -> HsHighlight

-- | Use highlighting-kate for non-Haskell?
otherHighlight :: BlogLiterately -> Bool

-- | Format LaTeX for WordPress?
wplatex :: BlogLiterately -> Bool

-- | Automatically process ghci sessions?
ghci :: BlogLiterately -> Bool

-- | Automatically upload images?
uploadImages :: BlogLiterately -> Bool

-- | Categories for the post
categories :: BlogLiterately -> [String]

-- | Tags for the post
tags :: BlogLiterately -> [String]

-- | Blog-specific identifier (e.g. for blogging software handling multiple
--   blogs)
blogid :: BlogLiterately -> String

-- | Blog xmlrpc URL
blog :: BlogLiterately -> Maybe String

-- | Blog user name
user :: BlogLiterately -> String

-- | Blog password (omit to be interactively prompted)
password :: BlogLiterately -> Maybe String

-- | Post title
title :: BlogLiterately -> String

-- | File to post
file :: BlogLiterately -> String

-- | ID of a post to update
postid :: BlogLiterately -> Maybe String

-- | Create a "page" instead of a post
page :: BlogLiterately -> Bool

-- | Should the post be published? (Otherwise it is uploaded as a draft.)
publish :: BlogLiterately -> Bool

-- | Extension arguments, for use e.g. by custom transforms
xtra :: BlogLiterately -> [String]

-- | Command-line configuration for use with <tt>cmdargs</tt>.
blOpts :: BlogLiterately
instance Typeable BlogLiterately
instance Show BlogLiterately
instance Data BlogLiterately


-- | Uploading images embedded in posts to the server.
module Text.BlogLiterately.Image

-- | Transform a document by uploading any "local" images to the server,
--   and replacing their filenames with the URLs returned by the server.
uploadAllImages :: BlogLiterately -> (Pandoc -> IO Pandoc)

-- | Upload a file using the <tt>metaWeblog.newMediaObject</tt> XML-RPC
--   method call.
uploadIt :: String -> FilePath -> BlogLiterately -> IO (Maybe Value)

-- | Prepare a file for upload.
mkMediaObject :: FilePath -> IO (Maybe Value)


-- | Uploading posts to the server.
module Text.BlogLiterately.Post

-- | Prepare a post for uploading by creating something of the proper form
--   to be an argument to an XML-RPC call.
mkPost :: String -> String -> [String] -> [String] -> Bool -> [(String, Value)]

-- | Given a name and a list of values, create a named "array" field
--   suitable for inclusion in an XML-RPC struct.
mkArray :: XmlRpcType [a] => String -> [a] -> [(String, Value)]

-- | Given a configuration and a formatted post, upload it to the server.
postIt :: BlogLiterately -> String -> IO ()


-- | Tools for putting together a pipeline transforming the source for a
--   post into a completely formatted HTML document.
module Text.BlogLiterately.Transform

-- | A document transformation consists of two parts: an actual
--   transformation, expressed as a function over Pandoc documents, and a
--   condition specifying whether the transformation should actually be
--   applied.
--   
--   The transformation itself takes a <a>BlogLiterately</a> configuration
--   as an argument. You may of course ignore it if you do not need to know
--   anything about the configuration. The <tt>--xtra</tt> (or <tt>-x</tt>)
--   flag is also provided especially as a method of getting information
--   from the command-line to custom extensions. Arguments passed via
--   <tt>-x</tt> on the command line are available from the <a>xtra</a>
--   field of the <a>BlogLiterately</a> configuration.
--   
--   The transformation is then specified as a <tt><a>Kleisli</a> IO
--   <a>Pandoc</a> <a>Pandoc</a></tt> arrow, which is isomorphic to
--   <tt>Pandoc -&gt; IO Pandoc</tt>. If you have a pure function of type
--   <tt>Pandoc -&gt; Pandoc</tt>, wrap it in a call to <a>arr</a> to
--   produce a <a>Kleisli</a> arrow. If you have a function <tt>Pandoc
--   -&gt; IO Pandoc</tt>, wrap it in the <a>Kleisli</a> constructor.
--   
--   For examples, see the implementations of the standard transforms
--   below.
data Transform
Transform :: (BlogLiterately -> Kleisli IO Pandoc Pandoc) -> (BlogLiterately -> Bool) -> Transform

-- | A document transformation, which can depend on BlogLiterately options
--   and can have effects in the <tt>IO</tt> monad.
getTransform :: Transform -> BlogLiterately -> Kleisli IO Pandoc Pandoc

-- | A condition under which to run the transformation.
xfCond :: Transform -> BlogLiterately -> Bool

-- | Run a <a>Transform</a> (if its condition is met).
runTransform :: Transform -> BlogLiterately -> Kleisli IO Pandoc Pandoc

-- | Run a pipeline of <a>Transform</a>s.
runTransforms :: [Transform] -> BlogLiterately -> Kleisli IO Pandoc Pandoc

-- | Format embedded LaTeX for WordPress (if the <tt>wplatex</tt> flag is
--   set).
wptexifyXF :: Transform

-- | Format embedded <tt>ghci</tt> sessions (if the <tt>ghci</tt> flag is
--   set).
ghciXF :: Transform

-- | Upload embedded local images to the server (if the
--   <tt>uploadImages</tt> flag is set).
imagesXF :: Transform

-- | Perform syntax highlighting on code blocks.
highlightXF :: Transform

-- | The standard set of transforms that are run by default:
--   <a>wptexifyXF</a>, <a>ghciXF</a>, <a>imagesXF</a>, <a>highlightXF</a>.
standardTransforms :: [Transform]

-- | Center any images which occur in a paragraph by themselves. Inline
--   images are not affected.
centerImagesXF :: Transform

-- | Transform a complete input document string to an HTML output string,
--   given a list of transformation passes.
xformDoc :: BlogLiterately -> [Transform] -> (String -> IO String)

-- | A useful arrow utility for running some part of a pipeline
--   conditionally.
whenA :: Category ~> => (a ~> a) -> Bool -> (a ~> a)

-- | Turn <tt>CRLF</tt> pairs into a single <tt>LF</tt>. This is necessary
--   since <a>readMarkdown</a> is picky about line endings.
fixLineEndings :: String -> String


-- | Functions for creating <tt>BlogLiterately</tt> executables. By
--   default, installing this library results in the installation of a
--   standard executable, called <tt>BlogLiterately</tt>, which corresponds
--   to <a>blogLiterately</a> from this module. However, you can create
--   your own custom executables with extra custom functionality using
--   <a>blogLiteratelyWith</a> or <a>blogLiteratelyCustom</a>. For example:
--   
--   <pre>
--   module Main where
--   import Text.BlogLiterately
--   
--   myCustomXF = Transform ...
--   main = blogLiteratelyWith [myCustomXF, centerImagesXF]
--   </pre>
--   
--   See <a>Text.BlogLiterately.Transform</a> for examples of transforms,
--   additional transforms which are not enabled by default, and help in
--   creating your own.
module Text.BlogLiterately.Run

-- | The default BlogLiterately application.
blogLiterately :: IO ()

-- | Like <a>blogLiterately</a>, but with the ability to specify additional
--   <a>Transform</a>s which will be applied <i>after</i> the standard
--   ones.
blogLiteratelyWith :: [Transform] -> IO ()

-- | Like <a>blogLiterately</a>, but with the ability to <i>replace</i> the
--   standard <a>Transform</a>s. Use this to implement custom interleaving
--   orders of the standard transforms and your own, to exclude some or all
--   of the standard transforms, etc.
blogLiteratelyCustom :: [Transform] -> IO ()


-- | This module is provided as a convenient wrapper which re-exports all
--   the other <tt>Text.BlogLiterately.*</tt> modules.
module Text.BlogLiterately