Fixes xenomachina#27. Add inline block parsing method (xenomachina#32)

Author: shanethehat

README.md

@@ -362,6 +362,28 @@ And equally easy to create a program that behaves like `cp`:
   ```
 
 
+## Forcing Parsing
+
+It is possible to enforce the parsing of arguments into a class of values. This 
+ensures that all arguments that are required are provided, and all arguments 
+provided are consumed. Forcing can be done in separate steps:
+
+  ```kotlin
+  val parser = ArgParser(args)
+  val parsedArgs = ParsedArgs(parser)
+  parser.force()
+  // now you can use parsedArgs
+  ```
+  
+Alternatively forcing of parsing and validation can be done inline:
+
+  ```kotlin
+  val parsedArgs = ArgParser(args).parseInto(::ParsedArgs)
+  // now you can use parsedArgs
+  ```
+  
+In both cases exceptions will be thrown where parsing or validation errors are found.    
+
 ## Help Formatting
 
 By default, `ArgParser` will add a `--help` option (short name `-h`) for

src/main/kotlin/com/xenomachina/argparser/ArgParser.kt

@@ -457,6 +457,18 @@ class ArgParser(args: Array<out String>,
         finished = true
     }
 
+    /**
+     * Provides an instance of T, where all arguments have already been parsed and validated
+     */
+    fun <T> parseInto(constructor: (ArgParser) -> T): T {
+        if (builtinDelegateCount != delegates.size) {
+            throw IllegalStateException("You can only use the parseInto function with a clean ArgParser instance")
+        }
+        val provided = constructor(this)
+        force()
+        return provided
+    }
+
     private var parseStarted = false
 
     internal fun checkNotParsed() {
@@ -590,6 +602,8 @@ class ArgParser(args: Array<out String>,
             }.default(Unit).registerRoot()
         }
     }
+
+    private val builtinDelegateCount = delegates.size
 }
 
 private val NAME_EQUALS_VALUE_REGEX = Regex("^([^=]+)=(.*)$")

src/test/kotlin/com/xenomachina/argparser/ArgParserTest.kt

@@ -1454,6 +1454,49 @@ class PositionalListAddValidatorTest : Test({
     }
 })
 
+class ParseIntoTest : Test({
+    class Args(parser: ArgParser) {
+        val str by parser.storing(TEST_HELP)
+    }
+
+    parserOf("--str=foo").parseInto(::Args).run {
+        str shouldBe "foo"
+    }
+})
+
+class ParseIntoUnrecognizedOptionFailureTest : Test({
+    class Args(parser: ArgParser) {
+        val str by parser.storing(TEST_HELP)
+    }
+
+    shouldThrow<UnrecognizedOptionException> {
+        parserOf("--str=foo", "--eggs=bacon").parseInto(::Args)
+    }.run { }
+})
+
+class ParseIntoMissingValueFailureTest : Test({
+    class Args(parser: ArgParser) {
+        val str by parser.storing(TEST_HELP)
+        val eggs by parser.storing(TEST_HELP)
+    }
+
+    shouldThrow<MissingValueException> {
+        parserOf("--str=foo").parseInto(::Args)
+    }.run { }
+})
+
+class ParseIntoIllegalStateTest : Test ({
+    class Args(parser: ArgParser) {
+        val str by parser.storing(TEST_HELP)
+    }
+
+    shouldThrow<IllegalStateException> {
+        val parser = parserOf("--str=foo")
+        val oops by parser.storing("--oops", help = TEST_HELP).default("oops")
+        parser.parseInto(::Args)
+    }.run { }
+})
+
 class Issue15Test : Test({
     class Args(parser: ArgParser) {
         val manual by parser.storing("--named-by-hand", help = TEST_HELP, argName = "HANDYS-ARG")