Add GetRequiredArg helper

api.go

@@ -17,6 +17,7 @@ type programTree struct {
 	Name            string
 	Description     string
 	SynopsisArgs    []help.SynopsisArg
+	SynopsisArgsIdx int // idx for the GetRequiredArg helper
 	ChildCommands   map[string]*programTree
 	ChildOptions    map[string]*option.Option
 	UnknownOptions  []*option.Option // Track unknown options in order in case they need to be passed to the remaining array.

helpers.go

@@ -0,0 +1,31 @@
+package getoptions
+
+import (
+	"fmt"
+
+	"github.com/DavidGamba/go-getoptions/text"
+)
+
+// GetRequiredArg - Get the next argument from the args list and error if it doesn't exist.
+// By default the error will include the HelpSynopsis section but it can be overriden with the list of sections or getoptions.HelpNone.
+//
+// If the arguments have been named with `opt.HelpSynopsisArg` then the error will include the argument name.
+func (gopt *GetOpt) GetRequiredArg(args []string, sections ...HelpSection) (string, []string, error) {
+	if len(args) < 1 {
+		if len(gopt.programTree.SynopsisArgs) > gopt.programTree.SynopsisArgsIdx {
+			argName := gopt.programTree.SynopsisArgs[gopt.programTree.SynopsisArgsIdx].Arg
+			fmt.Fprintf(Writer, text.ErrorMissingRequiredNamedArgument+"\n", argName)
+		} else {
+			fmt.Fprintf(Writer, "%s\n", text.ErrorMissingRequiredArgument)
+		}
+		if sections != nil {
+			fmt.Fprintf(Writer, "%s", gopt.Help(sections...))
+		} else {
+			fmt.Fprintf(Writer, "%s", gopt.Help(HelpSynopsis))
+		}
+		gopt.programTree.SynopsisArgsIdx++
+		return "", args, ErrorHelpCalled
+	}
+	gopt.programTree.SynopsisArgsIdx++
+	return args[0], args[1:], nil
+}

public_api_test.go

@@ -6,6 +6,7 @@ import (
 	"errors"
 	"fmt"
 	"os"
+	"path/filepath"
 	"reflect"
 	"testing"
 	"time"
@@ -14,6 +15,10 @@ import (
 	"github.com/DavidGamba/go-getoptions/text"
 )
 
+func executable(msg string) string {
+	return fmt.Sprintf(msg, filepath.Base(os.Args[0]))
+}
+
 // Test helper to compare two string outputs and find the first difference
 func firstDiff(got, expected string) string {
 	same := ""
@@ -3786,3 +3791,191 @@ func TestSetCalled(t *testing.T) {
 		}
 	})
 }
