Skip to content

Commit

Permalink
doc: updated action documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@rsteube
rsteube committed Jul 5, 2023
1 parent c92b881 commit 91135ef
Show file tree
Hide file tree
Showing 42 changed files with 1,564 additions and 164 deletions.
2 changes: 1 addition & 1 deletion action.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ func (a Action) Tag(tag string) Action {
// ActionValues("192.168.1.1", "127.0.0.1").TagF(func(value string) string {
// return "interfaces"
// })
func (a Action) TagF(f func(value string) string) Action {
func (a Action) TagF(f func(s string) string) Action {
return ActionCallback(func(c Context) Action {
invoked := a.Invoke(c)
for index, v := range invoked.rawValues {
Expand Down
46 changes: 28 additions & 18 deletions docs/src/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,29 +6,23 @@
- [PositionalCompletion](./carapace/gen/positionalCompletion.md)
- [FlagCompletion](./carapace/gen/flagCompletion.md)
- [DashCompletion](./carapace/gen/dashCompletion.md)
- [DefaultActions](./carapace/defaultActions.md)
- [ActionValues](./carapace/defaultActions/actionValues.md)
- [ActionValuesDescribed](./carapace/defaultActions/actionValuesDescribed.md)
- [ActionStyledValues](./carapace/defaultActions/actionStyledValues.md)
- [ActionStyledValuesDescribed](./carapace/defaultActions/actionStyledValuesDescribed.md)
- [ActionFiles](./carapace/defaultActions/actionFiles.md)
- [ActionDirectories](./carapace/defaultActions/actionDirectories.md)
- [ActionExecutables](./carapace/defaultActions/actionExecutables.md)
- [ActionMessage](./carapace/defaultActions/actionMessage.md)
- [ActionCallback](./carapace/defaultActions/actionCallback.md)
- [ActionMultiParts](./carapace/defaultActions/actionMultiParts.md)
- [ActionExecCommand](./carapace/defaultActions/actionExecCommand.md)
- [ActionExecute](./carapace/defaultActions/actionExecute.md)
- [ActionImport](./carapace/defaultActions/actionImport.md)
- [Action](./carapace/action.md)
- [Custom](./carapace/action/custom.md)
- [Chdir](./carapace/action/chDir.md)
- [Cache](./carapace/action/cache.md)
- [Chdir](./carapace/action/chdir.md)
- [Invoke](./carapace/action/invoke.md)
- [List](./carapace/action/list.md)
- [MultiParts](./carapace/action/multiParts.md)
- [NoSpace](./carapace/action/noSpace.md)
- [Suppress](./carapace/action/suppress.md)
- [Prefix](./carapace/action/prefix.md)
- [Style](./carapace/action/style.md)
- [StyleF](./carapace/action/styleF.md)
- [StyleR](./carapace/action/styleR.md)
- [Suffix](./carapace/action/suffix.md)
- [Suppress](./carapace/action/suppress.md)
- [Tag](./carapace/action/tag.md)
- [TagF](./carapace/action/tagF.md)
- [Timeout](./carapace/action/timeout.md)
- [UniqueList](./carapace/action/uniqueList.md)
- [Usage](./carapace/action/usage.md)
- [InvokedAction](./carapace/invokedAction.md)
- [Filter](./carapace/invokedAction/filter.md)
Expand All @@ -37,9 +31,25 @@
- [Suffix](./carapace/invokedAction/suffix.md)
- [ToA](./carapace/invokedAction/toA.md)
- [ToMultiPartsA](./carapace/invokedAction/toMultiPartsA.md)
- [DefaultActions](./carapace/defaultActions.md)
- [ActionValues](./carapace/defaultActions/actionValues.md)
- [ActionValuesDescribed](./carapace/defaultActions/actionValuesDescribed.md)
- [ActionStyledValues](./carapace/defaultActions/actionStyledValues.md)
- [ActionStyledValuesDescribed](./carapace/defaultActions/actionStyledValuesDescribed.md)
- [ActionFiles](./carapace/defaultActions/actionFiles.md)
- [ActionDirectories](./carapace/defaultActions/actionDirectories.md)
- [ActionExecutables](./carapace/defaultActions/actionExecutables.md)
- [ActionMessage](./carapace/defaultActions/actionMessage.md)
- [ActionCallback](./carapace/defaultActions/actionCallback.md)
- [ActionMultiParts](./carapace/defaultActions/actionMultiParts.md)
- [ActionExecCommand](./carapace/defaultActions/actionExecCommand.md)
- [ActionExecute](./carapace/defaultActions/actionExecute.md)
- [ActionImport](./carapace/defaultActions/actionImport.md)
- [CustomActions](./carapace/customActions.md)
- [Context](./carapace/context.md)
- [Batch](./carapace/batch.md)
- [Cache](./carapace/cache.md)
- [Export](./carapace/export.md)
- [Group](./carapace/group.md)
- [Standalone](./carapace/standalone.md)
- [caraparse](./carapace/standalone/caraparse.md)
- [pflag](./carapace/standalone/pflag.md)
Expand Down
168 changes: 168 additions & 0 deletions docs/src/carapace/action/cache-key.cast
View file

Large diffs are not rendered by default.

82 changes: 82 additions & 0 deletions docs/src/carapace/action/cache.cast
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
{"version": 2, "width": 108, "height": 24, "timestamp": 1688551063, "env": {"SHELL": "elvish", "TERM": "tmux-256color"}}
[0.055144, "o", "\u001b[?7h\u001b[7m⏎\u001b[m \r \r\u001b[?7l\u001b[?2004h"]
[0.055701, "o", "\u001b[?25l\r???> ???> \r\u001b[5C\u001b[?25h"]
[0.056095, "o", "\u001b[?25l\r\u001b[5C\u001b[K\r\u001b[5C\u001b[?25h"]
[0.064965, "o", "\u001b[?25l\r\r\u001b[5C\u001b[?25h"]
[0.065006, "o", "\u001b[?25l\r\u001b[K\r\n\u001b[0;1;36mcarapace\u001b[0;m on \u001b[0;1;35m doc-update\u001b[0;m \u001b[0;1;31m[$!?]\u001b[0;m via \u001b[0;1;36m🐹 v1.20.4 \r\n\u001b[0;1;37mesh\u001b[0;m \u001b[0;1;32m❯\u001b[0;m \r\u001b[6C\u001b[?25h"]
[1.015554, "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"]
[1.015982, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[7C\u001b[?25h"]
[1.027178, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[7C\u001b[?25h"]
[1.027313, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[7C\u001b[?25h"]
[1.247908, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[7C\u001b[0;31mx\u001b[0;m\r\u001b[8C\u001b[?25h"]
[1.39673, "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.527173, "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.615056, "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.729731, "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.84526, "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.845792, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[13C\u001b[?25h"]
[1.846099, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[13C\u001b[?25h"]
[1.847011, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[13C\u001b[?25h"]
[1.847779, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[13C\u001b[?25h"]
[1.94159, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[13C \r\u001b[14C\u001b[?25h"]
[2.55314, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[14C\u001b[0;4maction \r\n\u001b[0;1;37;45m COMPLETING argument \u001b[0;m \r\n\u001b[0;7;34maction\u001b[0;2;7m (action example) \r\n\u001b[0;34malias\u001b[0;2m (action example) \r\n\u001b[0;mcompletion\u001b[0;2m (Generate the autocompletion script for the specified shell)\r\n\u001b[0;34mflag\u001b[0;2m (flag example) \r\n\u001b[0;mhelp\u001b[0;2m (Help about any command) \r\n\u001b[0;35minjection\u001b[0;2m (just trying to break things) \r\n\u001b[0;33mmodifier\u001b[0;2m (modifier example) \r\n\u001b[0;mmultiparts\u001b[0;2m (multiparts example) \r\n\u001b[0;mspecial \u001b[9A\r\u001b[22C\u001b[?25h"]
[2.851885, "o", "\u001b[?25l\u001b[3A\r\r\n\r\n\r\n\u001b[22Cm\r\n\r\n\r\n\r\n\r\n\r\n\u001b[K\u001b[0;33mmodifier\u001b[0;2m (modifier example) \r\n\u001b[0;m\u001b[Kmultiparts\u001b[0;2m (multiparts example) \u001b[0;m\r\n\u001b[J\u001b[A\u001b[7A\r\u001b[23C\u001b[?25h"]
[2.853703, "o", "\u001b[?25l\u001b[3A\r\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\u001b[7A\r\u001b[23C\u001b[?25h"]
[2.901053, "o", "\u001b[?25l\u001b[3A\r\r\n\r\n\u001b[14C\u001b[K\u001b[0;4mmodifier \r\n\u001b[23C\u001b[0;mo\r\n\u001b[K\u001b[0;7;33mmodifier\u001b[0;2;7m (modifier example)\u001b[0;m\r\n\u001b[J\u001b[A\u001b[1A\r\u001b[24C\u001b[?25h"]
[3.539541, "o", "\u001b[?25l\u001b[3A\r\r\n\r\n\u001b[14C\u001b[Kmodifier \r\n\u001b[J\u001b[A\r\u001b[23C\u001b[?25h"]
[3.53962, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[23C\u001b[?25h"]
[3.820682, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[23C-\r\u001b[24C\u001b[?25h"]
[3.820772, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[24C\u001b[?25h"]
[3.978722, "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"]
[4.105482, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[23C\u001b[K\u001b[0;4m--batch \r\n\u001b[0;1;37;45m COMPLETING argument \u001b[0;m \r\n\u001b[0;7;34m--batch\u001b[0;2;7m (Batch()) \u001b[0;m \u001b[0;34m--persistentFlag2\u001b[0;2m (Help message for persistentFlag2)\r\n\u001b[0;34m--cache\u001b[0;2m (Cache()) \u001b[0;m \u001b[0;34m--timeout\u001b[0;2m (Timeout()) \r\n\u001b[0;34m--cache-key\u001b[0;2m (Cache()) \u001b[0;m \u001b[0;34m--tomultiparts\u001b[0;2m (ToMultiPartsA()) \r\n\u001b[0;m--help\u001b[0;2m (help for modifier) \u001b[0;m \u001b[0;34m--usage\u001b[0;2m (Usage()) \r\n\u001b[0;33m--persistentFlag\u001b[0;2m (Help message for persistentFlag)\u001b[0;m\u001b[5A\r\u001b[22C\u001b[?25h"]
[4.625278, "o", "\u001b[?25l\u001b[3A\r\r\n\r\n\r\n\u001b[22Cc\r\n\u001b[17C\u001b[K \u001b[0;34m--cache\u001b[0;2m (Cache())\u001b[0;m \u001b[0;34m--cache-key\u001b[0;2m (Cache())\u001b[0;m\r\n\u001b[J\u001b[A\u001b[1A\r\u001b[23C\u001b[?25h"]
[4.625395, "o", "\u001b[?25l\u001b[3A\r\r\n\r\n\r\n\r\n\u001b[1A\r\u001b[23C\u001b[?25h"]
[4.692309, "o", "\u001b[?25l\u001b[3A\r\r\n\r\n\u001b[25C\u001b[K\u001b[0;4mcache \r\n\u001b[23C\u001b[0;ma\r\n\u001b[2C\u001b[K\u001b[0;7;34mcache\u001b[0;2;7m (Cache())\u001b[0;m \u001b[0;34m--cache-key\u001b[0;2m (Cache())\u001b[0;m\u001b[1A\r\u001b[24C\u001b[?25h"]
[4.692635, "o", "\u001b[?25l\u001b[3A\r\r\n\r\n\r\n\r\n\u001b[1A\r\u001b[24C\u001b[?25h"]
[5.264578, "o", "\u001b[?25l\u001b[3A\r\r\n\r\n\u001b[23C\u001b[K--cache \r\n\u001b[J\u001b[A\r\u001b[31C\u001b[?25h"]
[5.265815, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[31C\u001b[?25h"]
[5.638732, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[31C11:57:49 \r\u001b[40C\u001b[?25h"]
[6.36486, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[39C\u001b[K\r\u001b[39C\u001b[?25h"]
[6.365533, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[39C\u001b[?25h"]
[6.365885, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[39C\u001b[?25h"]
[6.366533, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[39C\u001b[?25h"]
[6.366708, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[39C\u001b[?25h"]
[6.965124, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[38C\u001b[K\r\u001b[38C\u001b[?25h"]
[7.004251, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[37C\u001b[K\r\u001b[37C\u001b[?25h"]
[7.04417, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[36C\u001b[K\r\u001b[36C\u001b[?25h"]
[7.08354, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[35C\u001b[K\r\u001b[35C\u001b[?25h\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[35C\u001b[?25h"]
[7.236944, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[35C7:49 \r\u001b[40C\u001b[?25h"]
[7.74129, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[39C\u001b[K\r\u001b[39C\u001b[?25h"]
[8.341727, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[38C\u001b[K\r\u001b[38C\u001b[?25h"]
[8.381197, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[37C\u001b[K\r\u001b[37C\u001b[?25h"]
[8.421591, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[36C\u001b[K\r\u001b[36C\u001b[?25h"]
[8.421689, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[36C\u001b[?25h"]
[8.461716, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[35C\u001b[K\r\u001b[35C\u001b[?25h"]
[8.50113, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[34C\u001b[K\r\u001b[34C\u001b[?25h"]
[8.525937, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[34C57:49 \r\u001b[40C\u001b[?25h"]
[8.841861, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[39C\u001b[K\r\u001b[39C\u001b[?25h"]
[9.441847, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[38C\u001b[K\r\u001b[38C\u001b[?25h"]
[9.48161, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[37C\u001b[K\r\u001b[37C\u001b[?25h"]
[9.52198, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[36C\u001b[K\r\u001b[36C\u001b[?25h"]
[9.583079, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[36C:49 \r\u001b[40C\u001b[?25h"]
[9.998092, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[39C\u001b[K\r\u001b[39C\u001b[?25h"]
[10.597708, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[38C\u001b[K\r\u001b[38C\u001b[?25h"]
[10.637848, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[37C\u001b[K\r\u001b[37C\u001b[?25h"]
[10.677524, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[36C\u001b[K\r\u001b[36C\u001b[?25h"]
[10.717427, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[35C\u001b[K\r\u001b[35C\u001b[?25h"]
[10.743662, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[35C7:54 \r\u001b[40C\u001b[?25h"]
[13.380821, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[40C\u001b[?25h"]
[13.442623, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[6C\u001b[K\r\u001b[6C\u001b[?25h"]
[13.442693, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
[13.443907, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
[13.462229, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
[13.462434, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
[13.462523, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
[13.4628, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
[13.462828, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
[13.462893, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\u001b[6C\u001b[?25h"]
[13.914993, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[6C\u001b[0;31me\u001b[0;m\r\u001b[7C\u001b[?25h"]
[14.107927, "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"]
[14.238013, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\u001b[8C\u001b[0;31mi\u001b[0;m\r\u001b[9C\u001b[?25h"]
[14.338606, "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"]
[14.483371, "o", "\u001b[?25l\u001b[2A\r\r\n\r\n\r\n\r\u001b[?25h\u001b[?7h\u001b[?2004l\r"]
60 changes: 60 additions & 0 deletions docs/src/carapace/action/cache.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Cache

[`Cache`] caches an [Action] for a given duration.

```go
return carapace.ActionValues(
time.Now().Format("15:04:05"),
).Cache(5 * time.Second)
```

![](./cache.cast)

> Caches are implicitly assigned a unique key using [`runtime.Caller`] which can change between releases.

## Key

Additional keys like [`cache.String`] can be passed as well.

```go
carapace.ActionMultiParts("/", func(c carapace.Context) carapace.Action {
switch len(c.Parts) {
case 0:
return carapace.ActionValues("one", "two").Suffix("/")
case 1:
return carapace.ActionValues(
time.Now().Format("15:04:05"),
).Cache(10*time.Second, cache.String(c.Parts[0]))
default:
return carapace.ActionValues()
}
}),
```

![](./cache-key.cast)


## Location

Cache is written as `json` to [`os.UserCacheDir`] using the [Export] format.

```handlebars
{{cacheDir}}/carapace/{{binary}}/{{callerChecksum}}/{{cacheChecksum}}
```

| ID | x | example |
| ---- | --- | --- |
| cacheDir | os.UserCacheDir | `~/.cache/` |
| binary | binary name | `carapace` |
| callerChecksum | sha1sum using [`runtime.Caller`] | `89be88b670885d3d7855c7169ad7cfd2816a6c37` |
| cacheChecksum | sh1sum of given [`CacheKeys`] | `041858daaaa8b084122d4604a3223315c39edc3e` |

[Action]:../action.md
[`Cache`]:https://pkg.go.dev/github.com/rsteube/carapace#Action.Cache
[`cache.String`]:https://pkg.go.dev/github.com/rsteube/carapace/pkg/cache#String
[`CacheKeys`]:https://pkg.go.dev/github.com/rsteube/carapace/pkg/cache#CacheKey
[callback actions]:./defaultActions/actionCallback.md
[Export]:../export.md
[`os.UserCacheDir`]:https://pkg.go.dev/os#UserCacheDir
[`runtime.Caller`]:https://pkg.go.dev/runtime#Caller
Loading

0 comments on commit 91135ef

Please sign in to comment.