Update README

README.md

@@ -6,46 +6,138 @@ can be organized into a 'library'. The 'template' is now only
 responsible for simplified high level definitions. Running `manifer` will 
 combine the library and template to compose the final document.
 
-# build
-`./scripts/build.sh [--setup]`
-- `--setup` will `go get` required branches of forked dependencies
-
-# test
-`./scripts/test.sh [go test flags]`
-- `-count=1` can be used to disable test caching of integration tests in `cmd/manifer`
-
-# run
+# subcommands
+## list
 ```
-./manifer list [-a] (-l <library path>...):
+./manifer list [--all] (--library <library path>...):
   list scenarios in selected libraries.
   -a    Include all referenced libraries
+  -all
+        Include all referenced libraries
+  -j    Print output in json format
+  -json
+        Print output in json format
   -l value
         Path to library file
+  -library value
+        Path to library file
 ```
+## compose
 ```
-./manifer compose -t <template path> (-l <library path>...) (-s <scenario>...) [-p] [-d] [-- passthrough flags ...]:
+./manifer compose --template <template path> (--library <library path>...) (--scenario <scenario>...) [--print] [--diff] [-- passthrough flags ...]:
   compose a yml file from snippets.
   -d    Show diff after each snippet is applied
+  -diff
+        Show diff after each snippet is applied
   -l value
         Path to library file
+  -library value
+        Path to library file
   -p    Show snippets and arguments being applied
+  -print
+        Show snippets and arguments being applied
   -s value
         Scenario name in library
+  -scenario value
+        Scenario name in library
   -t string
-        Path to template file
+        Path to initial template file
+  -template string
+        Path to initial template file
 ```
 
-# interpolation and arguments
+# schemas
+
+## template
+Any valid yaml document you would like to modify with opsfiles and [implicit bosh variables](https://bosh.io/docs/cli-int/#implicit)
+
+e.g. foo-template.yml
+```
+foo:
+  bar: bizz
+  buzz: ((bazz))
+  extra: redundant
+```
+
+## snippets
+Yaml snippets to compose into the template use [go-patch](https://github.com/cppforlife/go-patch) format, 
+Also known as [BOSH Ops Files](https://bosh.io/docs/cli-ops-files).
+
+e.g. base-case.yml
+```
+- path: /foo/bar
+  type: replace
+  value: ((newbar))
+
+- path: /foo/extra
+  type: remove
+
+- path: /foo/((sub))? # note: bosh/go-patch do not natively support variables in opsfile paths
+  type: replace
+  value:
+    new: struct
+```
+
+## library
+[library.go](https://github.com/cjnosal/manifer/blob/master/pkg/library/library.go)
+
+Opsfiles can be grouped into scenarios, a named set that will be applied in order with associated variables to the template.
+Scenarios are defined in a library file.
+
+e.g. commonlib.yml
+```
+type: opsfile
+scenarios:
+- name: base-case
+  description: helpful text displayed by `./manifer list`
+  args: # applied to all snippets in this scenario
+  - -v
+  - sub=nested
+  snippets: # opsfiles to apply, in order
+  - path: ./base-case.yml
+    args: # applied to single snippet
+    - -v
+    - newbar=trendy
+```
 
+e.g. mainlib.yml
+```
+type: opsfile # other yaml templating tools could be supported in the future
+libraries:
+- alias: common # reference to another library file
+  path: ./commonlib.yml
+scenarios:
+- name: my-use-case
+  scenarios: # scenarios can reference other scenarios. The referenced scenario's snippets are applied first.
+  - name: common.base-case # prefix library alias if scenario name is in referenced library
+    args: # arguments will be applied to all snippets in the referenced scenario
+    - -v
+    - e=f
+  global_args: # applied all snippets in all scenarios as well as the template
+  - -v
+  - bazz=123
+```
+
+## Invocation
+Running `manifer compose --library mainlib.yml --template foo-template.yml --scenario my-use-case` should produce:
+```
+foo:
+  bar: trendy
+  buzz: 123
+  nested:
+    new: struct
+```
+
+# interpolation and arguments
 There are four argument scopes:
 - snippet args
 - scenario args
 - scenario global args
 - CLI global args
 
 Every snippet is used in two interpolations:
-- first the snippet itself is interpolated with snippet args, scenario args, and global args
-- then the template is interpolated with the interpolated snippet and global args
+- the snippet itself is interpolated with snippet args, scenario args, and global args
+- then the interpolated snippet is applied to the template, interpolated with global args
 
 # multiple libraries
 Libraries can include other libraries by specifying the path and an alias under 
@@ -55,51 +147,10 @@ library the name should be prefixed with `<library alias>.`.
 If multiple independant libraries are provided to the CLI all scenario names 
 should be unambiguous.
 
-# sample
-```base_library.yml
-type: opsfile
-
-scenarios:
-- name: "reusable"
-  snippets:
-  - path: ./common_opsfile.yml
-```
-```derived_library.yml
-type: opsfile
-
-libraries:
-- alias: other
-  path: "./base_library.yml"
-
-scenarios:
-- name: "base"
-  args:
-  - -v 
-  - foo=bar
-  snippets:
-  - path: ./opsfile.yml
-    args:
-    - -v 
-    - path=value
-
-- name: "derived"
-  scenarios:
-  - "other.reusable"
-  - "base"
-  global_args:
-  - -v
-  - deployment=test
-  args:
-  - -v 
-  - foo=overridden
-  snippets:
-  - path: ./another_opsfile.yml
-```
-```template.yml
-arbitrary: yaml
-```
-
-Invoke with:
-`./manifer compose -l derived_library.yml -t template.yml -s derived -- -v extra=arg`
+# build
+`./scripts/build.sh [--setup]`
+- `--setup` will `go get` required branches of forked dependencies
 
-Add `-p` (show plan) and `-d` (show diff) to see the input/output of each interpolation
+# test
+`./scripts/test.sh [go test flags]`
+- `-count=1` can be used to disable test caching of integration tests in `cmd/manifer`