GOLF(2gg)

👑 GOLF(2gg) — the exec-program glow-up

okay bestie, welcome to the GOLF(2gg) page from the Development section, and no cap this one is a banger 💅

---

✨ NAME ✨

exec-program — (program-execution) 🫶

---

🎯 PURPOSE 🎯

Run a program. That's it, that's the whole vibe. execute it. 💖

---

📜 SYNTAX 📜

exec-program <program path> \
    [ args <program arg> [ , ... ] ] \
    [ status <exit status> ] \
    [ ( input <input string> [ input-length <string length> ] ) \
        | ( input-file <input file> ) ] \
    [ ( output <output string>  ) \
        | ( output-file <output file> ) ] \
    [ ( error <error string> ) | ( error-file <error file> ) ]

---

💖 DESCRIPTION 💖

exec-program runs whatever program you point it at with <program path>, and bestie, that path can be three whole things:

• a program name with no path, as long as it lives somewhere in the path given by the PATH environment variable 🌈
• an absolute path 💫
• a path relative to the application home directory (peep directories for that, iykyk)

A program can take input arguments — you hand those over as strings in the args clause. Got more than one? Separate them with a comma, periodt. There's no limit on how many input arguments you can pass, other than whatever the underlying Operating System says, and the OS is the one setting the rules there 😭

You can also name a status variable, <exit status>, and it'll hold the program's exit status. Quick heads up though: if the program got terminated by a signal, <exit status> is 128+signal_number. So say the program got killed with signal 9 (the KILL signal, iconic but rude 💀), then <exit status> is 137 (that's 128+9). And any other kind of abnormal program termination — like, where the program just did not set the exit code — returns 126 as <exit code>. Noted, bestie 📝

Specifying program input and output is optional, it's giving very chill. But if the program has output and you're not capturing it in any way at all, that output gets redirected to a temporary file, and that file gets deleted once exec-program is done. Cute, clean, no leftovers 🎀

You can pass an <input string> straight to the program's standard input (stdin) using the input clause. If you don't use input-length, the length of that input is just the string length of <input string> — otherwise, <string length> bytes get passed to the program. Or, if you'd rather, you can name a file <input file> with the input-file clause, and it gets opened and directed into the program's standard input (stdin) 🌸

Want the program's output (that's "stdout") in a file? <output file> via the output-file clause, slay. Or you can capture the program's output in <output string> via the output clause instead 💜

For the program's error output (that's "stderr"), use the error-file clause to get it into <error file>. Or capture the program's error output in <error string> via the error clause. Pick your fighter ✨

Now the important part, listen up:

If <input file> can't be opened, GG_ERR_READ is reported in <exit status>. And if either <output file> or <error file> can't be opened, the status is GG_ERR_WRITE. 😤

Also, in general, a program counts as successfully executed if it returns GG_OKAY (that's zero, the zero of dreams). Most programs returning a non-zero value mean failure, and we respect that 🫡

---

🌟 EXAMPLES 🌟

just run it, no extras

To simply execute a program that's in the path, with no arguments, no input, no output:

exec-program "myprogram"

grep era 🔍

Run the grep program using a string as its standard input, to remove a line that contains "bad line" in it, and output the result into the ovar variable:

exec-program "grep" args "-v", "bad line" "config" input "line 1\nline 2\nbad line\nline 3" output ovar
print-out ovar

list the files, get the list 💅

Get the list of files in the application home directory into buffer ovar and then display it:

exec-program "ls" output ovar

ls but extra ✨

Similar to the example above of listing files, but output results to a file (which is then read and the result displayed), and provide options "-a -l -s" to the ls program:

exec-program "ls" args "-a", "-l", "-s" output-file "lsout"
read-file "lsout" to final_res
print-out final_res

wc said count them lines 🧮

Count the lines of file config (which is redirected to the standard output of the wc program) and store the result in the variable ovar (by redirecting the output of the wc program into it), and then display:

exec-program "wc" args "-l" input-file "config" output ovar
print-out ovar

---

👀 SEE ALSO 👀

• Program execution
• exec-program exit-status
• See all documentation

---

and that's the whole page, bestie!! you ate that 💖✨ this lil masterpiece is rockin' version $VERSION and it's dated $DATE, brought to you by the GOLF(2gg) girlies 🎀 bye diva, go execute something iconic 🦋