Print short script usage for '-h' (excluding global flags)

If you simply invoke rad on a script with -h, we'll give the 'short'
version of its usage, which is just that script's specific usage -- none
of the global rad arguments.

Also, while here, don't print a 'Script args' header if the script
doesn't have args -- oversight that's survived this far.

Author: amterp

core/funcs.go

@@ -1349,7 +1349,7 @@ func init() {
 			Execute: func(f FuncInvocationArgs) []RslValue {
 				// defaults
 				config := stid.NewConfig().
-					WithTickSize(stid.Decisecond).
+					WithTickSize(stid.Decisecond). // todo maybe milli, but reduce num random chars to 4?
 					WithNumRandomChars(5).
 					WithAlphabet(stid.Base62Alphabet)
 

core/printer.go

@@ -250,7 +250,7 @@ func (p *stdPrinter) RadErrorExit(msg string) {
 
 func (p *stdPrinter) UsageErrorExit(msg string) {
 	fmt.Fprint(p.stdErr, msg+"\n\n")
-	p.runner.RunUsage(true)
+	p.runner.RunUsage(false, true)
 	p.printShellExitIfEnabled()
 	p.errorExit(1)
 }

core/runner.go

@@ -123,7 +123,8 @@ func (r *RadRunner) Run() error {
 	// determine if we should run help/version or not
 
 	if FlagHelp.Value {
-		r.RunUsageExit()
+		shortHelp := !lo.Contains(os.Args[1:], "--help")
+		r.RunUsageExit(shortHelp)
 	}
 
 	if FlagVersion.Value {
@@ -143,7 +144,7 @@ func (r *RadRunner) Run() error {
 		}
 
 		// no flags, effectively, just print the basic usage
-		r.RunUsageExit()
+		r.RunUsageExit(false)
 	}
 
 	// from now on, assume we have a script name (or command)
@@ -227,7 +228,7 @@ func (r *RadRunner) Run() error {
 	if len(missingArgs) > 0 && len(args) == 0 && !atLeastOneFlagConfigured {
 		// if no args were passed but some are required, treat that as the user not really trying to use the script
 		// but instead just asking for help
-		r.RunUsageExit()
+		r.RunUsageExit(true)
 	}
 
 	// error if not all positional args were used
@@ -274,7 +275,7 @@ func (r *RadRunner) setUpGlobals() {
 	RFlagSet.ParseErrorsWhitelist.UnknownFlags = true
 
 	RFlagSet.Usage = func() {
-		r.RunUsage(false)
+		r.RunUsage(false, false)
 	}
 
 	r.globalFlags = CreateAndRegisterGlobalFlags()

core/runner_usage.go

@@ -7,16 +7,16 @@ import (
 	"strings"
 )
 
-func (r *RadRunner) RunUsage(isErr bool) {
+func (r *RadRunner) RunUsage(shortHelp, isErr bool) {
 	if r.scriptData == nil {
 		r.printScriptlessUsage(isErr)
 	} else {
-		r.printScriptUsage(isErr)
+		r.printScriptUsage(shortHelp, isErr)
 	}
 }
 
-func (r *RadRunner) RunUsageExit() {
-	r.RunUsage(false)
+func (r *RadRunner) RunUsageExit(shortHelp bool) {
+	r.RunUsage(shortHelp, false)
 	if FlagShell.Value {
 		RP.PrintForShellEval("exit 0")
 	}
@@ -45,7 +45,7 @@ func (r *RadRunner) printScriptlessUsage(isErr bool) {
 	r.printHelpFromBuffer(buf, isErr)
 }
 
-func (r *RadRunner) printScriptUsage(isErr bool) {
+func (r *RadRunner) printScriptUsage(shortHelp, isErr bool) {
 	buf := new(bytes.Buffer)
 
 	if r.scriptData.Description != nil {
@@ -70,16 +70,20 @@ func (r *RadRunner) printScriptUsage(isErr bool) {
 			com.CyanF(buf, fmt.Sprintf(" <%s>", arg.ApiName))
 		}
 	}
-	fmt.Fprintf(buf, "\n\n")
-
-	com.GreenBoldF(buf, "Script args:\n")
-	flagUsage(buf, r.scriptArgs)
 
 	fmt.Fprintf(buf, "\n")
 
-	// todo probably don't print these if there's a script? Or only minimal ones if --help is passed (not -h) ?
-	com.GreenBoldF(buf, "Global flags:\n")
-	flagUsage(buf, r.globalFlags)
+	if len(r.scriptArgs) > 0 {
+		fmt.Fprintf(buf, "\n")
+		com.GreenBoldF(buf, "Script args:\n")
+		flagUsage(buf, r.scriptArgs)
+	}
+
+	if !shortHelp {
+		fmt.Fprintf(buf, "\n")
+		com.GreenBoldF(buf, "Global flags:\n")
+		flagUsage(buf, r.globalFlags)
+	}
 
 	r.printHelpFromBuffer(buf, isErr)
 }

core/testing/args_test.go

@@ -28,8 +28,7 @@ func TestArgs_ApiRenameUsageString(t *testing.T) {
 
 Script args:
   -x, --bar string   
-
-` + scriptGlobalFlagHelp
+`
 	assertOnlyOutput(t, stdOutBuffer, expected)
 	assertNoErrors(t)
 }
@@ -47,8 +46,7 @@ args:
 Script args:
       --mandatory string   
       --optional int        (default 10)
-
-` + scriptGlobalFlagHelp
+`
 	assertOnlyOutput(t, stdOutBuffer, expected)
 	assertNoErrors(t)
 }
@@ -283,7 +281,23 @@ args:
 	assertError(t, 1, expected)
 }
 
-func TestArgs_Help(t *testing.T) {
+func TestArgs_FullHelp(t *testing.T) {
+	rsl := `
+args:
+	name string # The name.
+`
+	setupAndRunCode(t, rsl, "--help", "--color=never")
+	expected := `Usage:
+  <name>
+
+Script args:
+      --name string   The name.
+
+` + scriptGlobalFlagHelp
+	assertOnlyOutput(t, stdOutBuffer, expected)
+}
+
+func TestArgs_ShortHelp(t *testing.T) {
 	rsl := `
 args:
 	name string # The name.
@@ -294,6 +308,28 @@ args:
 
 Script args:
       --name string   The name.
+`
+	assertOnlyOutput(t, stdOutBuffer, expected)
+}
+
+func TestArgs_ShortHelpNoArgs(t *testing.T) {
+	rsl := `
+print("hi")
+`
+	setupAndRunCode(t, rsl, "-h", "--color=never")
+	expected := `Usage:
+ 
+`
+	assertOnlyOutput(t, stdOutBuffer, expected)
+}
+
+func TestArgs_FullHelpNoArgs(t *testing.T) {
+	rsl := `
+print("hi")
+`
+	setupAndRunCode(t, rsl, "--help", "--color=never")
+	expected := `Usage:
+ 
 
 ` + scriptGlobalFlagHelp
 	assertOnlyOutput(t, stdOutBuffer, expected)
@@ -324,8 +360,7 @@ Script args:
       --intArrayArg int,int             (default [2, 3])
       --floatArrayArg float,float       (default [2.1, 3.1])
       --boolArrayArg bool,bool          (default [true, false])
-
-` + scriptGlobalFlagHelp
+`
 	assertOnlyOutput(t, stdOutBuffer, expected)
 }
 

core/testing/file_header_test.go

@@ -18,8 +18,7 @@ Usage:
 
 Script args:
       --name string   
-
-` + scriptGlobalFlagHelp
+`
 	assertOnlyOutput(t, stdOutBuffer, expected)
 	assertNoErrors(t)
 }
@@ -46,8 +45,7 @@ Usage:
 
 Script args:
       --name string   
-
-` + scriptGlobalFlagHelp
+`
 	assertOnlyOutput(t, stdOutBuffer, expected)
 	assertNoErrors(t)
 }

core/testing/misc_test.go

@@ -127,7 +127,7 @@ func Test_Misc_CanShadowGlobalFlag(t *testing.T) {
 args:
 	src string
 `
-	setupAndRunCode(t, rsl, "--color=never", "-h")
+	setupAndRunCode(t, rsl, "--color=never", "--help")
 	expectedGlobalFlags := globalFlagHelpWithout("src")
 	expected := `Usage:
   <src>
@@ -145,7 +145,7 @@ func Test_Misc_CanShadowGlobalFlagThatHasShorthand(t *testing.T) {
 args:
 	debug string
 `
-	setupAndRunCode(t, rsl, "--color=never", "-h")
+	setupAndRunCode(t, rsl, "--color=never", "--help")
 	expectedGlobalFlags := `Global flags:
   -h, --help            Print usage string.
   -d                    Enables debug output. Intended for RSL script developers.
@@ -170,7 +170,7 @@ func Test_Misc_CanShadowGlobalShorthand(t *testing.T) {
 args:
 	myquiet q string
 `
-	setupAndRunCode(t, rsl, "--color=never", "-h")
+	setupAndRunCode(t, rsl, "--color=never", "--help")
 	expectedGlobalFlags := `Global flags:
   -h, --help            Print usage string.
   -d, --debug           Enables debug output. Intended for RSL script developers.
@@ -195,7 +195,7 @@ func Test_Misc_CanShadowGlobalFlagAndShorthand(t *testing.T) {
 args:
 	version v string
 `
-	setupAndRunCode(t, rsl, "--color=never", "-h")
+	setupAndRunCode(t, rsl, "--color=never", "--help")
 	expectedGlobalFlags := globalFlagHelpWithout("version")
 	expected := `Usage:
   <version>

core/version.go

@@ -1,6 +1,6 @@
 package core
 
 const (
-	Version = "0.5.30"
+	Version = "0.5.31"
 	// todo add in commit hash somehow?
 )

docs-web/docs/reference/functions.md

@@ -524,10 +524,10 @@ uuid_v7() -> string
 
 ### gen_stid
 
-Generate a random [Short Time ID](https://github.com/amterp/stid) (STID).
+Generate a random [short time ID](https://github.com/amterp/stid) (stid).
 
 ```rsl
-gen_stid(alphabet: string, time_granularity: int = 100, num_random_chars: int = 5) -> string
+gen_stid(alphabet: string, tick_size_ms: int = 100, num_random_chars: int = 5) -> string
 ```
 
 `alphabet` defaults to base-62 (`[0-9] [A-Z] [a-z]`).