Repository: eemeli/yaml
Pull request #617 (2025-04-16 16:21:58)

docs: include cli example
Adding basic example of CLI usage.

Reading from STDIN is not pattern I have used for node based CLI tools and took me a second to process. Example might help someone else.

Feel free to decline if its not aligned. 


Patch:
diff --git a/docs/09_cli.md b/docs/09_cli.md
index 0788bcb..9ec5ad1 100644
--- a/docs/09_cli.md
+++ b/docs/09_cli.md
@@ -1,8 +1,12 @@
 # Command-line Tool
 
+```sh
+npx yaml valid < file.yaml
+```
+
 Available as `npx yaml` or `npm exec yaml`:
 
-<pre id="cli-help" style="float: none">
+<pre id="cli-help" style="float: none; clear: none">
 yaml: A command-line YAML processor and inspector
 
 Reads stdin and writes output to stdout and errors & warnings to stderr.
@@ -17,6 +21,7 @@ Options:
   --help, -h    Show this message.
   --json, -j    Output JSON.
   --indent 2    Output pretty-printed data, indented by the given number of spaces.
+  --merge, -m   Enable support for "<<" merge keys.
 
 Additional options for bare "yaml" command:
   --doc, -d     Output pretty-printed JS Document objects.
diff --git a/src/cli.ts b/src/cli.ts
index 9e80f32..b46a90c 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -27,6 +27,7 @@ Options:
   --help, -h    Show this message.
   --json, -j    Output JSON.
   --indent 2    Output pretty-printed data, indented by the given number of spaces.
+  --merge, -m   Enable support for "<<" merge keys.
 
 Additional options for bare "yaml" command:
   --doc, -d     Output pretty-printed JS Document objects.
@@ -59,6 +60,7 @@ export async function cli(
         doc: { type: 'boolean', short: 'd' },
         help: { type: 'boolean', short: 'h' },
         indent: { type: 'string', short: 'i' },
+        merge: { type: 'boolean', short: 'm' },
         json: { type: 'boolean', short: 'j' },
         single: { type: 'boolean', short: '1' },
         strict: { type: 'boolean', short: 's' },
@@ -127,7 +129,7 @@ export async function cli(
       const lineCounter = new LineCounter()
       const parser = new Parser(lineCounter.addNewLine)
       // @ts-expect-error Version is validated at runtime
-      const composer = new Composer({ version: opt.yaml })
+      const composer = new Composer({ version: opt.yaml, merge: opt.merge })
       const visitor: visitor | null = opt.visit
         ? (await import(resolve(opt.visit))).default
         : null


Test patch:
diff --git a/tests/cli.ts b/tests/cli.ts
index 14ed144..27c2eca 100644
--- a/tests/cli.ts
+++ b/tests/cli.ts
@@ -208,6 +208,32 @@ const skip = Number(major) < 20
         ]
       )
     })
+    describe('--merge', () => {
+      ok(
+        'can be set',
+        'hello:\n  world: 2\nfoo:\n  world: 2',
+        ['--merge', '--json'],
+        ['[{"hello":{"world":2},"foo":{"world":2}}]']
+      )
+      ok(
+        'basic',
+        'hello: &a\n  world: 2\nfoo:\n  <<: *a',
+        ['--merge', '--json'],
+        ['[{"hello":{"world":2},"foo":{"world":2}}]']
+      )
+      ok(
+        'also enabled with --yaml=1.1',
+        'hello: &a\n  world: 2\nfoo:\n  <<: *a',
+        ['--yaml=1.1', '--json'],
+        ['[{"hello":{"world":2},"foo":{"world":2}}]']
+      )
+      ok(
+        'not enabled by default',
+        'hello: &a\n  world: 2\nfoo:\n  <<: *a',
+        ['--json'],
+        ['[{"hello":{"world":2},"foo":{"<<":{"world":2}}}]']
+      )
+    })
     describe('--doc', () => {
       ok('basic', 'hello: world', ['--doc'], [{ contents: { items: [{}] } }])
       ok(