Starting another program
A computer is full of programs that already do one thing well: git
keeps versions, ffmpeg turns one kind of video into another, a C
compiler compiles. A program that needs one of those things done does
not do it again. It starts the program that can, and waits.
import program
let ended = program.run("git", ["status", "--short"])
print(f"git ended with {ended}")
M docs/decisions.md
?? examples/download.zeno
git ended with 0
That is the whole of it: one function, in the module that already had
program.arguments().
| Written | Gives | Can fail with |
|---|---|---|
program.run(name, words) |
the int the program ended with |
FileError |
The decisions behind it are 25.1 to 25.7 in
decisions.md.
What run does
- It looks for a program called
namewhere the system looks for programs: the folders ofPATH. A name with a/in it is a path, and is used as it is. On Windowsyt-dlpfindsyt-dlp.exe. - It starts the program with
wordsas the words after its name. - It waits until the program ends. While it runs, the program uses this program's screen and keyboard, so what it prints appears among this program's lines, in the order things happened.
- It gives the number the program ended with. 0 means that all went well; what any other number means is for the other program to say.
The words are a list
program.run("yt-dlp", ["--paths", "my videos", address])
Each item is one word for the other program, whatever is in it. my
videos has a blank in it and is still one word, because it is one
item. Nothing reads the words on the way: no shell is started, so a
*, a $, a ; or a quote in an item means nothing but itself.
This matters most when a word comes from outside the program, as an
address does. In languages where the command is one line of text
handed to a shell, an address that ends in ; rm -rf ~ is two
commands. In Zeno it is one odd address, which the other program will
refuse (25.3).
A program that wants a shell's pipes and stars starts a shell, and the line shows it:
program.run("sh", ["-c", "ls *.zeno | wc -l"])
A Zeno program that is started this way gets the list back, item for
item, from its own program.arguments().
When it cannot be started
try {
program.run("yt-dlp", ["--version"])
} except FileError as error {
print(error.message) # there is no program `yt-dlp` to run
}
That a program is installed cannot be known before it is started, so
run raises a FileError, the error the files module raises for a
file that is not there. A function that calls run catches it or says
raises FileError, and zeno check --strict holds it to that.
A program that started and then ended with 3 is not an error. It ran, and 3 is its answer.
The example
examples/download.zeno saves a video
from YouTube in a folder. It is for videos you have the right to keep,
and its first lines say so.
zeno run examples/download.zeno https://youtu.be/VIDEO videos
Zeno does not fetch the video. The program checks that the address is one of YouTube's, puts together the words for yt-dlp, starts it, and says in plain words how it went:
try {
let ended = program.run("yt-dlp", words_for(address, folder, audio_only))
if ended == 0 and folder == "." {
print("Saved in this folder.")
} else if ended == 0 {
print(f"Saved in `{folder}`.")
} else {
print(f"yt-dlp could not save it, and ended with {ended}. What went wrong is in its lines above.")
}
} except FileError {
print("yt-dlp is not installed, or is not where programs are looked for.")
print("Get it with `pip install yt-dlp`, or from https://github.com/yt-dlp/yt-dlp")
}
Three things can happen, and each has its line: the program is not there, it ran and failed, it ran and worked.
Where it works
zeno run, zeno run --vm, zeno test |
yes |
zeno build, zeno build --llvm |
not yet: the build says so and names the line |
zeno build --target ... |
not yet, the same way |
zeno build --firmware |
never: a board has no other programs |
| In a page | a FileError: a browser starts no programs |
How it is built
One function in builtins.rs, program_run, which both engines call.
It hands the name and the words to Rust's std::process::Command,
which starts the program without a shell on every system, and on
Windows joins the words into the one line Windows wants, quoted by
Windows' rules.
Just before, it pushes out whatever this program has printed, so that the other program's lines come after it and not before.
The checker's part is "program.run" in builtin: a str, a
list[str], an int back, and can_raise("FileError").
emit_c.rs and emit_llvm.rs each have one arm that refuses, and
lower.rs has no_target_has, which refuses for every target at
once.
The tests are in interpreter.rs
(another_program_is_run_with_the_words_as_they_are, which has sh
write each word it was given into a file, among them two words,
a"b, $HOME, * and an empty one; and
a_program_that_is_not_there_is_a_file_error), in checker.rs, and
one in each of emit_c.rs, emit_llvm.rs and lower.rs for the
refusals. Every one that runs a program runs it in both engines.
Things to try
-
Run
zeno run examples/download.zenowith no words, then with an address that is not YouTube's. Which lines of the program decide each answer? -
Write
today.zeno, which runsdate(orcmdwith["/C", "date", "/T"]on Windows) and prints the number it ended with. Then misspell the name of the program and read the message. -
Write a program that prints its
program.arguments(), and a second that starts the first withprogram.run("zeno", ["run", "first.zeno", "two words", "*"]). How many arguments does the first one see? -
program.run("ls", ["*.zeno"])says there is no such file, andprogram.run("sh", ["-c", "ls *.zeno"])lists them. Who turns*into names? -
In
download.zeno, add a third word,--small, that asks yt-dlp for a picture no taller than 480 lines (--format-sortand thenres:480). Where do the words go inwords_for, and why must they be two items and not one?
This page is docs/running-programs.md in the language repository.