+
+func TestGetRequiredArg(t *testing.T) {
+	fn := func(ctx context.Context, opt *getoptions.GetOpt, args []string) error {
+		_, args, err := opt.GetRequiredArg(args)
+		if err != nil {
+			return err
+		}
+		_, args, err = opt.GetRequiredArg(args)
+		if err != nil {
+			return err
+		}
+		_, _, err = opt.GetRequiredArg(args)
+		if err != nil {
+			return err
+		}
+		return nil
+	}
+	t.Run("no args", func(t *testing.T) {
+		helpBuf := new(bytes.Buffer)
+		getoptions.Writer = helpBuf
+		opt := getoptions.New()
+		opt.SetCommandFn(fn)
+		opt.HelpCommand("help")
+		remaining, err := opt.Parse([]string{})
+		if err != nil {
+			t.Errorf("Unexpected error: %s", err)
+		}
+		err = opt.Dispatch(context.Background(), remaining)
+		if !errors.Is(err, getoptions.ErrorHelpCalled) {
+			t.Errorf("Unexpected error: %s", err)
+		}
+
+		expected := executable(`ERROR: Missing required argument
+SYNOPSIS:
+    %s [--help] [<args>]
+
+`)
+		if helpBuf.String() != expected {
+			t.Errorf("Wrong output:\n%s\n", firstDiff(helpBuf.String(), expected))
+		}
+	})
+	t.Run("no args", func(t *testing.T) {
+		helpBuf := new(bytes.Buffer)
+		getoptions.Writer = helpBuf
+		opt := getoptions.New()
+		opt.SetCommandFn(fn)
+		opt.HelpCommand("help")
+		remaining, err := opt.Parse([]string{"arg1", "arg2"})
+		if err != nil {
+			t.Errorf("Unexpected error: %s", err)
+		}
+		err = opt.Dispatch(context.Background(), remaining)
+		if !errors.Is(err, getoptions.ErrorHelpCalled) {
+			t.Errorf("Unexpected error: %s", err)
+		}
+
+		expected := executable(`ERROR: Missing required argument
+SYNOPSIS:
+    %s [--help] [<args>]
+
+`)
+		if helpBuf.String() != expected {
+			t.Errorf("Wrong output:\n%s\n", firstDiff(helpBuf.String(), expected))
+		}
+	})
+	t.Run("no named args", func(t *testing.T) {
+		helpBuf := new(bytes.Buffer)
+		getoptions.Writer = helpBuf
+		opt := getoptions.New()
+		opt.SetCommandFn(fn)
+		opt.HelpSynopsisArg("<arg1>", "arg1 desc")
+		opt.HelpSynopsisArg("<arg2>", "arg2 desc")
+		opt.HelpSynopsisArg("<arg3>", "arg3 desc")
+		opt.HelpCommand("help")
+		remaining, err := opt.Parse([]string{})
+		if err != nil {
+			t.Errorf("Unexpected error: %s", err)
+		}
+		err = opt.Dispatch(context.Background(), remaining)
+		if !errors.Is(err, getoptions.ErrorHelpCalled) {
+			t.Errorf("Unexpected error: %s", err)
+		}
+
+		expected := executable(`ERROR: Missing <arg1>
+SYNOPSIS:
+    %s [--help] <arg1> <arg2> <arg3>
+
+`)
+		if helpBuf.String() != expected {
+			t.Errorf("Wrong output:\n%s\n", firstDiff(helpBuf.String(), expected))
+		}
+	})
+	t.Run("no named args", func(t *testing.T) {
+		helpBuf := new(bytes.Buffer)
+		getoptions.Writer = helpBuf
+		opt := getoptions.New()
+		opt.SetCommandFn(fn)
+		opt.HelpSynopsisArg("<arg1>", "arg1 desc")
+		opt.HelpSynopsisArg("<arg2>", "arg2 desc")
+		opt.HelpSynopsisArg("<arg3>", "arg3 desc")
+		opt.HelpCommand("help")
+		remaining, err := opt.Parse([]string{"arg1", "arg2"})
+		if err != nil {
+			t.Errorf("Unexpected error: %s", err)
+		}
+		err = opt.Dispatch(context.Background(), remaining)
+		if !errors.Is(err, getoptions.ErrorHelpCalled) {
+			t.Errorf("Unexpected error: %s", err)
+		}
+
+		expected := executable(`ERROR: Missing <arg3>
+SYNOPSIS:
+    %s [--help] <arg1> <arg2> <arg3>
+
+`)
+		if helpBuf.String() != expected {
+			t.Errorf("Wrong output:\n%s\n", firstDiff(helpBuf.String(), expected))
+		}
+	})
+	t.Run("help section", func(t *testing.T) {
+		fn := func(ctx context.Context, opt *getoptions.GetOpt, args []string) error {
+			_, _, err := opt.GetRequiredArg(args, getoptions.HelpNone)
+			if err != nil {
+				return err
+			}
+			return nil
+		}
+		helpBuf := new(bytes.Buffer)
+		getoptions.Writer = helpBuf
+		opt := getoptions.New()
+		opt.SetCommandFn(fn)
+		opt.HelpSynopsisArg("<arg1>", "arg1 desc")
+		opt.HelpSynopsisArg("<arg2>", "arg2 desc")
+		opt.HelpSynopsisArg("<arg3>", "arg3 desc")
+		opt.HelpCommand("help")
+		remaining, err := opt.Parse([]string{})
+		if err != nil {
+			t.Errorf("Unexpected error: %s", err)
+		}
+		err = opt.Dispatch(context.Background(), remaining)
+		if !errors.Is(err, getoptions.ErrorHelpCalled) {
+			t.Errorf("Unexpected error: %s", err)
+		}
+
+		expected := `ERROR: Missing <arg1>
+`
+		if helpBuf.String() != expected {
+			t.Errorf("Wrong output:\n%s\n", firstDiff(helpBuf.String(), expected))
+		}
+	})
+	t.Run("help section", func(t *testing.T) {
+		fn := func(ctx context.Context, opt *getoptions.GetOpt, args []string) error {
+			_, _, err := opt.GetRequiredArg(args, getoptions.HelpName, getoptions.HelpSynopsis)
+			if err != nil {
+				return err
+			}
+			return nil
+		}
+		helpBuf := new(bytes.Buffer)
+		getoptions.Writer = helpBuf
+		opt := getoptions.New()
+		opt.SetCommandFn(fn)
+		opt.HelpSynopsisArg("<arg1>", "arg1 desc")
+		opt.HelpSynopsisArg("<arg2>", "arg2 desc")
+		opt.HelpSynopsisArg("<arg3>", "arg3 desc")
+		opt.HelpCommand("help")
+		remaining, err := opt.Parse([]string{})
+		if err != nil {
+			t.Errorf("Unexpected error: %s", err)
+		}
+		err = opt.Dispatch(context.Background(), remaining)
+		if !errors.Is(err, getoptions.ErrorHelpCalled) {
+			t.Errorf("Unexpected error: %s", err)
+		}
+
+		expected := executable(`ERROR: Missing <arg1>
+NAME:
+    %s
+
+SYNOPSIS:
+    %[1]s [--help] <arg1> <arg2> <arg3>
+
+`)
+		if helpBuf.String() != expected {
+			t.Errorf("Wrong output:\n%s\n", firstDiff(helpBuf.String(), expected))
+		}
+	})
+}

text/variables.go

@@ -21,6 +21,10 @@ var ErrorAmbiguousArgument = "Ambiguous option '%s', matches %v!"
 // It has a string placeholder '%s' for the name of the missing option.
 var ErrorMissingRequiredOption = "Missing required parameter '%s'"
 
+var ErrorMissingRequiredArgument = "ERROR: Missing required argument"
+
+var ErrorMissingRequiredNamedArgument = "ERROR: Missing %s"
+
 // ErrorArgumentIsNotKeyValue holds the text for Map type options where the argument is not of key=value type.
 // It has a string placeholder '%s' for the name of the option missing the argument.
 var ErrorArgumentIsNotKeyValue = "Argument error for option '%s': Should be of type 'key=value'!"

user_help.go

@@ -13,7 +13,8 @@ type HelpSection int
 
 // Help Output Types
 const (
-	helpDefaultName HelpSection = iota
+	HelpNone HelpSection = iota
+	helpDefaultName
 	HelpName
 	HelpSynopsis
 	HelpCommandList