Update usage and README

alxarch · Feb 8, 2019 · d0cdb5b · d0cdb5b
1 parent fb626c5
commit d0cdb5b
Show file tree

Hide file tree

Showing 2 changed files with 79 additions and 48 deletions.
diff --git a/README.md b/README.md
@@ -1,33 +1,45 @@
 # ycat
 
-Comand line processor for YAML/JSON files using [Jsonnet](https://jsonnet.org/)
+Command line processor for YAML/JSON files using [Jsonnet](https://jsonnet.org/)
 
+## Usage
 ```
-Usage: ycat [options|files...]
+ycat - command line YAML/JSON processor
 
-Options:
+USAGE:
+    ycat [OPTIONS] [INPUT...]
+    ycat [OPTIONS] [PIPELINE...]
+
+PIPELINE:
+    [INPUT...] [ENV...] EVAL
+
+OPTIONS:
     -h, --help                   Show help and exit
-    -y, --yaml [files...]        Read YAML values from file(s)
-    -j, --json [files...]        Read JSON values from file(s)
-    -n, --null                   Use null value input (no reading)
     -o, --out {json|j|yaml|y}    Set output format
-        --to-json                Output JSON one value per line (same as -o json, -oj)
-    -a, --array                  Merge values into an array
-    -e, --eval <snippet>         Process values with Jsonnet
-    -v, --var <var>=<code>       Bind Jsonnet variable to code
-              <var>==<value>     Bind Jsonnet variable to a string value
-    -i, --import <var>=<file>    Import file into a local Jsonnet variable
-        --input-var <var>        Change the name of the input value variable (default x) 
-        --max-stack <size>       Jsonnet VM max stack size (default 500)
-```
 
-### Arguments
+INPUT:
+    [FILE...]                   Read values from file(s)
+    -y, --yaml [FILE...]        Read YAML values from file(s)
+    -j, --json [FILE...]        Read JSON values from file(s)
+    -n, --null                  Inject a null value 
+    -a, --array                 Merge values to array
+
+ENV:
+    -v, --var <VAR>=<CODE>       Bind Jsonnet variable to code
+              <VAR>==<VALUE>     Bind Jsonnet variable to a string value
+    -i, --import <VAR>=<FILE>    Import file into a local Jsonnet variable
+        --input-var <VAR>        Change the name of the input value variable (default x) 
+        --max-stack <SIZE>       Jsonnet VM max stack size (default 500)
+
+EVAL:
+    -e, --eval <SNIPPET>         Process values with Jsonnet
 
-All non-option arguments are files to read from.
-Format is guessed from extension and fallsback to YAML.
 
-If filename is `-` values are read from stdin using the last specified format or YAML
-
+If no INPUT is specified, values are read from stdin as YAML.
+If FILE is "-" or "" values are read from stdin until EOF.
+If FILE has no type option format is detected from extension.
+```
+
 ## Examples
 
 Concatenate files to a single YAML stream (type is selected from extension)
@@ -39,7 +51,6 @@ $ ycat foo.yaml bar.yaml baz.json
 Concatenate files to single JSON stream (one item per-line)
 
 ```
-$ ycat --to-json foo.yaml bar.yaml baz.json
 $ ycat -o j foo.yaml bar.yaml baz.json
 ```
 
@@ -58,7 +69,7 @@ $ ycat -y a.txt - b.txt -j a.json
 Concatenate to YAML array
 
 ```
-$ ycat -a a.json b.yaml
+$ ycat a.json b.yaml -a
 ```
 
 Concatenate YAML from `a.yaml` and `b.yaml` setting key `foo` to `bar` on each top level object
@@ -67,10 +78,16 @@ Concatenate YAML from `a.yaml` and `b.yaml` setting key `foo` to `bar` on each t
 $ ycat a.yaml b.yaml -e 'x+{foo: "bar"}'
 ```
 
+Same as above with results merged into a single array
+
+```
+$ ycat a.yaml b.yaml -e 'x+{foo: "bar"}' -a
+```
+
 Add kubernetes namespace `foo` to all resources without namespace
 
 ```
-$ ycat -e 'x + { metadata +: { namespace: if "namespace" in super then super.namespace else "foo" }}' *.yaml
+$ ycat *.yaml -e 'x + { metadata +: { namespace: if "namespace" in super then super.namespace else "foo" }}'
 ```
 
 Process with [jq](http://stedolan.github.io/jq/) using a pipe
@@ -91,31 +108,33 @@ go get github.com/alxarch/ycat
 
 
 
-## YAML Input
+## Input / Output
+
+### YAML input
 
 Multiple YAML values separated by `---\n` are processed separately.
 Value reading stops at `...\n` or `EOF`.
 
-## JSON Input
+### YAML output
 
-Multiple JSON values separated by whitespace are processed separately.
-Value reading stops at `EOF`.
+Each result value is appended to the output with `---\n` separator.
 
-## YAML Output
+### JSON input
 
-Each result value is appended to the output with `---\n` separator.
+Multiple JSON values separated by whitespace are processed separately.
+Value reading stops at `EOF`.
 
-## JSON Output
+### JSON output
 
 Each result value is appended into a new line of output.
 
 ## Jsonnet
 
 [Jsonnet](https://jsonnet.org/) is a templating language from google that's really versatile in handling configuration files. Visit their site for more information.
 
-Each value is bound to a local variable named `x` inside the snippet by default. Use `--bind` to change the name.
+Each value is bound to a local variable named `x` inside the snippet by default. Use `--input-var` to change the name.
 
-To use `Jsonnet` code from a file in the snippet use `-m <var>=<file>` and the exported value will be available as
+To use `Jsonnet` code from a file in the snippet use `-i <VAR>=<FILE>` and the exported value will be available as
 a local variable in the snippet.
 
 ## TODO

diff --git a/arguments.go b/arguments.go
@@ -14,27 +14,39 @@ import (
 const Usage = `
 ycat - command line YAML/JSON processor
 
-Usage: ycat [options|files...]
+USAGE:
+    ycat [OPTIONS] [INPUT...]
+    ycat [OPTIONS] [PIPELINE...]
 
-Options:
+PIPELINE:
+    [INPUT...] [ENV...] EVAL
+
+OPTIONS:
     -h, --help                   Show help and exit
-    -y, --yaml [files...]        Read YAML values from file(s)
-    -j, --json [files...]        Read JSON values from file(s)
-    -n, --null                   Use null value input (no reading)
     -o, --out {json|j|yaml|y}    Set output format
         --to-json                Output JSON one value per line (same as -o json, -oj)
-    -a, --array                  Merge values into an array
-    -e, --eval <snippet>         Process values with Jsonnet
-    -v, --var <var>=<code>       Bind Jsonnet variable to code
-              <var>==<value>     Bind Jsonnet variable to a string value
-    -i, --import <var>=<file>    Import file into a local Jsonnet variable
-        --input-var <var>        Change the name of the input value variable (default x) 
-        --max-stack <size>       Jsonnet VM max stack size (default 500)
 
-If no files are specified values are read from stdin.
-Using "-" as a file path will read values from stdin.
-Files without a format option will be parsed as YAML unless
-they end in ".json".
+INPUT:
+    [FILE...]                   Read values from file(s)
+    -y, --yaml [FILE...]        Read YAML values from file(s)
+    -j, --json [FILE...]        Read JSON values from file(s)
+    -n, --null                  Inject a null value 
+    -a, --array                 Merge values to array
+
+ENV:
+    -v, --var <VAR>=<CODE>       Bind Jsonnet variable to code
+              <VAR>==<VALUE>     Bind Jsonnet variable to a string value
+    -i, --import <VAR>=<FILE>    Import file into a local Jsonnet variable
+        --input-var <VAR>        Change the name of the input value variable (default x) 
+        --max-stack <SIZE>       Jsonnet VM max stack size (default 500)
+
+EVAL:
+    -e, --eval <SNIPPET>         Process values with Jsonnet
+
+
+If no INPUT is specified, values are read from stdin as YAML.
+If FILE is "-" or "" values are read from stdin until EOF.
+If FILE has no type option format is detected from extension.
 `
 
 func splitArgV(s string) (string, string) {