From cc7eb84388540a084e3a0789bc6ed3603d9a086f Mon Sep 17 00:00:00 2001 From: kenjones Date: Mon, 25 Sep 2017 22:36:49 -0400 Subject: [PATCH] Task: Add docs on keys with dots Adds documentation on how to use a key lookup indicator for dealing with keys that have dots when specifying a path as part of create, read, and write commands. Resolves: #22 --- docs/create/index.html | 28 ++++++++++++++++++++++++++++ docs/mkdocs/search_index.json | 21 ++++++++++++++++++--- docs/read/index.html | 28 ++++++++++++++++++++++++++++ docs/sitemap.xml | 12 ++++++------ docs/write/index.html | 28 ++++++++++++++++++++++++++++ mkdocs/create.md | 4 +++- mkdocs/read.md | 2 ++ mkdocs/snippets/keys_with_dots.md | 17 +++++++++++++++++ mkdocs/write.md | 2 ++ 9 files changed, 132 insertions(+), 10 deletions(-) create mode 100644 mkdocs/snippets/keys_with_dots.md diff --git a/docs/create/index.html b/docs/create/index.html index 413b88d..6fcb960 100644 --- a/docs/create/index.html +++ b/docs/create/index.html @@ -257,6 +257,13 @@ +
  • + + Keys with dots + + +
    • + @@ -322,6 +329,13 @@ +
  • + + Keys with dots + + +
    • + @@ -373,6 +387,20 @@ b.e[0].name: Howdy Partner

    You can also pipe the instructions in:

    cat create_instructions.yaml | yaml n -s -
    + +

    Keys with dots

    +

    When specifying a key that has a dot use key lookup indicator.

    +
    b:
+  foo.bar: 7
+
    + +
    yaml r sample.yaml b[foo.bar]
+
    + +
    yaml w sample.yaml b[foo.bar] 9
