Merge pull request #209 from rsteube/update-example

updated example
carapace-sh · Sep 3, 2023 · ec91ac7 · ec91ac7
2 parents 845339f + a0b7221
commit ec91ac7
Show file tree

Hide file tree

Showing 19 changed files with 261 additions and 246 deletions.
diff --git a/action_test.go b/action_test.go
diff --git a/command_test.go b/command_test.go
@@ -9,26 +9,117 @@ import (
 	"github.com/rsteube/carapace/pkg/style"
 )
 
-//go:embed example/interspersed.yaml
-var interspersedSpec string
+//go:embed example/command.yaml
+var commandSpec string
 
-func TestInterspersed(t *testing.T) {
-	sandboxSpec(t, interspersedSpec)(func(s *sandbox.Sandbox) {
-		s.Run("--bool", "").
+func TestCommand(t *testing.T) {
+	sandboxSpec(t, commandSpec)(func(s *sandbox.Sandbox) {
+		s.Run("name").
 			Expect(carapace.ActionValues(
-				"four",
-				"five",
-				"six",
+				"name",
+			).Tag("commands"))
+
+		s.Run("name", "").
+			Expect(carapace.ActionValues().
+				Usage("name [value]"))
+
+		s.Run("description").
+			Expect(carapace.ActionValuesDescribed(
+				"description", "with description",
+			).Tag("commands"))
+
+		s.Run("a").
+			Expect(carapace.ActionValues(
+				"a",
+				"al",
+				"aliases",
+			).Tag("commands"))
+
+		s.Run("hidden").
+			Expect(carapace.ActionValues())
+
+		s.Run("hidden", "").
+			Expect(carapace.ActionValues(
+				"p1",
+				"positional1",
+			))
+
+		s.Run("parsing", "interspersed", "--bool", "").
+			Expect(carapace.ActionValues(
+				"p1",
+				"positional1",
 			))
 
-		s.Run("--bool", "-").
+		s.Run("parsing", "interspersed", "--bool", "p1", "--").
 			Expect(carapace.ActionStyledValuesDescribed(
 				"--string", "string flag", style.Blue,
 			).NoSpace('.').
 				Tag("flags"))
 
-		s.Run("--bool", "four", "-").
+		s.Run("parsing", "interspersed", "--bool", "p1", "--string", "").
+			Expect(carapace.ActionValues(
+				"s1",
+				"s2",
+				"s3",
+			).Usage("string flag"))
+
+		s.Run("parsing", "interspersed", "--bool", "p1", "--string", "s1", "--", "").
+			Expect(carapace.ActionValues(
+				"d1",
+				"dash1",
+			))
+
+		s.Run("parsing", "non-interspersed", "--bool", "p1", "--").
+			Expect(carapace.ActionValues())
+
+		s.Run("parsing", "disabled", "--").
 			Expect(carapace.ActionValues())
 
+		s.Run("flags", "--").
+			Expect(carapace.ActionStyledValuesDescribed(
+				"--bool", "bool flag", style.Default,
+				"--string", "string flag", style.Blue,
+			).NoSpace('.').
+				Tag("flags"))
+
+		s.Run("persistentflags", "--").
+			Expect(carapace.ActionStyledValuesDescribed(
+				"--bool", "bool flag", style.Default,
+				"--string", "string flag", style.Blue,
+			).NoSpace('.').
+				Tag("flags"))
+
+		s.Run("persistentflags", "subcommand", "--").
+			Expect(carapace.ActionStyledValuesDescribed(
+				"--bool", "bool flag", style.Default,
+				"--string", "string flag", style.Blue,
+			).NoSpace('.').
+				Tag("flags"))
+
+		s.Run("persistentflags", "--bool", "subcommand", "--").
+			Expect(carapace.ActionStyledValuesDescribed(
+				"--string", "string flag", style.Blue,
+			).NoSpace('.').
+				Tag("flags"))
+
+		s.Run("exclusiveflags", "--").
+			Expect(carapace.ActionStyledValuesDescribed(
+				"--bool", "bool flag", style.Default,
+				"--string", "string flag", style.Blue,
+			).NoSpace('.').
+				Tag("flags"))
+
+		s.Run("exclusiveflags", "--bool", "--").
+			Expect(carapace.ActionValues().
+				NoSpace('.').
+				Tag("flags"))
+
+		s.Run("run", "shell", "--color=").
+			Expect(carapace.ActionValues(
+				"always",
+				"auto",
+				"never",
+			).Prefix("--color=").
+				Usage("colored diff"))
 	})
 }
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -3,14 +3,23 @@
 - [carapace-spec](./carapace-spec.md)
   - [Usage](./carapace-spec/usage.md)
   - [Command](./carapace-spec/command.md)
+    - [Name](./carapace-spec/command/name.md)
+    - [Aliases](./carapace-spec/command/aliases.md)
+    - [Description](./carapace-spec/command/description.md)
+    - [Group](./carapace-spec/command/group.md)
+    - [Hidden](./carapace-spec/command/hidden.md)
+    - [Parsing](./carapace-spec/command/parsing.md)
     - [Flags](./carapace-spec/command/flags.md)
     - [PersistentFlags](./carapace-spec/command/persistentFlags.md)
+    - [ExclusiveFlags](./carapace-spec/command/exclusiveFlags.md)
+    - [Run](./carapace-spec/command/run.md)
     - [Completion](./carapace-spec/command/completion.md)
       - [Flag](./carapace-spec/command/completion/flag.md)
       - [Positional](./carapace-spec/command/completion/positional.md)
       - [PositionalAny](./carapace-spec/command/completion/positionalAny.md)
       - [Dash](./carapace-spec/command/completion/dash.md)
       - [DashAny](./carapace-spec/command/completion/dashAny.md)
+    - [Commands](./carapace-spec/command/commands.md)
   - [Values](./carapace-spec/values.md)
   - [Macros](./carapace-spec/macros.md)
     - [Core](./carapace-spec/macros/core.md)

diff --git a/docs/src/carapace-spec/command.md b/docs/src/carapace-spec/command.md
@@ -7,8 +7,11 @@ type Command struct {
 	Description     string
 	Group           string
 	Hidden          bool
+	Parsing         string
 	Flags           map[string]string
 	PersistentFlags map[string]string
+	ExclusiveFlags  [][]string
+	Run             string
 	Completion      struct {
 		Flag          map[string][]string
 		Positional    [][]string

diff --git a/docs/src/carapace-spec/command/aliases.md b/docs/src/carapace-spec/command/aliases.md
@@ -0,0 +1,7 @@
+# Aliases
+
+Aliases of the command.
+
+```yaml
+aliases: [l, ls]
+```
diff --git a/docs/src/carapace-spec/command/commands.md b/docs/src/carapace-spec/command/commands.md
@@ -0,0 +1 @@
+# Commands
diff --git a/docs/src/carapace-spec/command/description.md b/docs/src/carapace-spec/command/description.md
@@ -0,0 +1,7 @@
+# Description
+
+Description of the command.
+
+```yaml
+description: example description
+```
diff --git a/docs/src/carapace-spec/command/exclusiveFlags.md b/docs/src/carapace-spec/command/exclusiveFlags.md
@@ -0,0 +1 @@
+# ExclusiveFlags
diff --git a/docs/src/carapace-spec/command/group.md b/docs/src/carapace-spec/command/group.md
@@ -0,0 +1,9 @@
+# Group
+
+[Group] of the command.
+
+```yaml
+group: core
+```
+
+[Group]:https://rsteube.github.io/carapace/carapace/command/group.html
diff --git a/docs/src/carapace-spec/command/hidden.md b/docs/src/carapace-spec/command/hidden.md
@@ -0,0 +1,7 @@
+# Hidden
+
+Whether to hide the command during subcommand completion.
+
+```yaml
+hidden: true
+```
diff --git a/docs/src/carapace-spec/command/name.md b/docs/src/carapace-spec/command/name.md
@@ -0,0 +1,13 @@
+# Name
+
+Name of the command.
+
+```yaml
+name: add
+```
+
+It can also contain the one-line [usage](https://rsteube.github.io/carapace/carapace/action/usage.html) message.
+
+```yaml
+name: add [-F file | -D dir]... [-f format] profile
+```
diff --git a/docs/src/carapace-spec/command/parsing.md b/docs/src/carapace-spec/command/parsing.md
@@ -0,0 +1,8 @@
+# Parsing
+
+Sets flag parsing mode. One of:
+
+- `<unset>` interspersed but allows implicit changes
+- `interspersed` mixed flags and positional arguments
+- `non-interspersed` flag parsing stopped after first positional argument
+- `disabled` flag parsing disabled
diff --git a/docs/src/carapace-spec/command/run.md b/docs/src/carapace-spec/command/run.md
@@ -0,0 +1 @@
+# Run
diff --git a/example/command.yaml b/example/command.yaml
@@ -0,0 +1,94 @@
+name: command
+commands:
+- name: name [value]
+
+- name: description
+  description: with description
+
+- name: aliases
+  aliases: [a, al]
+
+- name: hidden
+  hidden: true
+  completion:
+    positional:
+    - [p1, positional1]
+
+- name: parsing
+  commands:
+  - name: interspersed
+    parsing: interspersed
+    flags:
+      --bool: bool flag
+      --string=: string flag
+    completion:
+      flag:
+        string: [s1, s2, s3]
+      positional:
+      - [p1, positional1]
+      dash:
+      - [d1, dash1]
+
+  - name: non-interspersed
+    parsing: non-interspersed
+    flags:
+      --bool: bool flag
+      --string=: string flag
+    completion:
+      flag:
+        string: [s1, s2, s3]
+      positional:
+      - [p1, positional1]
+
+  - name: disabled
+    parsing: disabled
+    flags:
+      --bool: bool flag
+      --string=: string flag
+    completion:
+      flag:
+        string: [s1, s2, s3]
+      positional:
+      - [p1, positional1]
+
+- name: flags
+  flags:
+    --bool: bool flag
+    --string=: string flag
+  completion:
+    flag:
+      string: [s1, s2, s3]
+
+- name: persistentflags
+  persistentflags:
+    --bool: bool flag
+    --string=: string flag
+  completion:
+    flag:
+      string: [s1, s2, s3]
+  commands:
+  - name: subcommand
+
+- name: exclusiveflags
+  flags:
+    --bool: bool flag
+    --string=: string flag
+  exclusiveflags:
+  - [bool, string]
+  completion:
+    flag:
+      string: [s1, s2, s3]
+
+- name: run
+  commands:
+  - name: alias
+    run: "[git, log]"
+  - name: shell
+    run: "$(git log --color=${C_FLAG_COLOR:-auto} $@)"
+    flags:
+      --color?: colored diff
+    completion:
+      flag:
+        color: [always, auto, never]
+      positional:
+      -  [master]