Populate values at parser level

*** BREAKING CHANGE ***

This is a fairly large re-think of how argument values are fetched from
the their various input sources. Before, values would be loaded during
a step after parsing, where the matched usage branch would be completely
unrolled, unified and then populated. This had the disadvantage that one
could not tell which of the mutually exclusive branches produced a
result, since one value might arrive from ARGV and another one from the
[default: ...] tag, or the environment, etc. (See #8)

Now, values are loaded at parse-time, removing these issues. Further,
"empty" values are elided from the output, representing the user *not
trying* to match these keys (as opposed to choosing to set them
explicitly). For example, the user might pass the value 'false' to an
option and that value will be retained. If the option however yields
false because there was no user input and because 'false' is its' empty
fall-back, the value will be omitted. The same goes for matching
repeating elements into an array. At least one element needs to be
matched before a value will be yielded.

The diff of 'testcases.docopt' should highlight these changes better
than any amount of explanatory text could.

This patch also removes the "ScoredResult" type as it is no longer
needed. Scoring is based on the "Origin" of a value now. This somewhat
simplifies the code.

Lastly, there's now a recursive step inside `genExhaustiveParser` that
recursively evaluates missing elements until all options have been
exhausted or failed.

src/Docopt/Docopt.purs

@@ -80,8 +80,7 @@ run :: forall e
 run d o = do
   argv <- maybe (A.drop 2 <$> Process.argv) (return <<< id) o.argv
   env  <- maybe Process.getEnv              (return <<< id) o.env
-  either onError return
-         do
+  either onError return do
           { specification, usage } <- parseDocopt d o.smartOptions
           lmap ((help usage) ++ _) do
             evalDocopt specification env argv o.optionsFirst

src/Language/Docopt.purs

@@ -43,20 +43,6 @@ data Origin
   | Environment
   | Default
 
--- newtype RichValue = RichValue {
---   value   :: D.Value
--- , origin  :: Origin
--- , env     :: Maybe {
---     key   :: String
---   , value :: Maybe String
---   }
--- , default :: Maybe D.Value
--- }
-
--- data Output
---   = SimpleOutput (StrMap D.Value)
---   | RichOutput   (StrMap RichValue)
-
 -- |
 -- | Parse the docopt text and produce a parser
 -- | that can be applied to user input.

src/Language/Docopt/Trans/Origin.purs → src/Language/Docopt/Origin.purs

@@ -1,4 +1,4 @@
-module Language.Docopt.Trans.Origin (
+module Language.Docopt.Origin (
   Origin(..)
   ) where
 
@@ -17,6 +17,12 @@ weight Environment = 2
 weight Default     = 1
 weight Empty       = 0
 
+instance showOrigin :: Show Origin where
+  show Argv        = "Argv"
+  show Environment = "Environment"
+  show Default     = "Default"
+  show Empty       = "Empty"
+
 instance eqOrigin :: Eq Origin where
   eq Argv        Argv        = true
   eq Environment Environment = true

src/Language/Docopt/ParserGen.purs

@@ -22,9 +22,9 @@ import Language.Docopt.ParserGen.Token (PositionedToken(..), Token(..),
                                         getSource, prettyPrintToken,
                                         unPositionedToken) as G
 import Language.Docopt.ParserGen.Parser (Parser, genUsageParser,
-                                        initialState) as G
+                                        RichValue(..), unRichValue,
+                                        from, initialState, ValueMapping()) as G
 import Language.Docopt.ParserGen.Lexer (lex) as G
-import Language.Docopt.ParserGen.ValueMapping (ValueMapping) as G
 
 type Result = Tuple D.Branch (List G.ValueMapping)