From 42f9ce67e6d4fad4ec8dd6a72e6b2c980fbf1401 Mon Sep 17 00:00:00 2001
From: rsteube <rsteube@users.noreply.github.com>
Date: Tue, 17 Mar 2020 16:40:10 +0100
Subject: [PATCH] updated circleci, readded README

partly updated README content
---
 .circleci/config.yml |   5 +-
 README.md            | 132 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 135 insertions(+), 2 deletions(-)
 create mode 100644 README.md

diff --git a/.circleci/config.yml b/.circleci/config.yml
index fa4e6b26..895b3fb5 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -2,7 +2,7 @@ version: 2
 
 references:
   workspace: &workspace
-    /go/src/github.com/rsteube/cobra-zsh-gen
+    /go/src/github.com/rsteube/carapace
 
   run_tests: &run_tests
     run:
@@ -16,7 +16,8 @@ references:
         go build .
         curl -Lso shellcheck https://github.com/caarlos0/shellcheck-docker/releases/download/v0.4.6/shellcheck
         chmod +x shellcheck
-        ./shellcheck -e SC2148,SC2154 <(./example _zsh_completion)
+        ./shellcheck -e SC2148,SC2154 <(./example _carapace zsh)
+        ./shellcheck -e SC2148,SC2154 <(./example _carapace fish)
 
 jobs:
   go-current:
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..1e1a086d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,132 @@
+# carapace
+
+[![CircleCI](https://circleci.com/gh/rsteube/carapace.svg?style=svg)](https://circleci.com/gh/rsteube/carapace)
+
+[ZSH completion](https://github.com/zsh-users/zsh-completions/blob/master/zsh-completions-howto.org) and [Fish completion](https://fishshell.com/docs/current/#writing-your-own-completions) script generator for [cobra] (based on [spf13/cobra#646](https://github.com/spf13/cobra/pull/646)).
+
+
+## Status
+
+**WIP**: works, but expect some api changes and small hiccups like a special character not yet escaped
+
+## Usage
+
+Calling `carapace.Gen` on any command is enough for adding completion script generation using the [hidden command](#hidden-command).
+
+> Invocations to `carapace.Gen` must be **after** the command was to the parent command so that the [uids](#uid) are correct.
+
+```go
+import (
+    "github.com/rsteube/carapace"
+)
+
+carapace.Gen(myCmd)
+```
+
+### FlagCompletions
+
+Completion for flags can be configured with `FlagCompletion` and a map consisting of name and [action](#action).
+
+```go
+carapace.Gen(myCmd).FlagCompletion(carapace.ActionMap{
+    "flagName": carapace.ActionValues("a", "b", "c"),
+    ...
+})
+```
+
+### PositionalCompletions
+
+Completion for positional arguments can be configured with `PositionalCompletion` and a list of [actions](#action).
+
+```go
+carapace.Gen(callbackCmd).PositionalCompletion(
+    carapace.ActionValues("a", "b", "c"),
+    ...
+)
+```
+
+## Hidden Command
+
+When `carapace.Gen(myCmd)` is invoked a hidden command (`_carapace`) is added to the root command unless it already exists. This handles completion script generation (when invoked with arg `zsh` or `fish`) and [callbacks](#actioncallback).
+
+
+### Uid
+
+Uids are generated to identify corresponding completions:
+- `_{rootCmd}__{subCommand1}__{subCommand2}#{position}` for positional arguments
+- `_{rootCmd}__{subCommand1}__{subCommand2}##{flagName}` for flags
+
+
+## Action
+An [action](#action) indicates how to complete a flag or a positional argument. See [action.go](./action.go) and the examples below for current implementations.
+
+Additional information can be found at [zsh-completions-howto](https://github.com/zsh-users/zsh-completions/blob/master/zsh-completions-howto.org#functions-for-performing-complex-completions-of-single-words) and the [official documentation](http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-System).
+
+### ActionMessage
+
+```go
+carapace.ActionMessage("message example")
+
+// #./example action --message <TAB>
+// message example
+```
+
+### ActionValuesDescribed
+
+```go
+carapace.ActionValuesDescribed(
+  "values", "valueDescription",
+  "example", "exampleDescription"),
+
+// #./example action --values_described <TAB>
+// example  -- exampleDescription
+// values   -- valueDescription
+```
+
+### ActionCallback
+
+ActionCallback is a special [action](#action) where the program itself provides the completion dynamically. For this the [hidden command](#hidden-command) is called with a [uid](#uid) and the current command line content which then lets [cobra] parse existing flags and invokes the callback function after that.
+
+```go
+carapace.ActionCallback(func(args []string) carapace.Action {
+  if conditionCmd.Flag("required").Value.String() == "valid" {
+    return carapace.ActionValues("condition fulfilled")
+  } else {
+    return carapace.ActionMessage("flag --required must be set to valid: " + conditionCmd.Flag("required").Value.String())
+  }
+})
+
+// #./example condition --required invalid <TAB>
+// flag --required must be set to valid: invalid
+```
+
+Since callbacks are simply invocations of the program they can be tested directly.
+
+```sh
+./example _carapace zsh '_example__condition#1' condition --required invalid
+
+# _message -r 'flag --required must be set to valid: invalid'
+```
+
+### Custom Action
+
+For [actions](#action) that aren't implemented or missing required options, a custom action can be defined.
+
+```go
+carapace.Action{Value: "_most_recent_file 2"}
+
+// #./example action --custom <TAB>
+```
+
+## Example
+
+An example implementation can be found in the [example](./example/) folder.
+
+```sh
+cd example
+go build .
+source <(./example _carapace zsh)
+./example <TAB>
+```
+
+[cobra]:https://github.com/spf13/cobra