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


-- | Conversion between formats used to represent mathematics.
--   
--   The texmath library provides functions to read and write TeX math,
--   presentation MathML, and OMML (Office Math Markup Language, used in
--   Microsoft Office). Support is also included for converting math
--   formats to pandoc's native format (allowing conversion, via pandoc, to
--   a variety of different markup formats). The TeX reader supports basic
--   LaTeX and AMS extensions, and it can parse and apply LaTeX macros.
--   (See <a>here</a> for a live demo of bidirectional conversion between
--   LaTeX and MathML.)
--   
--   The package also includes several utility modules which may be useful
--   for anyone looking to manipulate either TeX math or MathML. For
--   example, a copy of the MathML operator dictionary is included.
--   
--   Use the <tt>executable</tt> flag to install a standalone executable,
--   <tt>texmath</tt>, that by default reads a LaTeX formula from
--   <tt>stdin</tt> and writes MathML to <tt>stdout</tt>. With flags all
--   the functionality exposed by <a>Text.TeXMath</a> can be accessed
--   through this executable. (Use the <tt>--help</tt> flag for a
--   description of all functionality)
--   
--   The <tt>texmath</tt> executable can also be used as a CGI script, when
--   renamed as <tt>texmath-cgi</tt>. It will expect query parameters for
--   <tt>from</tt>, <tt>to</tt>, <tt>input</tt>, and optionally
--   <tt>inline</tt>, and return a JSON object with either <tt>error</tt>
--   and a message or <tt>success</tt> and the converted result.
@package texmath
@version 0.8.4.2


-- | This module exposes functions which attempt to approximate unicode
--   characters as ASCII.
--   
--   Information taken from the <a>Unidecode python package</a> which is
--   based upon the <a>Text::Unidecode Perl Module</a> by Sean M. Burke.
module Text.TeXMath.Unicode.ToASCII

-- | Approximates a single unicode character as an ASCII string (each
--   character is between 0x00 and 0x7F).
getASCII :: Char -> String


-- | HTML entity definitions as provided by W3C.
--   
--   The mapping matches the version from 10th April 2014.
--   
--   The original source can be downloaded from
--   <a>http://www.w3.org/TR/2014/REC-xml-entity-names-20140410/</a>.
--   
--   Note: I have made one alteration, switching epsilon and varepsilon,
--   because the meanings of these names in HTML is different from the
--   meanings in MathML+LaTeX. See
--   http:/<i>www.w3.org</i>2003<i>entities</i>2007doc/#epsilon.
module Text.TeXMath.Readers.MathML.EntityMap

-- | Translates MathML entity reference to the corresponding Unicode
--   string.
getUnicode :: String -> Maybe String


-- | Functions for parsing LaTeX macro definitions and applying macros to
--   LateX expressions.
module Text.TeXMath.Readers.TeX.Macros
data Macro

-- | Parses a string for a list of macro definitions, optionally separated
--   and ended by spaces and TeX comments. Returns the list of macros
--   (which may be empty) and the unparsed portion of the input string.
parseMacroDefinitions :: String -> ([Macro], String)

-- | Applies a list of macros to a string recursively until a fixed point
--   is reached. If there are several macros in the list with the same
--   name, earlier ones will shadow later ones.
applyMacros :: [Macro] -> String -> String
instance Show Macro


-- | Types for representing a structured formula.
module Text.TeXMath.Types
data Exp

-- | A number (<tt>&lt;mn&gt;</tt> in MathML).
ENumber :: String -> Exp

-- | A group of expressions that function as a unit (e.g. <tt>{...}</tt>)
--   in TeX, <tt>&lt;mrow&gt;...&lt;/mrow&gt;</tt> in MathML.
EGrouped :: [Exp] -> Exp

-- | A group of expressions inside paired open and close delimiters (which
--   may in some cases be null).
EDelimited :: String -> String -> [InEDelimited] -> Exp