+
    + +

    Any valid yaml key can be specified as part of a key lookup.

    diff --git a/docs/mkdocs/search_index.json b/docs/mkdocs/search_index.json index 533d377..1c110d2 100644 --- a/docs/mkdocs/search_index.json +++ b/docs/mkdocs/search_index.json @@ -22,7 +22,7 @@ }, { "location": "/read/", - "text": "yaml r \nyaml_file|json_file\n \npath\n\n\n\n\n\nThis command can take a json file as input too, and will output yaml unless specified to export as json (-j)\n\n\nBasic\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n\n\n\n\nthen\n\n\nyaml r sample.yaml b.c\n\n\n\n\nwill output the value of '2'.\n\n\nFrom Stdin\n\n\nGiven a sample.yaml file of:\n\n\ncat sample.yaml | yaml r - b.c\n\n\n\n\nwill output the value of '2'.\n\n\nSplat\n\n\nGiven a sample.yaml file of:\n\n\n---\nbob:\n item1:\n cats: bananas\n item2:\n cats: apples\n\n\n\n\nthen\n\n\nyaml r sample.yaml bob.*.cats\n\n\n\n\nwill output\n\n\n- bananas\n- apples\n\n\n\n\nHandling '.' in the yaml key\n\n\nGiven a sample.yaml file of:\n\n\nb.x:\n c: 2\n\n\n\n\nthen\n\n\nyaml r sample.yaml \\\nb.x\\\n.c\n\n\n\n\nwill output the value of '2'.\n\n\nArrays\n\n\nYou can give an index to access a specific element:\ne.g.: given a sample file of\n\n\nb:\n e:\n - name: fred\n value: 3\n - name: sam\n value: 4\n\n\n\n\nthen\n\n\nyaml r sample.yaml b.e[1].name\n\n\n\n\nwill output 'sam'\n\n\nArray Splat\n\n\ne.g.: given a sample file of\n\n\nb:\n e:\n - name: fred\n value: 3\n - name: sam\n value: 4\n\n\n\n\nthen\n\n\nyaml r sample.yaml b.e[*].name\n\n\n\n\nwill output:\n\n\n- fred\n- sam", + "text": "yaml r \nyaml_file|json_file\n \npath\n\n\n\n\n\nThis command can take a json file as input too, and will output yaml unless specified to export as json (-j)\n\n\nBasic\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n\n\n\n\nthen\n\n\nyaml r sample.yaml b.c\n\n\n\n\nwill output the value of '2'.\n\n\nFrom Stdin\n\n\nGiven a sample.yaml file of:\n\n\ncat sample.yaml | yaml r - b.c\n\n\n\n\nwill output the value of '2'.\n\n\nSplat\n\n\nGiven a sample.yaml file of:\n\n\n---\nbob:\n item1:\n cats: bananas\n item2:\n cats: apples\n\n\n\n\nthen\n\n\nyaml r sample.yaml bob.*.cats\n\n\n\n\nwill output\n\n\n- bananas\n- apples\n\n\n\n\nHandling '.' in the yaml key\n\n\nGiven a sample.yaml file of:\n\n\nb.x:\n c: 2\n\n\n\n\nthen\n\n\nyaml r sample.yaml \\\nb.x\\\n.c\n\n\n\n\nwill output the value of '2'.\n\n\nArrays\n\n\nYou can give an index to access a specific element:\ne.g.: given a sample file of\n\n\nb:\n e:\n - name: fred\n value: 3\n - name: sam\n value: 4\n\n\n\n\nthen\n\n\nyaml r sample.yaml b.e[1].name\n\n\n\n\nwill output 'sam'\n\n\nArray Splat\n\n\ne.g.: given a sample file of\n\n\nb:\n e:\n - name: fred\n value: 3\n - name: sam\n value: 4\n\n\n\n\nthen\n\n\nyaml r sample.yaml b.e[*].name\n\n\n\n\nwill output:\n\n\n- fred\n- sam\n\n\n\n\nKeys with dots\n\n\nWhen specifying a key that has a dot use key lookup indicator.\n\n\nb:\n foo.bar: 7\n\n\n\n\nyaml r sample.yaml b[foo.bar]\n\n\n\n\nyaml w sample.yaml b[foo.bar] 9\n\n\n\n\nAny valid yaml key can be specified as part of a key lookup.", "title": "Read" }, { @@ -55,9 +55,14 @@ "text": "e.g.: given a sample file of b:\n e:\n - name: fred\n value: 3\n - name: sam\n value: 4 then yaml r sample.yaml b.e[*].name will output: - fred\n- sam", "title": "Array Splat" }, + { + "location": "/read/#keys-with-dots", + "text": "When specifying a key that has a dot use key lookup indicator. b:\n foo.bar: 7 yaml r sample.yaml b[foo.bar] yaml w sample.yaml b[foo.bar] 9 Any valid yaml key can be specified as part of a key lookup.", + "title": "Keys with dots" + }, { "location": "/write/", - "text": "yaml w \nyaml_file|json_file\n \npath\n \nnew value\n\n\n\n\n\nThis command can take a json file as input too, and will output yaml unless specified to export as json (-j)\n\n\nTo Stdout\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n\n\n\n\nthen\n\n\nyaml w sample.yaml b.c cat\n\n\n\n\nwill output:\n\n\nb:\n c: cat\n\n\n\n\nFrom STDIN\n\n\ncat sample.yaml | yaml w - b.c blah\n\n\n\n\nAdding new fields\n\n\nAny missing fields in the path will be created on the fly.\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n\n\n\n\nthen\n\n\nyaml w sample.yaml b.d[0] \nnew thing\n\n\n\n\n\nwill output:\n\n\nb:\n c: cat\n d:\n - new thing\n\n\n\n\nAppending value to an array field\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n d:\n - new thing\n - foo thing\n\n\n\n\nthen\n\n\nyaml w sample.yaml b.d[+] \nbar thing\n\n\n\n\n\nwill output:\n\n\nb:\n c: cat\n d:\n - new thing\n - foo thing\n - bar thing\n\n\n\n\nUpdating files in-place\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n\n\n\n\nthen\n\n\nyaml w -i sample.yaml b.c cat\n\n\n\n\nwill update the sample.yaml file so that the value of 'c' is cat.\n\n\nUpdating multiple values with a script\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n e:\n - name: Billy Bob\n\n\n\n\nand a script update_instructions.yaml of:\n\n\nb.c: 3\nb.e[0].name: Howdy Partner\n\n\n\n\nthen\n\n\nyaml w -s update_instructions.yaml sample.yaml\n\n\n\n\nwill output:\n\n\nb:\n c: 3\n e:\n - name: Howdy Partner\n\n\n\n\nAnd, of course, you can pipe the instructions in using '-':\n\n\ncat update_instructions.yaml | yaml w -s - sample.yaml\n\n\n\n\nValues starting with a hyphen (or dash)\n\n\nThe flag terminator needs to be used to stop the app from attempting to parse the subsequent arguments as flags:\n\n\nyaml w -- my.path -3\n\n\n\n\nwill output\n\n\nmy:\n path: -3", + "text": "yaml w \nyaml_file|json_file\n \npath\n \nnew value\n\n\n\n\n\nThis command can take a json file as input too, and will output yaml unless specified to export as json (-j)\n\n\nTo Stdout\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n\n\n\n\nthen\n\n\nyaml w sample.yaml b.c cat\n\n\n\n\nwill output:\n\n\nb:\n c: cat\n\n\n\n\nFrom STDIN\n\n\ncat sample.yaml | yaml w - b.c blah\n\n\n\n\nAdding new fields\n\n\nAny missing fields in the path will be created on the fly.\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n\n\n\n\nthen\n\n\nyaml w sample.yaml b.d[0] \nnew thing\n\n\n\n\n\nwill output:\n\n\nb:\n c: cat\n d:\n - new thing\n\n\n\n\nAppending value to an array field\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n d:\n - new thing\n - foo thing\n\n\n\n\nthen\n\n\nyaml w sample.yaml b.d[+] \nbar thing\n\n\n\n\n\nwill output:\n\n\nb:\n c: cat\n d:\n - new thing\n - foo thing\n - bar thing\n\n\n\n\nUpdating files in-place\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n\n\n\n\nthen\n\n\nyaml w -i sample.yaml b.c cat\n\n\n\n\nwill update the sample.yaml file so that the value of 'c' is cat.\n\n\nUpdating multiple values with a script\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n e:\n - name: Billy Bob\n\n\n\n\nand a script update_instructions.yaml of:\n\n\nb.c: 3\nb.e[0].name: Howdy Partner\n\n\n\n\nthen\n\n\nyaml w -s update_instructions.yaml sample.yaml\n\n\n\n\nwill output:\n\n\nb:\n c: 3\n e:\n - name: Howdy Partner\n\n\n\n\nAnd, of course, you can pipe the instructions in using '-':\n\n\ncat update_instructions.yaml | yaml w -s - sample.yaml\n\n\n\n\nValues starting with a hyphen (or dash)\n\n\nThe flag terminator needs to be used to stop the app from attempting to parse the subsequent arguments as flags:\n\n\nyaml w -- my.path -3\n\n\n\n\nwill output\n\n\nmy:\n path: -3\n\n\n\n\nKeys with dots\n\n\nWhen specifying a key that has a dot use key lookup indicator.\n\n\nb:\n foo.bar: 7\n\n\n\n\nyaml r sample.yaml b[foo.bar]\n\n\n\n\nyaml w sample.yaml b[foo.bar] 9\n\n\n\n\nAny valid yaml key can be specified as part of a key lookup.", "title": "Write/Update" }, { @@ -95,9 +100,14 @@ "text": "The flag terminator needs to be used to stop the app from attempting to parse the subsequent arguments as flags: yaml w -- my.path -3 will output my:\n path: -3", "title": "Values starting with a hyphen (or dash)" }, + { + "location": "/write/#keys-with-dots", + "text": "When specifying a key that has a dot use key lookup indicator. b:\n foo.bar: 7 yaml r sample.yaml b[foo.bar] yaml w sample.yaml b[foo.bar] 9 Any valid yaml key can be specified as part of a key lookup.", + "title": "Keys with dots" + }, { "location": "/create/", - "text": "Yaml files can be created using the 'new' command. This works in the same way as the write command, but you don't pass in an existing Yaml file.\n\n\nyaml n \npath\n \nnew value\n\n\n\n\n\nCreating a simple yaml file\n\n\nyaml n b.c cat\n\n\n\n\nwill output:\n\n\nb:\n c: cat\n\n\n\n\nCreating using a create script\n\n\nCreate scripts follow the same format as the update scripts.\n\n\nGiven a script create_instructions.yaml of:\n\n\nb.c: 3\nb.e[0].name: Howdy Partner\n\n\n\n\nthen\n\n\nyaml n -s create_instructions.yaml\n\n\n\n\nwill output:\n\n\nb:\n c: 3\n e:\n - name: Howdy Partner\n\n\n\n\nYou can also pipe the instructions in:\n\n\ncat create_instructions.yaml | yaml n -s -", + "text": "Yaml files can be created using the 'new' command. This works in the same way as the write command, but you don't pass in an existing Yaml file.\n\n\nyaml n \npath\n \nnew value\n\n\n\n\n\nCreating a simple yaml file\n\n\nyaml n b.c cat\n\n\n\n\nwill output:\n\n\nb:\n c: cat\n\n\n\n\nCreating using a create script\n\n\nCreate scripts follow the same format as the update scripts.\n\n\nGiven a script create_instructions.yaml of:\n\n\nb.c: 3\nb.e[0].name: Howdy Partner\n\n\n\n\nthen\n\n\nyaml n -s create_instructions.yaml\n\n\n\n\nwill output:\n\n\nb:\n c: 3\n e:\n - name: Howdy Partner\n\n\n\n\nYou can also pipe the instructions in:\n\n\ncat create_instructions.yaml | yaml n -s -\n\n\n\n\nKeys with dots\n\n\nWhen specifying a key that has a dot use key lookup indicator.\n\n\nb:\n foo.bar: 7\n\n\n\n\nyaml r sample.yaml b[foo.bar]\n\n\n\n\nyaml w sample.yaml b[foo.bar] 9\n\n\n\n\nAny valid yaml key can be specified as part of a key lookup.", "title": "Create" }, { @@ -110,6 +120,11 @@ "text": "Create scripts follow the same format as the update scripts. Given a script create_instructions.yaml of: b.c: 3\nb.e[0].name: Howdy Partner then yaml n -s create_instructions.yaml will output: b:\n c: 3\n e:\n - name: Howdy Partner You can also pipe the instructions in: cat create_instructions.yaml | yaml n -s -", "title": "Creating using a create script" }, + { + "location": "/create/#keys-with-dots", + "text": "When specifying a key that has a dot use key lookup indicator. b:\n foo.bar: 7 yaml r sample.yaml b[foo.bar] yaml w sample.yaml b[foo.bar] 9 Any valid yaml key can be specified as part of a key lookup.", + "title": "Keys with dots" + }, { "location": "/convert/", "text": "Yaml to Json\n\n\nTo convert output to json, use the --tojson (or -j) flag. This can be used with any command.\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n\n\n\n\nthen\n\n\nyaml r -j sample.yaml b.c\n\n\n\n\nwill output\n\n\n{\nb\n:{\nc\n:2}}\n\n\n\n\nJson to Yaml\n\n\nTo read in json, just pass in a json file instead of yaml, it will just work :)\n\n\ne.g given a json file\n\n\n{\na\n:\nEasy! as one two three\n,\nb\n:{\nc\n:2,\nd\n:[3,4]}}\n\n\n\n\nthen\n\n\nyaml r sample.json\n\n\n\n\nwill output\n\n\na: Easy! as one two three\nb:\n c: 2\n d:\n - 3\n - 4", diff --git a/docs/read/index.html b/docs/read/index.html index 0d2aa48..cb8a4f4 100644 --- a/docs/read/index.html +++ b/docs/read/index.html @@ -261,6 +261,13 @@ +
  • + + Keys with dots + + +
    • + @@ -378,6 +385,13 @@ +
  • + + Keys with dots + + +
    • + @@ -480,6 +494,20 @@ e.g.: given a sample file of

    - fred
 - sam
    + +

    Keys with dots

    +

    When specifying a key that has a dot use key lookup indicator.

    +
    b:
+  foo.bar: 7
+
    + +
    yaml r sample.yaml b[foo.bar]
+
    + +
    yaml w sample.yaml b[foo.bar] 9
+
    + +

    Any valid yaml key can be specified as part of a key lookup.

    diff --git a/docs/sitemap.xml b/docs/sitemap.xml index 222fdf8..bb17d51 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -4,7 +4,7 @@ / - 2017-09-24 + 2017-09-26 daily @@ -12,7 +12,7 @@ /read/ - 2017-09-24 + 2017-09-26 daily @@ -20,7 +20,7 @@ /write/ - 2017-09-24 + 2017-09-26 daily @@ -28,7 +28,7 @@ /create/ - 2017-09-24 + 2017-09-26 daily @@ -36,7 +36,7 @@ /convert/ - 2017-09-24 + 2017-09-26 daily @@ -44,7 +44,7 @@ /merge/ - 2017-09-24 + 2017-09-26 daily diff --git a/docs/write/index.html b/docs/write/index.html index 6452bde..e375a19 100644 --- a/docs/write/index.html +++ b/docs/write/index.html @@ -280,6 +280,13 @@ +
  • + + Keys with dots + + +
    • + @@ -392,6 +399,13 @@ +
  • + + Keys with dots + + +
    • + @@ -520,6 +534,20 @@ b.e[0].name: Howdy Partner 
    my:
   path: -3
    + +

    Keys with dots

    +

    When specifying a key that has a dot use key lookup indicator.

    +
    b:
+  foo.bar: 7
+
    + +
    yaml r sample.yaml b[foo.bar]
+
    + +
    yaml w sample.yaml b[foo.bar] 9
+
    + +

    Any valid yaml key can be specified as part of a key lookup.

    diff --git a/mkdocs/create.md b/mkdocs/create.md index 0d7a4b7..3c97de1 100644 --- a/mkdocs/create.md +++ b/mkdocs/create.md @@ -39,4 +39,6 @@ You can also pipe the instructions in: ```bash cat create_instructions.yaml | yaml n -s - -``` \ No newline at end of file +``` + +{!snippets/keys_with_dots.md!} diff --git a/mkdocs/read.md b/mkdocs/read.md index b9a4bbd..155f3be 100644 --- a/mkdocs/read.md +++ b/mkdocs/read.md @@ -91,3 +91,5 @@ will output: - fred - sam ``` + +{!snippets/keys_with_dots.md!} diff --git a/mkdocs/snippets/keys_with_dots.md b/mkdocs/snippets/keys_with_dots.md new file mode 100644 index 0000000..81f8f18 --- /dev/null +++ b/mkdocs/snippets/keys_with_dots.md @@ -0,0 +1,17 @@ +### Keys with dots +When specifying a key that has a dot use key lookup indicator. + +```yaml +b: + foo.bar: 7 +``` + +```bash +yaml r sample.yaml b[foo.bar] +``` + +```bash +yaml w sample.yaml b[foo.bar] 9 +``` + +Any valid yaml key can be specified as part of a key lookup. diff --git a/mkdocs/write.md b/mkdocs/write.md index 460c74e..b59f2f2 100644 --- a/mkdocs/write.md +++ b/mkdocs/write.md @@ -123,3 +123,5 @@ will output my: path: -3 ``` + +{!snippets/keys_with_dots.md!}