Repository: rsteube/carapace
Pull request #818 (2023-07-14 20:07:10)

doc: simpler usage example


Patch:
diff --git a/docs/book.toml b/docs/book.toml
index 0b4d773..be67439 100644
--- a/docs/book.toml
+++ b/docs/book.toml
@@ -13,4 +13,4 @@ git-repository-url = "https://github.com/rsteube/carapace"
 edit-url-template = "https://github.com/rsteube/carapace/edit/master/docs/{path}"
 
 [output.linkcheck]
-follow-web-links = true
+follow-web-links = false
diff --git a/docs/src/carapace/action/usage.cast b/docs/src/carapace/action/usage.cast
index 2c0e374..9472f80 100644
--- a/docs/src/carapace/action/usage.cast
+++ b/docs/src/carapace/action/usage.cast
@@ -1,48 +1,43 @@
-{"version": 2, "width": 108, "height": 24, "timestamp": 1688570725, "env": {"SHELL": "elvish", "TERM": "tmux-256color"}}
-[0.077639, "o", "\u001b[1m\u001b[7m%\u001b[27m\u001b[1m\u001b[0m                                                                                                           \r \r"]
-[0.0935, "o", "\r\u001b[0m\u001b[27m\u001b[24m\u001b[J\r\n\u001b[1;36mcarapace\u001b[0m on \u001b[1;35m \u001b[0m\u001b[1;35mdoc-update\u001b[0m \u001b[1;31m[\u001b[0m\u001b[1;31m$\u001b[0m\u001b[1;31m!\u001b[0m\u001b[1;31m?\u001b[0m\u001b[1;31m]\u001b[0m via \u001b[1;36m🐹 \u001b[0m\u001b[1;36mv1.20.4\u001b[0m\u001b[1;36m \u001b[0m\r\n\u001b[1;37mzsh\u001b[0m \u001b[1;32m❯\u001b[0m \u001b[K\u001b[?2004h"]
-[1.10568, "o", "e"]
-[1.259408, "o", "\bex"]
-[1.436954, "o", "a"]
-[1.528555, "o", "m"]
-[1.775181, "o", "p"]
-[2.018019, "o", "l"]
-[2.137242, "o", "e"]
-[2.248635, "o", " "]
-[2.447993, "o", "m"]
-[2.534367, "o", "o"]
-[2.632755, "o", "d"]
-[2.842902, "o", "ifier "]
-[3.167879, "o", "-"]
-[3.33015, "o", "-"]
-[3.864969, "o", "u"]
-[3.926364, "o", "s"]
-[4.156021, "o", "age "]
-[4.60786, "o", "\u0007\r\r\n\u001b[2mUsage()\u001b[m\r\n\u001b[J\u001b[0m\u001b[mexplicit\u001b[0m  \u001b[J\u001b[mimplicit\u001b[0m\u001b[J\u001bM\u001bM\u001b[0m\u001b[27m\u001b[24m\r\u001b[6Cexample modifier --usage\u001b[K\u001b[1C"]
-[5.059838, "o", "explicit:\r\r\n\u001b[2mUsage()\u001b[m\u001b[K\u001b[K\r\n\u001b[J\u001b[7mexplicit\u001b[0m  \u001b[J\u001b[mimplicit\u001b[0m\u001b[J\u001bM\u001bM\u001b[0m\u001b[27m\u001b[24m\r\u001b[6Cexample modifier --usage explicit:\u001b[K"]
-[5.50293, "o", "\r\r\n\u001b[1B\u001b[7mexplicit\u001b[0m  \r\u001b[7mexplicit\u001b[0m  \r\u001bM\u001bM\u001b[0m\u001b[27m\u001b[24m\r\u001b[6Cexample modifier --usage explicit:\u001b[K\u001b[9Dim\u001b[7C"]
-[5.503272, "o", "\r\r\n\u001b[1B\u001b[10C\u001b[7mimplicit\u001b[0m\r\u001b[mexplicit\u001b[0m  \r\u001bM\u001bM\u001b[0m\u001b[27m\u001b[24m\r\u001b[6Cexample modifier --usage implicit:\u001b[K"]
-[5.856037, "o", "\r\r\n\u001b[J\u001bM\u001b[40C"]
-[6.080966, "o", "\u0007\r\r\n\u001b[J\u001b[J\u001b[2mUsage()\u001b[m\u001bM\u001b[0m\u001b[27m\u001b[24m\r\u001b[6Cexample modifier --usage implicit:\u001b[K"]
-[6.59112, "o", "\b \b"]
-[6.753252, "o", "\b \b"]
-[7.353479, "o", "\b \b"]
-[7.393543, "o", "\b \b"]
-[7.433772, "o", "\b \b"]
-[7.473486, "o", "\b \b"]
-[7.513593, "o", "\b \b"]
-[7.623915, "o", "\b \b"]
-[7.804521, "o", "\b \b"]
-[8.052794, "o", "\u0007\r\r\n\u001b[J\u001b[2mUsage()\u001b[m\r\n\u001b[J\u001b[0m\u001b[mexplicit\u001b[0m  \u001b[J\u001b[mimplicit\u001b[0m\u001b[J\u001bM\u001bM\u001b[0m\u001b[27m\u001b[24m\r\u001b[6Cexample modifier --usage\u001b[K\u001b[1C"]
-[8.696808, "o", "explicit:\r\r\n\u001b[2mUsage()\u001b[m\u001b[K\u001b[K\r\n\u001b[J\u001b[7mexplicit\u001b[0m  \u001b[J\u001b[mimplicit\u001b[0m\u001b[J\u001bM\u001bM\u001b[0m\u001b[27m\u001b[24m\r\u001b[6Cexample modifier --usage explicit:\u001b[K"]
-[8.927694, "o", "\r\r\n\u001b[1B\u001b[7mexplicit\u001b[0m  \r\u001b[7mexplicit\u001b[0m  \r\u001bM\u001bM\u001b[0m\u001b[27m\u001b[24m\r\u001b[6Cexample modifier --usage explicit:\u001b[K\r\r\n\u001b[J\u001bM\u001b[40C"]
-[9.33537, "o", "\u0007\r\r\n\u001b[J\u001b[J\u001b[2mexplicit usage\u001b[m\u001bM\u001b[0m\u001b[27m\u001b[24m\r\u001b[6C"]
-[9.335425, "o", "example modifier --usage explicit:\u001b[K"]
-[11.986459, "o", "\u001b[?2004l\r\r\n\u001b[J"]
-[11.986557, "o", "\u001b[1m\u001b[7m%\u001b[27m\u001b[1m\u001b[0m                                                                                                           \r \r"]
-[12.013627, "o", "\r\u001b[0m\u001b[27m\u001b[24m\u001b[J\r\n\u001b[1;36mcarapace\u001b[0m on \u001b[1;35m \u001b[0m\u001b[1;35mdoc-update\u001b[0m \u001b[1;31m[\u001b[0m\u001b[1;31m$\u001b[0m\u001b[1;31m!\u001b[0m\u001b[1;31m?\u001b[0m\u001b[1;31m]\u001b[0m via \u001b[1;36m🐹 \u001b[0m\u001b[1;36mv1.20.4\u001b[0m\u001b[1;36m \u001b[0m\r\n\u001b[1;37mzsh\u001b[0m \u001b[1;31m❯\u001b[0m \u001b[K\u001b[?2004h"]
-[12.473597, "o", "e"]
-[12.642813, "o", "\bex"]
-[12.79662, "o", "i"]
-[12.87228, "o", "t"]
-[13.000643, "o", "\u001b[?2004l\r\r\n"]
+{"version": 2, "width": 108, "height": 24, "timestamp": 1689365156, "env": {"SHELL": "elvish", "TERM": "tmux-256color"}}
+[0.083027, "o", "\u001b[?7h\u001b[7m⏎\u001b[m                                                                                                           \r \r\u001b[?7l\u001b[?2004h"]
+[0.08357, "o", "\u001b[?25l\r???>                                                                                                   ???> \r\u001b[5C\u001b[?25h\u001b[?25l\r\u001b[5C\u001b[K\r\u001b[5C\u001b[?25h"]
+[0.095309, "o", "\u001b[?25l\r\r\u001b[5C\u001b[?25h"]
+[0.095431, "o", "\u001b[?25l\r\u001b[K\r\n\u001b[0;1;36mcarapace/example\u001b[0;m on \u001b[0;1;35m master\u001b[0;m \u001b[0;1;31m[$!?]\u001b[0;m via \u001b[0;1;36m🐹 v1.20.5 \r\n\u001b[0;1;37mesh\u001b[0;m \u001b[0;1;32m❯\u001b[0;m \r\u001b[6C\u001b[?25h"]
+[0.266525, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[6C\u001b[0;31me\u001b[0;m\r\u001b[7C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[7C\u001b[?25h"]
+[0.266942, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[7C\u001b[?25h"]
+[0.284338, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[7C\u001b[?25h"]
+[0.284495, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[7C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[7C\u001b[?25h"]
+[0.470457, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[7C\u001b[0;31mx\u001b[0;m\r\u001b[8C\u001b[?25h"]
+[0.470724, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[8C\u001b[?25h"]
+[0.585879, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[6C\u001b[K\u001b[0;32mexa\u001b[0;m\r\u001b[9C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[9C\u001b[?25h"]
+[0.686349, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[6C\u001b[K\u001b[0;31mexam\u001b[0;m\r\u001b[10C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[10C\u001b[?25h"]
+[0.74574, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[10C\u001b[0;31mp\u001b[0;m\r\u001b[11C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[11C\u001b[?25h"]
+[0.874098, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[11C\u001b[0;31ml\u001b[0;m\r\u001b[12C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[12C\u001b[?25h"]
+[0.959794, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[6C\u001b[K\u001b[0;32mexample\u001b[0;m\r\u001b[13C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[13C\u001b[?25h"]
+[1.028051, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[13C \r\u001b[14C\u001b[?25h"]
+[1.028356, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[14C\u001b[?25h"]
+[1.029994, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[14C\u001b[?25h"]
+[1.030266, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[14C\u001b[?25h"]
+[1.593859, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[14Cm\r\u001b[15C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[15C\u001b[?25h"]
+[1.66983, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[15Co\r\u001b[16C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[16C\u001b[?25h"]
+[1.807487, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[16Cdifier \r\u001b[23C\u001b[?25h"]
+[2.089341, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[23C-\r\u001b[24C\u001b[?25h"]
+[2.234003, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[24C-\r\u001b[25C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[25C\u001b[?25h"]
+[2.393766, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[25Cu\r\u001b[26C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[26C\u001b[?25h"]
+[2.495365, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[23C\u001b[K\u001b[0;4m--uniquelist \r\n\u001b[0;1;37;45m COMPLETING argument \u001b[0;m \r\n\u001b[0;7;34m--uniquelist\u001b[0;2;7m (UniqueList())\u001b[0;m  \u001b[0;34m--usage\u001b[0;2m (Usage())\u001b[0;m\u001b[1A\r\u001b[22C\u001b[?25h"]
+[3.030474, "o", "\u001b[?25l\u001b[3A\r\r\n\r\n\u001b[26C\u001b[K\u001b[0;4msage \r\n\r\n\u001b[0;m\u001b[K\u001b[0;34m--uniquelist\u001b[0;2m (UniqueList())\u001b[0;m  \u001b[0;7;34m--usage\u001b[0;2;7m (Usage())\u001b[0;m\u001b[1A\r\u001b[22C\u001b[?25h"]
+[3.247828, "o", "\u001b[?25l\u001b[3A\r\r\n\r\n\u001b[23C\u001b[K--usage \r\n\u001b[J\u001b[A\r\u001b[31C\u001b[?25h"]
+[3.247934, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[31C\u001b[?25h"]
+[3.449224, "o", "\u001b[?25l\u001b[2A\r\u001b[0;2musage: \u001b[0;mexplicit usage\u001b[K\r\n\u001b[0;31merror:\u001b[0;m no candidates\u001b[K\r\n\u001b[K\r\n\u001b[K\u001b[0;1;36mcarapace/example\u001b[0;m on \u001b[0;1;35m master\u001b[0;m \u001b[0;1;31m[$!?]\u001b[0;m via \u001b[0;1;36m🐹 v1.20.5 \r\n\u001b[0;1;37mesh\u001b[0;m \u001b[0;1;32m❯\u001b[0;m \u001b[0;32mexample\u001b[0;m modifier --usage \r\u001b[31C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[31C\u001b[?25h"]
+[5.115699, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[6C\u001b[K\r\u001b[6C\u001b[?25h"]
+[5.116344, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
+[5.132634, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
+[5.132683, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
+[5.313226, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[6C\u001b[0;31me\u001b[0;m\r\u001b[7C\u001b[?25h"]
+[5.3137, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[7C\u001b[?25h"]
+[5.581167, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[7C\u001b[0;31mx\u001b[0;m\r\u001b[8C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[8C\u001b[?25h"]
+[5.767279, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[8C\u001b[0;31mi\u001b[0;m\r\u001b[9C\u001b[?25h"]
+[5.767387, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[9C\u001b[?25h"]
+[5.872712, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[6C\u001b[K\u001b[0;32mexit\u001b[0;m\r\u001b[10C\u001b[?25h"]
+[5.872799, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[10C\u001b[?25h"]
+[6.036772, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\n\r\u001b[?25h\u001b[?7h\u001b[?2004l\r"]
diff --git a/docs/src/carapace/action/usage.md b/docs/src/carapace/action/usage.md
index 91a40d8..86d2c92 100644
--- a/docs/src/carapace/action/usage.md
+++ b/docs/src/carapace/action/usage.md
@@ -3,21 +3,9 @@
 [`Usage`] sets the usage message.
 
 ```go
-carapace.ActionMultiParts(":", func(c carapace.Context) carapace.Action {
-	switch len(c.Parts) {
-	case 0:
-		return carapace.ActionValues("explicit", "implicit").Suffix(":")
-	case 1:
-		if c.Parts[0] == "explicit" {
-			return carapace.ActionValues().Usage("explicit usage")
-		}
-		return carapace.ActionValues()
-
-	default:
-		return carapace.ActionValues()
-	}
-})
+carapace.ActionValues().Usage("explicit usage")
 ````
+
 ![](./usage.cast)
 
 > It is implicitly set by default to [`Flag.Usage`] for flag and [`Command.Use`] for positional arguments.
diff --git a/example/cmd/modifier.go b/example/cmd/modifier.go
index 32d90df..94fe935 100644
--- a/example/cmd/modifier.go
+++ b/example/cmd/modifier.go
@@ -174,20 +174,7 @@ func init() {
 			}
 		}),
 		"uniquelist": carapace.ActionValues("one", "two", "three").UniqueList(","),
-		"usage": carapace.ActionMultiParts(":", func(c carapace.Context) carapace.Action {
-			switch len(c.Parts) {
-			case 0:
-				return carapace.ActionValues("explicit", "implicit").Suffix(":")
-			case 1:
-				if c.Parts[0] == "explicit" {
-					return carapace.ActionValues().Usage("explicit usage")
-				}
-				return carapace.ActionValues()
-
-			default:
-				return carapace.ActionValues()
-			}
-		}),
+		"usage":      carapace.ActionValues().Usage("explicit usage"),
 	})
 
 	carapace.Gen(modifierCmd).PositionalCompletion(


Test patch:
diff --git a/example/cmd/modifier_test.go b/example/cmd/modifier_test.go
index cdf7efd..1747b59 100644
--- a/example/cmd/modifier_test.go
+++ b/example/cmd/modifier_test.go
@@ -62,14 +62,7 @@ func TestTimeout(t *testing.T) {
 func TestUsage(t *testing.T) {
 	sandbox.Package(t, "github.com/rsteube/carapace/example")(func(s *sandbox.Sandbox) {
 		s.Run("modifier", "--usage", "").
-			Expect(carapace.ActionValues("explicit", "implicit").
-				Suffix(":").
-				NoSpace(':').
-				Usage("Usage()"))
-
-		s.Run("modifier", "--usage", "explicit:").
 			Expect(carapace.ActionValues().
-				NoSpace(':').
 				Usage("explicit usage"))
 	})
 }