Self Installation Scripts
Note: If you just ran a program with
bash
that printed a URL to this page, click the arrow below for more information on "What just happened?".What just happened?
If you are reading this you probably just ran a YAMLScript program with
bash
. The first time you do that, the program installed theys
interpreter under the/tmp/
directory for you and then ran the program with it. Subsequent runs of the program will use that installedys
interpreter.You may continue to run the program this way, but there will be a slight delay at the start each time while the
run-ys
auto-installer script is downloaded.It is very easy to install the
ys
interpreter permanently on your system so that you can run the program withys
instead ofbash
.$ curl -s https://yamlscript.org/install-ys | bash
See the YAMLScript Installation page for more information.
YAMLScript has a way to publish programs that people can run immediately without having installed the ys
interpreter first.
Warning: See the Security Considerations below before using this technique.
Just begin your YAMLScript program with these lines:
#!/usr/bin/env ys-0
source <(curl '-s' 'https://yamlscript.org/run-ys') "$@" :
Then anyone can run your program using Bash with a command like this: bash script.ys arg1 arg2 ...
.
The first time they do so, the ys
interpreter will be downloaded and installed under the /tmp/
directory.
The ys
interpreter will be downloaded only once, and it will be used for all subsequent runs of the script.
Note: The
curl
command will still download and evaluate therun-ys
script on subsequent runs > so the user will need to have internet access.
The program can also be run with the ys
interpreter if the user installs it. In that case the Bash installer line will be ignored.
Since the program has a shebang line, it can also be run as a PATH
command if the file is marked as executable.
Example
Here's a small YAMLScript program that program that prints the ROT13 encoding of its arguments:
#!/usr/bin/env ys-0
source <(curl '-s' 'https://yamlscript.org/run-ys') "$@" :
defn main(in):
s =: set((\\A .. \\Z) + (\\a .. \\z))
say: cycle(s).drop(13 * 2).zipmap(s).map(in).str(*)
If we run it with ys
:
$ ys rot13.ys FooBar
SbbOne
If we run it with bash
:
$ bash rot13.ys FooBar
Installing YAMLScript CLI '/tmp/yamlscript-run-ys/bin/ys-0.1.72' now...
Ctl-C to abort
See https://yamlscript.org/doc/run-ys for more information.
Installed /tmp/yamlscript-run-ys/bin/ys - version 0.1.72
--------------------------------------------------------------------------------
SbbOne
and again:
$ bash rot13.ys FooBar
SbbOne
How It Works
The program is both valid YAMLScript and valid Bash.
YAMLScript programs are required to start with a YAML tag like this:
!yamlscript/v0
But if they start with a shebang line like this:
#!/usr/bin/env ys-0
then the !yamlscript/v0
tag is optional.
When you run the program with bash
, the shebang line is merely a comment and ignored by Bash.
The source
line is a Bash command that reads and evaluates the contents of the <(...)
process substitution file. The curl
command inside downloads the run-ys
script and installs the ys
interpreter under the /tmp/
directory if it is not already installed.
It then exec
s the installed ys
interpreter with your original program and any arguments you provided.
The source
line is also a valid YAMLScript command. It calls the YAMLScript source
macro which ignores all of its arguments (much like the comment
macro does).
Note: The
source
macro was added in YAMLScript version 0.1.72. This technique will not work with earlier versions of YAMLScript.
Use Cases and Security Considerations
This technique is may be useful in situations where you want to share a YAMLScript program with people who are not yet familiar with YAMLScript.
Since the program is run with Bash which gets more Bash code from the internet, it is subject to the many security risks of running arbitrary code from the internet.
Caveat yamlscriptor!
** Note**: A more secure way to distribute a YAMLScript program is to compile it to a binary executable and distribute the binary instead.
There is at least one use case where this technique is safe and useful:
You can easily run a YAMLScript program that you are developing with a particular version of the ys
interpreter without having to install it first. Just use the YS_VERSION
environment variable to specify the version you want:
$ YS_VERSION=0.1.72 bash my-program.ys arg1 arg2 ...
This might be useful for testing a reported bug with an older version of the interpreter, for example.
There may be other development and testing use cases for this technique as well. If you find one, please let us know!