action: added Retain

exposed filter
carapace-sh · Jul 12, 2023 · 3f79509 · 3f79509
1 parent c4e3e3a
commit 3f79509
Show file tree

Hide file tree

Showing 10 changed files with 277 additions and 85 deletions.
diff --git a/action.go b/action.go
@@ -52,6 +52,32 @@ func (a Action) Cache(timeout time.Duration, keys ...pkgcache.Key) Action {
 	return a
 }
 
+// Chdir changes the current working directory to the named directory for the duration of invocation.
+func (a Action) Chdir(dir string) Action {
+	return ActionCallback(func(c Context) Action {
+		abs, err := c.Abs(dir)
+		if err != nil {
+			return ActionMessage(err.Error())
+		}
+		if info, err := os.Stat(abs); err != nil {
+			return ActionMessage(err.Error())
+		} else if !info.IsDir() {
+			return ActionMessage("not a directory: %v", abs)
+		}
+		c.Dir = abs
+		return a.Invoke(c).ToA()
+	})
+}
+
+// Filter filters given values.
+//
+//	carapace.ActionValues("A", "B", "C").Filter([]string{"B"}) // ["A", "C"]
+func (a Action) Filter(values []string) Action {
+	return ActionCallback(func(c Context) Action {
+		return a.Invoke(c).Filter(values).ToA()
+	})
+}
+
 // Invoke executes the callback of an action if it exists (supports nesting).
 func (a Action) Invoke(c Context) InvokedAction {
 	if c.Args == nil {
@@ -72,6 +98,20 @@ func (a Action) Invoke(c Context) InvokedAction {
 	return InvokedAction{a}
 }
 
+// List wraps the Action in an ActionMultiParts with given divider.
+func (a Action) List(divider string) Action {
+	return ActionMultiParts(divider, func(c Context) Action {
+		return a.Invoke(c).ToA().NoSpace()
+	})
+}
+
+// MultiParts splits values of an Action by given dividers and completes each segment separately.
+func (a Action) MultiParts(dividers ...string) Action {
+	return ActionCallback(func(c Context) Action {
+		return a.Invoke(c).ToMultiPartsA(dividers...)
+	})
+}
+
 // NoSpace disables space suffix for given characters (or all if none are given).
 func (a Action) NoSpace(suffixes ...rune) Action {
 	return ActionCallback(func(c Context) Action {
@@ -83,20 +123,21 @@ func (a Action) NoSpace(suffixes ...rune) Action {
 	})
 }
 
-// Usage sets the usage.
-func (a Action) Usage(usage string, args ...interface{}) Action {
-	return a.UsageF(func() string {
-		return fmt.Sprintf(usage, args...)
+// Prefix adds a prefix to values (only the ones inserted, not the display values).
+//
+//	carapace.ActionValues("melon", "drop", "fall").Prefix("water")
+func (a Action) Prefix(prefix string) Action {
+	return ActionCallback(func(c Context) Action {
+		return a.Invoke(c).Prefix(prefix).ToA()
 	})
 }
 
-// Usage sets the usage using a function.
-func (a Action) UsageF(f func() string) Action {
+// Retain retains given values.
+//
+//	carapace.ActionValues("A", "B", "C").Retain([]string{"A", "C"}) // ["A", "C"]
+func (a Action) Retain(values []string) Action {
 	return ActionCallback(func(c Context) Action {
-		if usage := f(); usage != "" {
-			a.meta.Usage = usage
-		}
-		return a
+		return a.Invoke(c).Retain(values).ToA()
 	})
 }
 
@@ -110,6 +151,20 @@ func (a Action) Style(s string) Action {
 	})
 }
 
+// Style sets the style using a function.
+//
+//	ActionValues("dir/", "test.txt").StyleF(style.ForPathExt)
+//	ActionValues("true", "false").StyleF(style.ForKeyword)
+func (a Action) StyleF(f func(s string, sc style.Context) string) Action {
+	return ActionCallback(func(c Context) Action {
+		invoked := a.Invoke(c)
+		for index, v := range invoked.rawValues {
+			invoked.rawValues[index].Style = f(v.Value, c)
+		}
+		return invoked.ToA()
+	})
+}
+
 // Style sets the style using a reference.
 //
 //	ActionValues("value").StyleR(&style.Carapace.Value)
@@ -123,15 +178,21 @@ func (a Action) StyleR(s *string) Action {
 	})
 }
 
-// Style sets the style using a function.
+// Suffix adds a suffx to values (only the ones inserted, not the display values).
 //
-//	ActionValues("dir/", "test.txt").StyleF(style.ForPathExt)
-//	ActionValues("true", "false").StyleF(style.ForKeyword)
-func (a Action) StyleF(f func(s string, sc style.Context) string) Action {
+//	carapace.ActionValues("apple", "melon", "orange").Suffix("juice")
+func (a Action) Suffix(suffix string) Action {
+	return ActionCallback(func(c Context) Action {
+		return a.Invoke(c).Suffix(suffix).ToA()
+	})
+}
+
+// Suppress suppresses specific error messages using regular expressions.
+func (a Action) Suppress(expr ...string) Action {
 	return ActionCallback(func(c Context) Action {
 		invoked := a.Invoke(c)
-		for index, v := range invoked.rawValues {
-			invoked.rawValues[index].Style = f(v.Value, c)
+		if err := invoked.meta.Messages.Suppress(expr...); err != nil {
+			return ActionMessage(err.Error())
 		}
 		return invoked.ToA()
 	})
@@ -161,73 +222,6 @@ func (a Action) TagF(f func(s string) string) Action {
 	})
 }
 
-// Chdir changes the current working directory to the named directory for the duration of invocation.
-func (a Action) Chdir(dir string) Action {
-	return ActionCallback(func(c Context) Action {
-		abs, err := c.Abs(dir)
-		if err != nil {
-			return ActionMessage(err.Error())
-		}
-		if info, err := os.Stat(abs); err != nil {
-			return ActionMessage(err.Error())
-		} else if !info.IsDir() {
-			return ActionMessage("not a directory: %v", abs)
-		}
-		c.Dir = abs
-		return a.Invoke(c).ToA()
-	})
-}
-
-// Suppress suppresses specific error messages using regular expressions.
-func (a Action) Suppress(expr ...string) Action {
-	return ActionCallback(func(c Context) Action {
-		invoked := a.Invoke(c)
-		if err := invoked.meta.Messages.Suppress(expr...); err != nil {
-			return ActionMessage(err.Error())
-		}
-		return invoked.ToA()
-	})
-}
-
-// MultiParts splits values of an Action by given dividers and completes each segment separately.
-func (a Action) MultiParts(dividers ...string) Action {
-	return ActionCallback(func(c Context) Action {
-		return a.Invoke(c).ToMultiPartsA(dividers...)
-	})
-}
-
-// List wraps the Action in an ActionMultiParts with given divider.
-func (a Action) List(divider string) Action {
-	return ActionMultiParts(divider, func(c Context) Action {
-		return a.Invoke(c).ToA().NoSpace()
-	})
-}
-
-// UniqueList wraps the Action in an ActionMultiParts with given divider.
-func (a Action) UniqueList(divider string) Action {
-	return ActionMultiParts(divider, func(c Context) Action {
-		return a.Invoke(c).Filter(c.Parts).ToA().NoSpace()
-	})
-}
-
-// Prefix adds a prefix to values (only the ones inserted, not the display values).
-//
-//	carapace.ActionValues("melon", "drop", "fall").Prefix("water")
-func (a Action) Prefix(prefix string) Action {
-	return ActionCallback(func(c Context) Action {
-		return a.Invoke(c).Prefix(prefix).ToA()
-	})
-}
-
-// Suffix adds a suffx to values (only the ones inserted, not the display values).
-//
-//	carapace.ActionValues("apple", "melon", "orange").Suffix("juice")
-func (a Action) Suffix(suffix string) Action {
-	return ActionCallback(func(c Context) Action {
-		return a.Invoke(c).Suffix(suffix).ToA()
-	})
-}
-
 // Timeout sets the maximum duration an Action may take to invoke.
 //
 //	carapace.ActionCallback(func(c carapace.Context) carapace.Action {
@@ -252,3 +246,27 @@ func (a Action) Timeout(d time.Duration, alternative Action) Action {
 		return result.ToA()
 	})
 }
+
+// UniqueList wraps the Action in an ActionMultiParts with given divider.
+func (a Action) UniqueList(divider string) Action {
+	return ActionMultiParts(divider, func(c Context) Action {
+		return a.Invoke(c).Filter(c.Parts).ToA().NoSpace()
+	})
+}
+
+// Usage sets the usage.
+func (a Action) Usage(usage string, args ...interface{}) Action {
+	return a.UsageF(func() string {
+		return fmt.Sprintf(usage, args...)
+	})
+}
+
+// Usage sets the usage using a function.
+func (a Action) UsageF(f func() string) Action {
+	return ActionCallback(func(c Context) Action {
+		if usage := f(); usage != "" {
+			a.meta.Usage = usage
+		}
+		return a
+	})
+}
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -9,11 +9,13 @@
   - [Action](./carapace/action.md)
     - [Cache](./carapace/action/cache.md)
     - [Chdir](./carapace/action/chdir.md)
+    - [Filter](./carapace/action/filter.md)
     - [Invoke](./carapace/action/invoke.md)
     - [List](./carapace/action/list.md)
     - [MultiParts](./carapace/action/multiParts.md)
     - [NoSpace](./carapace/action/noSpace.md)
     - [Prefix](./carapace/action/prefix.md)
+    - [Retain](./carapace/action/retain.md)
     - [Style](./carapace/action/style.md)
     - [StyleF](./carapace/action/styleF.md)
     - [StyleR](./carapace/action/styleR.md)

diff --git a/docs/src/carapace/action/filter.cast b/docs/src/carapace/action/filter.cast
@@ -0,0 +1,41 @@
+{"version": 2, "width": 108, "height": 24, "timestamp": 1689158161, "env": {"SHELL": "elvish", "TERM": "tmux-256color"}}
+[0.065171, "o", "\u001b[?7h\u001b[7m⏎\u001b[m                                                                                                           \r \r\u001b[?7l\u001b[?2004h"]
+[0.065792, "o", "\u001b[?25l\r???>                                                                                                   ???> \r\u001b[5C\u001b[?25h\u001b[?25l\r\u001b[5C\u001b[K\r\u001b[5C\u001b[?25h"]
+[0.074083, "o", "\u001b[?25l\r\r\u001b[5C\u001b[?25h"]
+[0.074275, "o", "\u001b[?25l\r\u001b[K\r\n\u001b[0;1;36mcarapace/example\u001b[0;m on \u001b[0;1;35m action-retain\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.587118, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[6C\u001b[0;31me\u001b[0;m\r\u001b[7C\u001b[?25h"]
+[0.587557, "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.600157, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[7C\u001b[?25h"]
+[0.600276, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[7C\u001b[?25h"]
+[0.769978, "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"]
+[0.906975, "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"]
+[1.008014, "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"]
+[1.06184, "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"]
+[1.198941, "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"]
+[1.263944, "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.328305, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[13C \r\u001b[14C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[14C\u001b[?25h"]
+[1.48774, "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.573788, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[15Co\r\u001b[16C\u001b[?25h"]
+[1.573866, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[16C\u001b[?25h"]
+[1.575372, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[16C\u001b[?25h"]
+[1.575431, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[16C\u001b[?25h"]
+[1.694119, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[16Cdifier \r\u001b[23C\u001b[?25h"]
+[2.106809, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[23C-\r\u001b[24C\u001b[?25h"]
+[2.106893, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[24C\u001b[?25h"]
+[2.262227, "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.516307, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[25Cf\r\u001b[26C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[26C\u001b[?25h"]
+[2.642845, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[26Ci\r\u001b[27C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[27C\u001b[?25h"]
+[2.824332, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[27Clter \r\u001b[32C\u001b[?25h"]
+[3.289998, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[32C\u001b[0;4m1 \r\n\u001b[0;1;37;45m COMPLETING argument \u001b[0;m \r\n\u001b[0;7m1\u001b[0;2;7m (one)\u001b[0;m  3\u001b[0;2m (three)\u001b[0;m\u001b[1A\r\u001b[22C\u001b[?25h"]
+[4.228643, "o", "\u001b[?25l\u001b[3A\r\r\n\r\n\u001b[32C\u001b[K\u001b[0;4m3 \r\n\r\n\u001b[0;m\u001b[K1\u001b[0;2m (one)\u001b[0;m  \u001b[0;7m3\u001b[0;2;7m (three)\u001b[0;m\u001b[1A\r\u001b[22C\u001b[?25h"]
+[5.733904, "o", "\u001b[?25l\u001b[3A\r\r\n\r\n\u001b[6C\u001b[K\r\n\u001b[J\u001b[A\r\u001b[6C\u001b[?25h"]
+[5.734661, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
+[5.752609, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
+[5.752756, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
+[5.969899, "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"]
+[6.212241, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[7C\u001b[0;31mx\u001b[0;m\r\u001b[8C\u001b[?25h"]
+[6.212335, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[8C\u001b[?25h"]
+[6.3745, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[8C\u001b[0;31mi\u001b[0;m\r\u001b[9C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[9C\u001b[?25h"]
+[6.445559, "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\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[10C\u001b[?25h"]
+[6.624242, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\n\r\u001b[?25h"]
+[6.624648, "o", "\u001b[?7h\u001b[?2004l\r"]
diff --git a/docs/src/carapace/action/filter.md b/docs/src/carapace/action/filter.md
@@ -0,0 +1,16 @@
+# Filter
+
+[`Filter`] filters given values.
+
+```go
+carapace.ActionValuesDescribed(
+	"1", "one",
+	"2", "two",
+	"3", "three",
+	"4", "four",
+).Filter([]string{"2", "4"})
+```
+
+![](./filter.cast)
+
+[`Filter`]: https://pkg.go.dev/github.com/rsteube/carapace#Action.Filter
diff --git a/docs/src/carapace/action/retain.cast b/docs/src/carapace/action/retain.cast
@@ -0,0 +1,41 @@
+{"version": 2, "width": 108, "height": 24, "timestamp": 1689158181, "env": {"SHELL": "elvish", "TERM": "tmux-256color"}}
+[0.070882, "o", "\u001b[?7h\u001b[7m⏎\u001b[m                                                                                                           \r \r\u001b[?7l\u001b[?2004h"]
+[0.071423, "o", "\u001b[?25l\r???>                                                                                                   ???> \r\u001b[5C\u001b[?25h\u001b[?25l\r\u001b[5C\u001b[K\r\u001b[5C\u001b[?25h"]
+[0.083515, "o", "\u001b[?25l\r\r\u001b[5C\u001b[?25h"]
+[0.083754, "o", "\u001b[?25l\r\u001b[K\r\n\u001b[0;1;36mcarapace/example\u001b[0;m on \u001b[0;1;35m action-retain\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.412814, "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.41334, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[7C\u001b[?25h"]
+[0.423245, "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.588142, "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"]
+[0.735276, "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"]
+[0.735347, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[9C\u001b[?25h"]
+[0.837106, "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.876364, "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"]
+[1.038023, "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"]
+[1.106702, "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"]
+[1.106807, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[13C\u001b[?25h"]
+[1.204027, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[13C \r\u001b[14C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[14C\u001b[?25h"]
+[1.343381, "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.410835, "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.551868, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[16Cdifier \r\u001b[23C\u001b[?25h"]
+[1.919688, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[23C-\r\u001b[24C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[24C\u001b[?25h"]
+[2.053776, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[24C-\r\u001b[25C\u001b[?25h"]
+[2.053872, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[25C\u001b[?25h"]
+[2.378561, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[25Cr\r\u001b[26C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[26C\u001b[?25h"]
+[2.466607, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[26Ce\r\u001b[27C\u001b[?25h"]
+[2.466684, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[27C\u001b[?25h"]
+[2.656245, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[27Ctain \r\u001b[32C\u001b[?25h"]
+[3.133397, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[32C\u001b[0;4m2 \r\n\u001b[0;1;37;45m COMPLETING argument \u001b[0;m \r\n\u001b[0;7m2\u001b[0;2;7m (two)\u001b[0;m  4\u001b[0;2m (four)\u001b[0;m\u001b[1A\r\u001b[22C\u001b[?25h"]
+[3.774198, "o", "\u001b[?25l\u001b[3A\r\r\n\r\n\u001b[32C\u001b[K\u001b[0;4m4 \r\n\r\n\u001b[0;m\u001b[K2\u001b[0;2m (two)\u001b[0;m  \u001b[0;7m4\u001b[0;2;7m (four)\u001b[0;m\u001b[1A\r\u001b[22C\u001b[?25h"]
+[5.468723, "o", "\u001b[?25l\u001b[3A\r\r\n\r\n\u001b[6C\u001b[K\r\n\u001b[J\u001b[A\r\u001b[6C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
+[5.469673, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
+[5.486014, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
+[5.48608, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
+[5.740105, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[6C\u001b[0;31me\u001b[0;m\r\u001b[7C\u001b[?25h"]
+[5.740396, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[7C\u001b[?25h"]
+[5.943355, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[7C\u001b[0;31mx\u001b[0;m\r\u001b[8C\u001b[?25h"]
+[5.94357, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[8C\u001b[?25h"]
+[6.054215, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[8C\u001b[0;31mi\u001b[0;m\r\u001b[9C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[9C\u001b[?25h"]
+[6.180112, "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"]
+[6.180364, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[10C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[10C\u001b[?25h"]
+[6.333115, "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/retain.md b/docs/src/carapace/action/retain.md
@@ -0,0 +1,16 @@
+# Retain
+
+[`Retain`] retains given values.
+
+```go
+carapace.ActionValuesDescribed(
+	"1", "one",
+	"2", "two",
+	"3", "three",
+	"4", "four",
+).Retain([]string{"2", "4"})
+```
+
+![](./retain.cast)
+
+[`Retain`]: https://pkg.go.dev/github.com/rsteube/carapace#Action.Retain