diff --git a/src/Text/ParserCombinators/UU.hs b/src/Text/ParserCombinators/UU.hs --- a/src/Text/ParserCombinators/UU.hs +++ b/src/Text/ParserCombinators/UU.hs @@ -14,7 +14,7 @@ -- -- * how to use the permutating/merging parsers -- --- * to see the parsers in action load the module "Text.ParserCombinators.UU.Demo.Examples" or "Text.ParserCombinators.UU.Demo.MergeAndPermute"in @ghci@ and type @show_demos@, while looking at the corresponding code +-- * to see the parsers in action load the module "Text.ParserCombinators.UU.Demo.Examples" or "Text.ParserCombinators.UU.Demo.MergeAndPermute" in @ghci@ and type @show_demos@, while looking at the corresponding code -- module Text.ParserCombinators.UU ( module Text.ParserCombinators.UU.Core diff --git a/src/Text/ParserCombinators/UU/BasicInstances.hs b/src/Text/ParserCombinators/UU/BasicInstances.hs --- a/src/Text/ParserCombinators/UU/BasicInstances.hs +++ b/src/Text/ParserCombinators/UU/BasicInstances.hs @@ -9,13 +9,13 @@ TypeSynonymInstances, ScopedTypeVariables #-} --- | This module caontains basic instances for the class interface described in the "Text.ParserCombinators.UU.Core" module. --- It demonstates how to use construct and maintain a state during parsing. In the state we store error messages, +-- | This module contains basic instances for the class interface described in the "Text.ParserCombinators.UU.Core" module. +-- It demonstates how to construct and maintain a state during parsing. In the state we store error messages, -- positional information and the actual input that is being parsed. -- Unless you have very specific wishes the module can be used as such. -- Since we make use of the "Data.ListLike" interface a wide variety of input structures can be handled. -- --- The main part of this module is made up from the various instances for the class `Provides` +-- The main part of this module is made up from the various instances for the class `Provides`. module Text.ParserCombinators.UU.BasicInstances( -- * Data Types @@ -74,7 +74,7 @@ -- * The Stream data type -- | The data type `Str` holds the input data to be parsed, the current location, the error messages generated --- and whether it is ok to delet elements from the input. Since an insert/delete action is +-- and whether it is ok to delete elements from the input. Since an insert/delete action is -- the same as a delete/insert action we try to avoid the first one. -- So: no deletes after an insert. @@ -88,7 +88,7 @@ deleteOk :: !Bool } --- | A`Parser` is a parser that is prepared to accept "Data.Listlike" input; hence we can deal with @String@'s, @ByteString@'s, etc. +-- | A `Parser` is a parser that is prepared to accept "Data.Listlike" input; hence we can deal with @String@'s, @ByteString@'s, etc. type Parser a = (IsLocationUpdatedBy loc Char, LL.ListLike state Char) => P (Str Char state loc) a -- | A @`ParserTrafo` a b@ maps a @`Parser` a@ onto a @`Parser` b@. @@ -99,7 +99,7 @@ createStr beginpos ls = Str ls [] beginpos True --- | The first parameter is the current position, and the second parameter the part which has been removed from the input. +-- The first parameter is the current position, and the second parameter the part which has been removed from the input. instance IsLocationUpdatedBy Int Char where advance pos _ = pos + 1 diff --git a/src/Text/ParserCombinators/UU/CHANGELOG.hs b/src/Text/ParserCombinators/UU/CHANGELOG.hs --- a/src/Text/ParserCombinators/UU/CHANGELOG.hs +++ b/src/Text/ParserCombinators/UU/CHANGELOG.hs @@ -1,5 +1,9 @@ -- | This module just contains the CHANGELOG -- +-- Version 2.7.0.1 +-- +-- * Typos fixed in Haddock documentation +-- -- Version 2.7.0 -- -- Improvement: change of error correction at end of @amb@ combinator, so lookahead is better taken into account @@ -18,9 +22,9 @@ -- this may require some rwriting of existing parsers. Readbaility is supposed to improve from that. -- Types become simpler. For an example see the module "Text.ParserCombinators.UU.Utils". -- --- * Included a Demo directory, with a modules for demonstrating nromal parsers and one aimed at merging parsers +-- * Included a Demo directory, with a modules for demonstrating normal parsers and one aimed at merging parsers -- --- * added the module "Text.ParserCombinaors.UU.Idioms", which contains specialised version for the idiomatic notation; it infers the +-- * Added the module "Text.ParserCombinaors.UU.Idioms", which contains specialised version for the idiomatic notation; it infers the -- sequental composition operators from the types of the operands; @String@-s and @Char@-s are not supposed to contribute to the result, -- function parameters are lifted using `pure`, and normal parsers are composed with `<*>`. -- diff --git a/src/Text/ParserCombinators/UU/Core.hs b/src/Text/ParserCombinators/UU/Core.hs --- a/src/Text/ParserCombinators/UU/Core.hs +++ b/src/Text/ParserCombinators/UU/Core.hs @@ -61,9 +61,9 @@ class (Alternative p) => ExtAlternative p where -- | `<<|>` is the greedy version of `<|>`. If its left hand side parser can - -- make any progress that alternative is committed. Can be used to make + -- make any progress then it commits to that alternative. Can be used to make -- parsers faster, and even get a complete Parsec equivalent behaviour, with - -- all its (dis)advantages. Intended use @p \<\<\|> q \<\<\|> r \<\|> x \<\|> y \ "string"@. Use with care! + -- all its (dis)advantages. Intended use @p \<\<\|> q \<\<\|> r \<\|> x \<\|> y \ \"string\"@. Use with care! (<<|>) :: p a -> p a -> p a -- | The parsers build a list of symbols which are expected at a specific point. -- This list is used to report errors. @@ -71,7 +71,7 @@ -- The `` combinator replaces this list of symbols by the string argument. () :: p a -> String -> p a -- | `doNotInterpret` makes a parser opaque for abstract interpretation; used when permuting parsers - -- where we do not want to compare lengths + -- where we do not want to compare lengths. doNotInterpret :: p a -> p a doNotInterpret = id -- | `must_be_non_empty` checks whether its second argument @@ -121,9 +121,11 @@ -- called in the `splitState` functions. class Show loc => loc `IsLocationUpdatedBy` str where - advance::loc -> str -> loc + advance :: loc -- ^ The current position + -> str -- ^ The part which has been removed from the input + -> loc --- | The class `StoresErrors` is used by the function `pErrors` which retreives the generated +-- | The class `StoresErrors` is used by the function `pErrors` which retrieves the generated -- correction steps since the last time it was called. -- @@ -134,8 +136,8 @@ class state `HasPosition` pos | state -> pos where - -- | `getPos` retreives the correcting steps made since the last time the function was called. The result can, - -- by usingit as the left hand sie of a mondaic bind, be used to control how to proceed with the parsing process. + -- | `getPos` retrieves the correcting steps made since the last time the function was called. The result can, + -- by using it as the left hand side of a monadic bind, be used to control how to proceed with the parsing process. getPos :: state -> pos -- | The data type `T` contains three components, all being some form of primitive parser. @@ -180,13 +182,13 @@ instance Show (P st a) where show (P _ nt n e) = "P _ " ++ maybe "Nothing" (const "(Just _)") nt ++ " (" ++ show n ++ ") " ++ maybe "Nothing" (const "(Just _)") e --- | `getOneP` retreives the non-zero part from a descriptor +-- | `getOneP` retrieves the non-zero part from a descriptor. getOneP :: P a b -> Maybe (P a b) -- getOneP (P _ (Just _) (Zero Unspecified) _ ) = error "The element is a special parser which cannot be combined" getOneP (P _ Nothing l _ ) = Nothing getOneP (P _ onep l ep ) = Just( mkParser onep Nothing (getLength l)) --- | `getZeroP` retreives the possibly empty part from a descriptor +-- | `getZeroP` retrieves the possibly empty part from a descriptor. getZeroP :: P t a -> Maybe a getZeroP (P _ _ _ z) = z @@ -292,9 +294,9 @@ unParser_r (P (T _ _ r ) _ _ _ ) = r return = pure --- | The function `pSymExt` converts a very basic parser, passed to at as the function `splitState`, --- the minmal number of tokens recognised by the function and and empty descriptor, and builds a @P@ parser out of this, --- i.e. lift the behaviour to a fture pareser, a histroy parser and a recogniser. +-- | The basic recognisers are written elsewhere (e.g. in our module "Text.ParserCombinataors.UU.BasicInstances"; +-- they (i.e. the parameter `splitState`) are lifted to our`P` descriptors by the function `pSymExt` which also takes +-- the minimal number of tokens recognised by the parameter `spliState` and an @Maybe@ value describing the possibly empty value. pSymExt :: (forall a. (token -> state -> Steps a) -> state -> Steps a) -> Nat -> Maybe token -> P state token pSymExt splitState l e = mkParser (Just t) e l where t = T ( splitState ) @@ -326,7 +328,7 @@ nep = (fmap pure pe) in mkParser nnp nep pl --- | `pErrors` returns the error messages that were generated since its last call +-- | `pErrors` returns the error messages that were generated since its last call. pErrors :: StoresErrors st error => P st [error] pErrors = let nnp = Just (T ( \ k inp -> let (errs, inp') = getErrors inp in k errs inp' ) ( \ k inp -> let (errs, inp') = getErrors inp in push errs (k inp')) @@ -334,7 +336,7 @@ nep = (Just (error "pErrors cannot occur in lhs of bind")) -- the errors consumed cannot be determined statically! in mkParser nnp Nothing (Zero Infinite) --- | `pPos` returns the current input position +-- | `pPos` returns the current input position. pPos :: HasPosition st pos => P st pos pPos = let nnp = Just ( T ( \ k inp -> let pos = getPos inp in k pos inp ) ( \ k inp -> let pos = getPos inp in push pos (k inp)) @@ -349,7 +351,7 @@ ($)) in mkParser nnp Nothing (Zero Infinite) --- | The function `pEnd` should be called at the end of the parsing process. It deletes any unconsumed input, turning them into error messages +-- | The function `pEnd` should be called at the end of the parsing process. It deletes any unconsumed input, turning it into error messages. pEnd :: (StoresErrors st error, Eof st) => P st [error] pEnd = let nnp = Just ( T ( \ k inp -> let deleterest inp = case deleteAtEnd inp of @@ -370,10 +372,10 @@ in mkParser nnp Nothing (Zero Infinite) -- | @`pSwitch`@ takes the current state and modifies it to a different type of state to which its argument parser is applied. --- The second component of the result is a function which converts the remaining state of this parser back into a valuee of the original type. --- For the second argumnet to @`pSwitch`@ (say split) we expect the following to hold: +-- The second component of the result is a function which converts the remaining state of this parser back into a value of the original type. +-- For the second argument to @`pSwitch`@ (say split) we expect the following to hold: -- --- > let (n,f) = split st in f n to be equal to st +-- > let (n,f) = split st in f n == st pSwitch :: (st1 -> (st2, st2 -> st1)) -> P st2 a -> P st1 a -- we require let (n,f) = split st in f n to be equal to st pSwitch split (P _ np pl pe) @@ -400,22 +402,23 @@ else error "pEnd missing?") -- | The data type `Steps` is the core data type around which the parsers are constructed. --- It is a describes a tree structure of streams containing (in an interleaved way) both the online result of the parsing process, +-- It describes a tree structure of streams containing (in an interleaved way) both the online result of the parsing process, -- and progress information. Recognising an input token should correspond to a certain amount of @`Progress`@, -- which tells how much of the input state was consumed. -- The @`Progress`@ is used to implement the breadth-first search process, in which alternatives are --- examined in a more-or-less synchonised way. The meaning of the various @`Step`@ constructors is as follows: +-- examined in a more-or-less synchronised way. The meaning of the various @`Step`@ constructors is as follows: -- -- [`Step`] A token was succesfully recognised, and as a result the input was 'advanced' by the distance @`Progress`@ -- -- [`Apply`] The type of value represented by the `Steps` changes by applying the function parameter. -- --- [`Fail`] A correcting step has to made to the input; the first parameter contains information about what was expected in the input, +-- [`Fail`] A correcting step has to be made to the input; the first parameter contains information about what was expected in the input, -- and the second parameter describes the various corrected alternatives, each with an associated `Cost` -- -- [`Micro`] A small cost is inserted in the sequence, which is used to disambiguate. Use with care! -- --- The last two alternatives play a role in recognising ambigous non-terminals. For a full description see the technical report referred to from the README file.. +-- The last two alternatives play a role in recognising ambigous non-terminals. For a full description see the technical report referred to from +-- "Text.ParserCombinators.UU.README". @@ -453,9 +456,9 @@ has_success (Step _ _) = True has_success _ = False --- ! @`eval`@ removes the progress information from a sequence of steps, and constructs the value embedded in it. +-- | @`eval`@ removes the progress information from a sequence of steps, and constructs the value embedded in it. -- If you are really desparate to see how your parsers are making progress (e.g. when you have written an ambiguous parser, and you cannot find the cause of --- the exponential blow-up of your parsing process, you may switch on the trace in the function @`eval`@ +-- the exponential blow-up of your parsing process), you may switch on the trace in the function @`eval`@ (you will need to edit the library source code). -- eval :: Steps a -> a eval (Step n l) = {- trace ("Step " ++ show n ++ "\n")-} (eval l) diff --git a/src/Text/ParserCombinators/UU/Demo/Examples.hs b/src/Text/ParserCombinators/UU/Demo/Examples.hs --- a/src/Text/ParserCombinators/UU/Demo/Examples.hs +++ b/src/Text/ParserCombinators/UU/Demo/Examples.hs @@ -6,7 +6,7 @@ CPP #-} -- | This module contains a lot of examples of the typical use of our parser combinator library. --- We strongly encourage you to take a look at the source code +-- We strongly encourage you to take a look at the source code. -- At the end you find a @`main`@ function which demonstrates the main characteristics. -- Only the @`run`@ function is exported since it may come in handy elsewhere. @@ -120,7 +120,7 @@ show_errors = sequence_ . (map (putStrLn . show)) -- | Our first two parsers are simple; one recognises a single 'a' character and the other one a single 'b'. Since we will use them later we --- convert the recognsised character into `String` so they can be easily combined. +-- convert the recognised character into `String` so they can be easily combined. pa ::Parser String pa = lift <$> pSym 'a' pb :: Parser String diff --git a/src/Text/ParserCombinators/UU/Derived.hs b/src/Text/ParserCombinators/UU/Derived.hs --- a/src/Text/ParserCombinators/UU/Derived.hs +++ b/src/Text/ParserCombinators/UU/Derived.hs @@ -7,23 +7,23 @@ UndecidableInstances, NoMonomorphismRestriction #-} +-- | This module contains a large variety of combinators for list-like structures. the extension @_ng@ indicates that +-- that variant is the non-greedy variant. +-- See the "Text.ParserCombinators.UU.Demo.Examples" module for some examples of their use. + module Text.ParserCombinators.UU.Derived where import Text.ParserCombinators.UU.Core import Control.Applicative --- | This module contains a large variety of combinators for list-lile structures. the extension @_ng@ indiactes that --- that variant is the non-greedy variant. --- See the "Text.ParserCombinators.UU.Demo.Examples" module for some examples of their use. - -- * Some aliases for oft occurring constructs --- | @`pReturn`@ is defined for upwards comptaibility +-- | @`pReturn`@ is defined for upwards compatibility -- pReturn :: Applicative p => a -> p a pReturn = pure --- | @`pFail`@ is defined for upwards comptaibility, and is the unit for @<|>@ +-- | @`pFail`@ is defined for upwards compatibility, and is the unit for @<|>@ -- pFail :: Alternative p => p a pFail = empty @@ -38,7 +38,7 @@ pEither :: IsParser p => p a -> p b -> p (Either a b) pEither p q = Left <$> p <|> Right <$> q --- | `<$$>` is the version of `<$>` whichflips the function argument +-- | `<$$>` is the version of `<$>` which flips the function argument -- (<$$>) :: IsParser p => (a -> b -> c) -> p b -> p (a -> c) f <$$> p = flip f <$> p @@ -144,7 +144,7 @@ -- * Repeating parsers --- | `pExact` recocgnises a specified number of elements +-- | `pExact` recognises a specified number of elements pExact :: (IsParser f) => Int -> f a -> f [a] pExact n p | n == 0 = pure [] | n > 0 = (:) <$> p <*> pExact (n-1) p diff --git a/src/Text/ParserCombinators/UU/Idioms.hs b/src/Text/ParserCombinators/UU/Idioms.hs --- a/src/Text/ParserCombinators/UU/Idioms.hs +++ b/src/Text/ParserCombinators/UU/Idioms.hs @@ -16,10 +16,10 @@ import Control.Applicative --- | The `Ii` is to be pronouunced as @stop@ +-- | The `Ii` is to be pronounced as @stop@ data Ii = Ii --- | The function `iI` is to be pronouunced as @start@ +-- | The function `iI` is to be pronounced as @start@ iI :: Idiomatic (Str Char state loc) (a -> a) g => g iI = idiomatic (pure id) diff --git a/src/Text/ParserCombinators/UU/MergeAndPermute.hs b/src/Text/ParserCombinators/UU/MergeAndPermute.hs --- a/src/Text/ParserCombinators/UU/MergeAndPermute.hs +++ b/src/Text/ParserCombinators/UU/MergeAndPermute.hs @@ -1,8 +1,8 @@ {-# LANGUAGE ExistentialQuantification #-} -- | This module contains the additional data types, instance definitions and functions to run parsers in an interleaved way. --- If all the interlevaed parsers recognise a single connected piece of the input text this incorporates the permutation parsers. --- For some examples see the module "Text.ParserCombinators.UU.Demo.MergeAndpermute" +-- If all the interleaved parsers recognise a single connected piece of the input text this incorporates the permutation parsers. +-- For some examples see the module "Text.ParserCombinators.UU.Demo.MergeAndPermute". module Text.ParserCombinators.UU.MergeAndPermute where import Text.ParserCombinators.UU.Core @@ -13,7 +13,7 @@ -- * The data type `Gram` --- | Since we want to get access to the individial parsers which recognise a consecutive piece of the input text we +-- | Since we want to get access to the individual parsers which recognise a consecutive piece of the input text we -- define a new data type, which lifts the underlying parsers to the grammatical level, so they can be transformed, manipulated, and run in a piecewise way. -- `Gram` is defined in such a way that we can always access the first parsers to be ran from such a structure. -- We require that all the `Alt`s do not recognise the empty string. These should be covered by the `Maybe` in the `Gram` constructor. @@ -26,7 +26,7 @@ -- | The function `mkGram` splits a simple parser into the possibly empty part and the non-empty part. -- The non-empty part recognises a consecutive part of the input. --- Here we use the function `getOneP` and `getZeroP` which are provided in the uu-parsinglib package, +-- Here we use the functions `getOneP` and `getZeroP` which are provided in the uu-parsinglib package, -- but they could easily be provided by other packages too. mkGram :: P t a -> Gram (P t) a @@ -92,20 +92,21 @@ ) (pe <*> qe) -- | The function `<<||>` is a special version of `<||>`, whch only starts a new instance of its right operand when the left operand cannot proceed. --- This is used in the function pmMany, where we want to merge as many instances of its argument, but not more than that. +-- This is used in the function 'pmMany', where we want to merge as many instances of its argument, but not more than that. +(<<||>):: Functor f => Gram f (b->a) -> Gram f b -> Gram f a pg@(Gram pl pe) <<||> ~qg@(Gram ql qe) = Gram ( [ p `Seq` (flip <$> pp <||> qg)| p `Seq` pp <- pl] ) (pe <*> qe) --- | `mkPaserM` converts a `Gram`mar beack into a parser, which can subsequenly be run. +-- | 'mkParserM' converts a `Gram`mar back into a parser, which can subsequenly be run. mkParserM :: (Monad f, Applicative f, ExtAlternative f) => Gram f a -> f a mkParserM (Gram ls le) = foldr (\ p pp -> doNotInterpret p <|> pp) (maybe empty pure le) (map mkParserAlt ls) where mkParserAlt (p `Seq` pp) = p <**> mkParserM pp mkParserAlt (fc `Bind` c2fa) = fc >>= (mkParserM . c2fa) --- | `mkParserS` is like `mkParserM`, with the additional feature that we allow seprators between the components. Only useful in the permuting case. +-- | `mkParserS` is like `mkParserM`, with the additional feature that we allow separators between the components. Only useful in the permuting case. mkParserS :: (Monad f, Applicative f, ExtAlternative f) => f b -> Gram f a -> f a mkParserS sep (Gram ls le) = foldr (\ p pp -> doNotInterpret p <|> pp) (maybe empty pure le) (map mkParserAlt ls) where mkParserAlt (p `Seq` pp) = p <**> mkParserP sep pp diff --git a/src/Text/ParserCombinators/UU/README.hs b/src/Text/ParserCombinators/UU/README.hs --- a/src/Text/ParserCombinators/UU/README.hs +++ b/src/Text/ParserCombinators/UU/README.hs @@ -8,12 +8,12 @@ -- -- which is also available as a technical report from -- --- The first part of this report is a general introduction into parser combinators, whereas the second part contains the +-- The first part of this report is a general introduction to parser combinators, whereas the second part contains the -- motivation for and documentation of the current package. -- -- We appreciate if you include a reference to the above documentation in any publication describing software in which you have used the library succesfully. -- --- Any feedback on particular use of the library, and suggestions for extensions, are welcome at mailto:doaitse\@swierstra.net +-- Any feedback on particular use of the library, and suggestions for extensions, are welcome at -- module Text.ParserCombinators.UU.README () where diff --git a/uu-parsinglib.cabal b/uu-parsinglib.cabal --- a/uu-parsinglib.cabal +++ b/uu-parsinglib.cabal @@ -1,5 +1,5 @@ Name: uu-parsinglib -Version: 2.7.0 +Version: 2.7.0.1 Build-Type: Simple License: MIT Copyright: S Doaitse Swierstra