blog: Add 2025-07-21.md

Author: ingydotnet

blog/2025-07-21.md

@@ -0,0 +1,158 @@
+---
+title: Calling Shell Commands from YAML
+date: 2025-07-21
+draft: false
+authors: [ingydotnet]
+categories: [Summer-of-YS]
+edit: blog/2025-07-21.md
+comments: true
+---
+
+Wouldn't it be handy to get data from shell commands in YAML?
+
+Well you can, and it's really easy.
+
+YS has a bunch of functions in its Standard Library for calling shell commands,
+and passing data to and from them.
+
+Let's take a look...
+
+<!-- more -->
+
+
+## The `shell` function
+
+When you just want to run a shell command and let its outputs print to the
+terminal, you can use the `shell` function.
+
+```bash
+$ ys - <<'...'
+!YS-v0
+shell: 'fortune'
+...
+You have taken yourself too seriously.
+```
+
+This is the same as running `fortune` in from the command line.
+
+You can also pass data to the shell command.
+Let's try the `tac` command, which reverses the lines of a file.
+
+```bash
+$ ys - <<'...'
+!YS-v0
+shell {:in "foo\nbar\nbaz\n"}: 'tac'
+...
+baz
+bar
+foo
+```
+
+
+## The `sh` function
+
+The `sh` function doesn't print the output to the terminal.
+It returns a mapping that contains a bunch of fields like the exit code, stdout,
+stderr, and more.
+
+```bash
+$ ys - <<'...'
+!YS-v0
+result =:
+  sh: 'echo "Hello, World!"'
+say: result.out
+...
+Hello, World!
+```
+
+Let's look at the entire result object:
+
+```bash
+$ ys - <<'...'
+!YS-v0
+result =:
+  sh: 'echo "Hello, World!"'
+say: result
+...
+{:proc #object[java.lang.ProcessImpl 0x512d4b90 Process[pid=1364706, exitValue=0]], :exit 0, :in #object[java.lang.ProcessImpl$ProcessPipeOutputStream 0x22ebcf7e java.lang.ProcessImpl$ProcessPipeOutputStream@22ebcf7e], :out Hello, World!
+, :err , :prev nil, :cmd [echo Hello, World!]}
+```
+
+That's kind of ugly and hard to read.
+
+Let's use the `yaml/dump` function to pretty print it:
+
+```bash
+$ ys - <<'...'
+!YS-v0
+result =:
+  sh: 'echo "Hello, World!"'
+say: result:yaml/dump
+...
+proc: !!java.lang.ProcessImpl {}
+exit: 0
+in: !!java.lang.ProcessImpl$ProcessPipeOutputStream {}
+out: |
+  Hello, World!
+err: ''
+prev: null
+cmd:
+- echo
+- Hello, World!
+```
+
+Much better!
+
+You can also pass data to the `sh` function just like the `shell` function.
+
+
+## The `sh-out` function
+
+The `sh-out` function is like the `sh` function, but it returns the output as a
+string.
+
+```bash
+$ ys - <<'...'
+!YS-v0
+say:
+  sh-out: 'echo "Hello, World!"'
+...
+Hello, World!
+```
+
+This handy shortcut is often just what the doctor ordered.
+
+
+## The `bash` function
+
+You can only run simple shell commands with the `shell` and `sh` functions.
+
+In other words, you can't do things like pipes and redirects.
+
+Of course you can also put any complicated shell command inside:
+
+```
+bash -c 'complicated | shell > command'
+```
+
+The `bash` function basically does this for you in YS code.
+
+```bash
+$ ys - <<'...'
+!YS-v0
+say:
+  get _ :out:
+    bash: 'fortune | tr a-z A-Z > /tmp/fortune.txt &&
+           ls -l /tmp/fortune.txt && cat /tmp/fortune.txt'
+...
+-rw-r--r-- 1 ingy ingy 46 Jul 21 21:27 /tmp/fortune.txt
+LOOK AFAR AND SEE THE END FROM THE BEGINNING.
+```
+
+## The Shell's the Limit
+
+As you can imagine, there's no limit to what you can do with shell commands in
+YAML using YS.
+
+Don't worry.
+Later we'll explore ways to actually limit capabilities in YS if you need to.