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


-- | Rendering from and scanning to format strings
--   
--   Rendering from and scanning to simple format strings
@package format
@version 0.1.0.0

module Text.Format

-- | Parse a format string into a <a>Format</a> object ready to be used in
--   <a>renderFormat</a> and <a>scanFormat</a>.
--   
--   The format string consists of raw tokens (ordinary characters), and
--   variables, marked '$varname' or '${varname}'. The dollar sign may be
--   used as a raw token by escaping it with another dollar sign, like so:
--   <tt>$$</tt>. (If you want a variable named $, use '${$}'.)
--   
--   Not all syntactically valid parse strings are semantically valid. In
--   particular, two variables must not occur consecutively without
--   interleaving raw tokens. (If this were permitted, the resulting
--   grammar would be ambiguous.)
--   
--   Variable names may be used twice; however, this will make the result
--   of <a>scanFormat</a> somewhat difficult to deal with.
--   
--   The functions <a>renderFormatString</a> and <a>scanFormatString</a>
--   are provided as conveniences to make doing this explicitly
--   unnecessary.
parseFormat :: String -> Either String Format
renderFormat :: Format -> (String -> Maybe String) -> Either String String

-- | A more convenient alternative to using <a>parseFormat</a> and
--   <a>renderFormat</a>.
renderFormatString :: String -> (String -> Maybe String) -> Either String String

-- | Parses a string using the given format as a guide, generating a list
--   of pairs of variable names and values.
--   
--   To determine where a variable ends, the entire subsequent string of
--   raw tokens (until the next variable or the end of the string) is used
--   as a terminator. It must occur verbatim in the scanned string or the
--   parse will fail. The smallest match is used: if the format string is
--   '${a}:' and the input string is '1:2:', the parse will exit with an
--   error, as only the first character will be considered part of the
--   variable <tt>a</tt>.
scanFormat :: Format -> String -> Either String [(String, String)]

-- | A more convenient alternative to using <a>parseFormat</a> and
--   <a>scanFormat</a>.
scanFormatString :: String -> String -> Either String [(String, String)]