extra arguments support

Author: hellflame

README.md

@@ -199,6 +199,22 @@ Customize argument hint with `&argparse.Option{HintInfo: "customize info"}`
 
 [example](examples/sub-command)
 
+#### 3. Extra special positional arguments [ >= v1.12 ]
+
+When the user want to input some special arguments starting with `-` or `--` , normally the parser will warn you with  `unrecognized arguments`. 
+
+If you want to do so, simply input any arguments after a single `--`. 
+
+For example: `./run -- extra1 extra2`.  In the example, `extra1`  and `extra2` can be anything, `./run -- --1 -x`.
+
+If the last positional argument receives multiple inputs, then the positional inputs before and after `--` will all be its value.
+
+```go
+names := parser.Strings("", "names", &argparse.Option{Positional: true})
+parser.parse([]string{"a", "--", "b", "c"})
+// names == ["a", "b", "c"]
+```
+
 ### Supported Arguments
 
 #### 1. Flag
@@ -311,7 +327,7 @@ if e := parser.Parse(nil); e != nil {
 }
 
 if *path != "" {
-  if read, e := ioutil.ReadFile(*path); e == nil {
+  if read, e := os.ReadFile(*path); e == nil {
     fmt.Println(string(read))
   }
 }
@@ -1046,4 +1062,5 @@ feel free to add different use cases
 9. [batch create arguments](examples/batch-create-arguments)
 9. [argument inherit](examples/inherit)
 9. [color support](examples/colorful)
+9. [extra arguments](examples/extra-arguments)
 

args.go

@@ -13,7 +13,7 @@ type arg struct {
 	short    string
 	full     string
 	target   interface{}
-	assigned bool
+	assigned bool // whether the argument is parsed
 	Option
 }
 

docs/cn.md

@@ -193,6 +193,24 @@ options:
 
 [example](../examples/sub-command)
 
+#### 3. 额外的特殊位置参数 [ >= v1.12 ]
+
+当用户想要输入一些以 `-` 或 `--` 开头的一些入参，通常解析器会警告你 `未知的参数`。
+
+如果的确想要这样做，只需要把入参放到 `--` 之后。
+
+比如: `./run -- extra1 extra2`，在栗子里，`extra1` 和 `extra2` 可以是任何东西，比如: 
+
+`./run -- --1 -x`
+
+如果最后一个位置参数接受多个入参，那么用户在 `--` 前后的位置入参都会当作这个位置参数的值。
+
+```go
+names := parser.Strings("", "names", &argparse.Option{Positional: true})
+parser.parse([]string{"a", "--", "b", "c"})
+// names == ["a", "b", "c"]
+```
+
 ### 支持的参数
 
 #### 1. 标记参数
@@ -305,7 +323,7 @@ if e := parser.Parse(nil); e != nil {
 }
 
 if *path != "" {
-  if read, e := ioutil.ReadFile(*path); e == nil {
+  if read, e := os.ReadFile(*path); e == nil {
     fmt.Println(string(read))
   }
 }
@@ -1037,4 +1055,5 @@ type Option struct {
 9. [参数分组](../examples/argument-groups)
 9. [批量创建参数](../examples/batch-create-arguments)
 9. [参数继承](../examples/inherit)
-9. [颜色支持](../examples/colorful)
+9. [颜色支持](../examples/colorful)
+9. [额外特殊参数](../examples/extra-arguments)

examples/any-type-action/main.go

@@ -7,7 +7,7 @@ package main
 
 import (
 	"fmt"
-	"io/ioutil"
+	"os"
 	"strconv"
 
 	"github.com/hellflame/argparse"
@@ -30,7 +30,7 @@ func main() {
 	}})
 
 	parser.String("", "b", &argparse.Option{Action: func(args []string) error {
-		raw, e := ioutil.ReadFile(args[0])
+		raw, e := os.ReadFile(args[0])
 		if e != nil {
 			return e
 		}

examples/customzed-types/main.go

@@ -11,7 +11,6 @@ package main
 
 import (
 	"fmt"
-	"io/ioutil"
 	"net/url"
 	"os"
 
@@ -46,7 +45,7 @@ func main() {
 	}
 
 	if *path != "" {
-		if read, e := ioutil.ReadFile(*path); e == nil {
+		if read, e := os.ReadFile(*path); e == nil {
 			fmt.Println(string(read))
 		}
 	}

examples/extra-arguments/.gitignore

@@ -0,0 +1,3 @@
+*
+!*.go
+!.gitignore

examples/extra-arguments/main.go

@@ -0,0 +1,32 @@
+//go:build ignore
+
+// this is show case for extra arguments after --
+//
+// if there are argument value happen to start with - or --, it may be regard as unknown arguments.
+// in this scenario, you can input any input after a --, eg: program -- extra1 extra2
+package main
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/hellflame/argparse"
+)
+
+func main() {
+	// example:
+	// go run main.go x y -- --x --y
+	parser := argparse.NewParser("basic", "this is a basic program", nil)
+	names := parser.Strings("", "names", &argparse.Option{Positional: true})
+	if e := parser.Parse(nil); e != nil {
+		switch e {
+		case argparse.BreakAfterHelpError:
+			os.Exit(1)
+		default:
+			fmt.Println(e.Error())
+		}
+		return
+	}
+	fmt.Printf("hello %s\n", strings.Join(*names, ", "))
+}

parse.go

@@ -465,14 +465,36 @@ fi
 `, p.formatBashCompletionScript(), p.formatZshCompletionScript())
 }
 
+// find extra positional arguments
+func findExtraPositionalArgs(args []string) (idx int, remains []string) {
+	startRemain := false
+	remainMark := "--"
+	for i, a := range args {
+		if startRemain {
+			remains = append(remains, a)
+		}
+		if !startRemain && a == remainMark {
+			startRemain = true
+			idx = i
+		}
+	}
+	return
+}
+
 // Parse will parse given args to bind to any registered arguments
 //
 // args: set nil to use os.Args[1:] by default
 func (p *Parser) Parse(args []string) error {
 	if args == nil {
 		args = os.Args[1:]
 	}
-	if len(args) == 0 {
+	extraIdx, remains := findExtraPositionalArgs(args)
+	hasExtra := len(remains) > 0
+	if hasExtra || extraIdx > 0 {
+		args = args[:extraIdx]
+	}
+
+	if len(args) == 0 && !hasExtra {
 		if p.config.DefaultAction != nil {
 			p.config.DefaultAction()
 		} else if !p.config.DisableDefaultShowHelp {
@@ -488,43 +510,53 @@ func (p *Parser) Parse(args []string) error {
 		lastPositionArgIndex := 0
 		registeredPositionsLength := len(p.positionArgs)
 		for len(args) > 0 {
+			// iterate user input args
 			sign := args[0]
 			if arg, ok := p.entryMap[sign]; ok {
 				if arg.isFlag {
 					_ = arg.parseValue(nil)
 					args = args[1:]
 				} else {
-					var tillNext []string // find user inputs before next registered optional argument
+					// find user inputs before next registered optional argument
+					var tillNext []string
 					for _, a := range args[1:] {
 						if _, isEntry := p.entryMap[a]; !isEntry {
 							tillNext = append(tillNext, a)
 						} else {
 							break
 						}
 					}
-					if len(tillNext) == 0 { // argument takes at least one input as argument, but there is 0
+					// argument takes at least one input as argument, but there is 0
+					if len(tillNext) == 0 {
 						return fmt.Errorf("argument %s expect argument",
 							strings.Join(arg.getWatchers(), "/"))
 					}
-					if arg.multi { // if argument takes more than one arguments, it will take all user input before next registered argument, and proceed 'args' parsing to next registered argument
+					// if argument takes more than one arguments,
+					// it will take all user input before next registered argument,
+					// and proceed 'args' parsing to next registered argument
+					if arg.multi {
 						e := arg.parseValue(tillNext)
 						if e != nil {
 							return e
 						}
 						args = args[len(tillNext)+1:]
-					} else { // then the argument takes only one argument, and proceed the left arguments for positional argument parsing
+					} else {
+						// then the argument takes only one argument
 						e := arg.parseValue(tillNext[0:1])
 						if e != nil {
 							return e
 						}
+						// proceed the left arguments for positional argument parsing
 						args = args[2:]
 					}
 				}
 			} else {
-				if registeredPositionsLength > lastPositionArgIndex { // while there is unparsed positional argument
+				// while there is unparsed positional argument
+				if registeredPositionsLength > lastPositionArgIndex {
 					arg := p.positionArgs[lastPositionArgIndex]
 					lastPositionArgIndex += 1
-					var tillNext []string // find user inputs before next registered optional argument
+					// find user inputs before next registered optional argument
+					var tillNext []string
 					for _, a := range args {
 						if _, isEntry := p.entryMap[a]; !isEntry {
 							tillNext = append(tillNext, a)
@@ -533,10 +565,13 @@ func (p *Parser) Parse(args []string) error {
 						}
 					}
 					if arg.multi {
-						e := arg.parseValue(tillNext)
+						// if any multi-type positional required,
+						// extra arguments with be regard as part of it
+						e := arg.parseValue(append(tillNext, remains...))
 						if e != nil {
 							return e
 						}
+						remains = []string{}
 						args = args[len(tillNext):]
 					} else {
 						e := arg.parseValue(tillNext[0:1])
@@ -579,6 +614,28 @@ func (p *Parser) Parse(args []string) error {
 		fmt.Println(p.FormatCompletionScript())
 		return BreakAfterShellScriptError
 	}
+
+	// apply extra arguments for only positional
+	if len(remains) > 0 {
+		for _, arg := range p.positionArgs {
+			if arg.assigned {
+				continue
+			}
+			if arg.multi {
+				e := arg.parseValue(remains)
+				if e != nil {
+					return e
+				}
+			} else {
+				e := arg.parseValue(remains[0:1])
+				if e != nil {
+					return e
+				}
+				remains = remains[1:]
+			}
+		}
+	}
+
 	entries := append(p.entries, p.positionArgs...)
 	for _, arg := range entries { // check Required & set Default value
 		if !arg.assigned && arg.Default != "" {