-- | An identifier, e.g. a variable (<tt>&lt;mi&gt;...&lt;/mi&gt;</tt> in
--   MathML. Note that MathML tends to use <tt>&lt;mi&gt;</tt> tags for
--   "sin" and other mathematical operators; these are represented as
--   <a>EMathOperator</a> in TeXMath.
EIdentifier :: String -> Exp

-- | A spelled-out operator like <tt>lim</tt> or <tt>sin</tt>.
EMathOperator :: String -> Exp

-- | A symbol.
ESymbol :: TeXSymbolType -> String -> Exp

-- | A space, with the width specified in em.
ESpace :: Rational -> Exp

-- | An expression with a subscript. First argument is base, second
--   subscript.
ESub :: Exp -> Exp -> Exp

-- | An expresion with a superscript. First argument is base, second
--   subscript.
ESuper :: Exp -> Exp -> Exp

-- | An expression with both a sub and a superscript. First argument is
--   base, second subscript, third superscript.
ESubsup :: Exp -> Exp -> Exp -> Exp

-- | An expression with something over it. The first argument is True if
--   the formula is "convertible:" that is, if the material over the
--   formula should appear as a regular superscript in inline math. The
--   second argument is the base, the third the expression that goes over
--   it.
EOver :: Bool -> Exp -> Exp -> Exp

-- | An expression with something under it. The arguments work as in
--   <tt>EOver</tt>.
EUnder :: Bool -> Exp -> Exp -> Exp

-- | An expression with something over and something under it.
EUnderover :: Bool -> Exp -> Exp -> Exp -> Exp

-- | A "phantom" operator that takes space but doesn't display.
EPhantom :: Exp -> Exp

-- | A boxed expression.
EBoxed :: Exp -> Exp

-- | A fraction. First argument is numerator, second denominator.
EFraction :: FractionType -> Exp -> Exp -> Exp

-- | An nth root. First argument is index, second is base.
ERoot :: Exp -> Exp -> Exp

-- | A square root.
ESqrt :: Exp -> Exp

-- | An expression that is scaled to some factor of its normal size.
EScaled :: Rational -> Exp -> Exp

-- | An array or matrix. The first argument specifies the alignments of the
--   columns; the second gives the contents of the lines. All of these
--   lists should be the same length.
EArray :: [Alignment] -> [ArrayLine] -> Exp

-- | Some normal text, possibly styled.
EText :: TextType -> String -> Exp

-- | A group of styled expressions.
EStyled :: TextType -> [Exp] -> Exp
data TeXSymbolType
Ord :: TeXSymbolType
Op :: TeXSymbolType
Bin :: TeXSymbolType
Rel :: TeXSymbolType
Open :: TeXSymbolType
Close :: TeXSymbolType
Pun :: TeXSymbolType
Accent :: TeXSymbolType
Fence :: TeXSymbolType
TOver :: TeXSymbolType
TUnder :: TeXSymbolType
Alpha :: TeXSymbolType
BotAccent :: TeXSymbolType
Rad :: TeXSymbolType
type ArrayLine = [[Exp]]
data FractionType

-- | Displayed or textual, acc to <a>DisplayType</a>
NormalFrac :: FractionType

-- | Force display mode
DisplayFrac :: FractionType

-- | Force inline mode (textual)
InlineFrac :: FractionType

-- | No line between top and bottom
NoLineFrac :: FractionType
data TextType
TextNormal :: TextType
TextBold :: TextType
TextItalic :: TextType
TextMonospace :: TextType
TextSansSerif :: TextType
TextDoubleStruck :: TextType
TextScript :: TextType
TextFraktur :: TextType
TextBoldItalic :: TextType
TextSansSerifBold :: TextType
TextSansSerifBoldItalic :: TextType
TextBoldScript :: TextType
TextBoldFraktur :: TextType
TextSansSerifItalic :: TextType
data Alignment
AlignLeft :: Alignment
AlignCenter :: Alignment
AlignRight :: Alignment
AlignDefault :: Alignment
data DisplayType

-- | A displayed formula.
DisplayBlock :: DisplayType

-- | A formula rendered inline in text.
DisplayInline :: DisplayType

-- | A record of the MathML dictionary as defined <a>in the
--   specification</a>
data Operator
Operator :: String -> String -> FormType -> Int -> Int -> Int -> [Property] -> Operator

-- | Operator
oper :: Operator -> String

-- | Plain English Description
description :: Operator -> String

-- | Whether Prefix, Postfix or Infix
form :: Operator -> FormType

-- | Default priority for implicit nesting
priority :: Operator -> Int

-- | Default Left Spacing
lspace :: Operator -> Int

-- | Default Right Spacing
rspace :: Operator -> Int

-- | List of MathML properties
properties :: Operator -> [Property]
data FormType
FPrefix :: FormType
FPostfix :: FormType
FInfix :: FormType

-- | A record of the Unicode to LaTeX lookup table a full descripton can be
--   seen
--   &lt;<a>http://milde.users.sourceforge.net/LUCR/Math/data/unimathsymbols.txt</a>
--   here&gt;
data Record
Record :: Char -> [(String, String)] -> TeXSymbolType -> String -> Record

-- | Unicode Character
uchar :: Record -> Char

-- | LaTeX commands (package, command)
commands :: Record -> [(String, String)]

-- | TeX math category
category :: Record -> TeXSymbolType

-- | Plain english description
comments :: Record -> String
type Property = String
data Position
Under :: Position
Over :: Position

-- | List of available packages
type Env = [String]

-- | Contains <tt>amsmath</tt> and <tt>amssymbol</tt>
defaultEnv :: [String]

-- | An <tt>EDelimited</tt> element contains a string of ordinary
--   expressions (represented here as <tt>Right</tt> values) or fences
--   (represented here as <tt>Left</tt>, and in LaTeX using <tt>mid</tt>).
type InEDelimited = Either Middle Exp
instance Typeable TeXSymbolType
instance Typeable Alignment
instance Typeable FractionType
instance Typeable TextType
instance Typeable Exp
instance Show TeXSymbolType
instance Read TeXSymbolType
instance Eq TeXSymbolType
instance Data TeXSymbolType
instance Show Alignment
instance Read Alignment
instance Eq Alignment
instance Data Alignment
instance Show FractionType
instance Read FractionType
instance Eq FractionType
instance Data FractionType
instance Show DisplayType
instance Eq DisplayType
instance Show TextType
instance Ord TextType
instance Read TextType
instance Eq TextType
instance Data TextType
instance Show Exp
instance Read Exp
instance Eq Exp
instance Data Exp
instance Show FormType
instance Ord FormType
instance Eq FormType
instance Show Operator
instance Show Record


-- | Function for replacing strings of characters with their respective
--   mathvariant and vice versa.
module Text.TeXMath.Unicode.ToUnicode

-- | The inverse of <a>toUnicodeChar</a>: returns the corresponding
--   unstyled character and <a>TextType</a> of a unicode character.
fromUnicodeChar :: Char -> Maybe (TextType, Char)
toUnicodeChar :: (TextType, Char) -> Maybe Char

-- | Inverse of <a>toUnicode</a>.
fromUnicode :: TextType -> String -> String

-- | Replace characters with their corresponding mathvariant unicode
--   character. MathML has a mathvariant attribute which is unimplemented
--   in Firefox (see <a>here</a>) Therefore, we may want to translate
--   mathscr, etc to unicode symbols directly.
toUnicode :: TextType -> String -> String


-- | This module is derived from the list of unicode to LaTeX mappings
--   compiled by Günter Milde.
--   
--   An unmodified original copy of this work can be obtained from
--   <a>here</a>
module Text.TeXMath.Unicode.ToTeX

-- | Converts a string of unicode characters into a strong of equivalent
--   TeXMath commands. An environment is a list of strings specifying which
--   additional packages are available.
getTeXMath :: String -> Env -> [TeX]

-- | Returns TeX symbol type corresponding to a unicode character.
getSymbolType :: Char -> TeXSymbolType
records :: [Record]


-- | Dictionary of operators to MathML attributes as specified by the W3C
--   standard.
--   
--   The original file can be downloaded from <a>here</a>
module Text.TeXMath.Readers.MathML.MMLDict

-- | Tries to find the <a>Operator</a> record based on a given position. If
--   there is no exact match then the positions will be tried in the
--   following order (Infix, Postfix, Prefix) with the first match (if any)
--   being returned.
getMathMLOperator :: String -> FormType -> Maybe Operator

-- | A table of all operators as defined by the MathML operator dictionary.
operators :: [Operator]

module Text.TeXMath.Writers.TeX

-- | Transforms an expression tree to equivalent LaTeX with the default
--   packages (amsmath and amssymb)
writeTeX :: [Exp] -> String

-- | Transforms an expression tree to equivalent LaTeX with the specified
--   packages
writeTeXWith :: Env -> [Exp] -> String

-- | Adds the correct LaTeX environment around a TeXMath fragment
addLaTeXEnvironment :: DisplayType -> String -> String
instance Show MathState
instance Functor Math
instance Applicative Math
instance Monad Math
instance MonadReader MathState Math
instance MonadWriter [TeX] Math


-- | Functions for writing a parsed formula as a list of Pandoc Inlines.
module Text.TeXMath.Writers.Pandoc

-- | Attempts to convert a formula to a list of <a>Pandoc</a> inlines.
writePandoc :: DisplayType -> [Exp] -> Maybe [Inline]


-- | Functions for writing a parsed formula as OMML.
module Text.TeXMath.Writers.OMML

-- | Transforms an expression tree to an OMML XML Tree
writeOMML :: DisplayType -> [Exp] -> Element


-- | Functions for writing a parsed formula as MathML.
module Text.TeXMath.Writers.MathML

-- | Transforms an expression tree to a MathML XML tree
writeMathML :: DisplayType -> [Exp] -> Element


-- | Types and functions for conversion of OMML into TeXMath <a>Exp</a>s.
module Text.TeXMath.Readers.OMML
readOMML :: String -> Either String [Exp]
instance Show OMathRunElem
instance Show OMathTextScript
instance Eq OMathTextScript
instance Show OMathTextStyle
instance Eq OMathTextStyle
instance Show OMathRunTextStyle


-- | Parses MathML in conformance with the MathML3 specification.
--   
--   Unimplemented features:
--   
--   <ul>
--   <li>menclose</li>
--   <li>mpadded</li>
--   <li>mmultiscripts (etc)</li>
--   <li>malignmark</li>
--   <li>maligngroup</li>
--   <li>Elementary Math</li>
--   </ul>
--   
--   To Improve:
--   
--   <ul>
--   <li>Handling of menclose</li>
--   <li>Handling of mstyle</li>
--   </ul>
module Text.TeXMath.Readers.MathML

-- | Parse a MathML expression to a list of <a>Exp</a>.
readMathML :: String -> Either String [Exp]
instance Show SupOrSub
instance Eq SupOrSub
instance Show a => Show (IR a)


-- | Functions for parsing a LaTeX formula to a Haskell representation.
module Text.TeXMath.Readers.TeX

-- | Parse a formula, returning a list of <a>Exp</a>.
readTeX :: String -> Either String [Exp]


-- | Functions for converting between different representations of
--   mathematical formulas.
--   
--   Also note that in general <tt>writeLaTeX . readLaTeX /= id</tt>.
--   
--   A typical use is to combine together a reader and writer.
--   
--   <pre>
--   import Control.Applicative ((&lt;$&gt;))
--   import Text.TeXMath (writeMathML, readTeX)
--   
--   texMathToMathML :: DisplayType -&gt; String -&gt; Either String Element
--   texMathToMathML dt s = writeMathML dt &lt;$&gt; readTeX s
--   </pre>
--   
--   It is also possible to manipulate the AST using <a>Generics</a>. For
--   example, if you wanted to replace all occurences of the identifier x
--   in your expression, you do could do so with the following script.
--   
--   <pre>
--   import Control.Applicative ((&lt;$&gt;))
--   import Data.Generics (everywhere, mkT)
--   import Text.TeXMath (writeMathML, readTeX)
--   import Text.TeXMath.Types
--   import Text.XML.Light (Element)
--   
--   changeIdent :: Exp -&gt; Exp
--   changeIdent (EIdentifier "x") = EIdentifier "y"
--   changeIdent e = e
--   
--   texToMMLWithChangeIdent :: DisplayType -&gt; String -&gt; Either String Element
--   texToMMLWithChangeIdent dt s =
--     writeMathML dt . everywhere (mkT changeIdent) &lt;$&gt; readTeX s
--   </pre>
module Text.TeXMath

-- | Parse a MathML expression to a list of <a>Exp</a>.
readMathML :: String -> Either String [Exp]
readOMML :: String -> Either String [Exp]

-- | Parse a formula, returning a list of <a>Exp</a>.
readTeX :: String -> Either String [Exp]

-- | Transforms an expression tree to equivalent LaTeX with the default
--   packages (amsmath and amssymb)
writeTeX :: [Exp] -> String

-- | Transforms an expression tree to equivalent LaTeX with the specified
--   packages
writeTeXWith :: Env -> [Exp] -> String

-- | Adds the correct LaTeX environment around a TeXMath fragment
addLaTeXEnvironment :: DisplayType -> String -> String

-- | Transforms an expression tree to an OMML XML Tree
writeOMML :: DisplayType -> [Exp] -> Element

-- | Transforms an expression tree to a MathML XML tree
writeMathML :: DisplayType -> [Exp] -> Element

-- | Attempts to convert a formula to a list of <a>Pandoc</a> inlines.
writePandoc :: DisplayType -> [Exp] -> Maybe [Inline]
data DisplayType

-- | A displayed formula.
DisplayBlock :: DisplayType

-- | A formula rendered inline in text.
DisplayInline :: DisplayType
data Exp
