### Execlineb Script: Basic Execution Flow and Comments Source: https://skarnet.org/software/execline/componentsb This script demonstrates basic execlineb execution. It includes comments, the 'foreground' command, a 'sleep' command within braces, and examples of different string literal interpretations. Note that variable substitution and environment variable expansion are not enabled by default in this version. ```execline #!/command/execlineb -P # This execlineb script will sleep for 1 second, then print some # silly things on the standard output. foreground # an unquoted string, evaluated to: foreground { # A single opening brace, not included in the argv sleep 1 # Two unquoted strings, evaluated to " sleep" and " 1" # (without the quotation marks). } # A single closing brace, evaluated to the empty word "echo" # this is a quoted string. It will evaluate to the word: echo foo\ bar\ zoinx # This is one word, since the spaces are escaped "foo bar zoinx" # This is exactly the same word, written another way " # this is not a comment, since it is inside a quoted string # This is not a comment either \" # nor is this " # but this is one "\0x41\66\0103D\n" # This is the string ABCD followed by a newline. # Be careful: the newline will be part of the word. \n # this is not a newline, but the single word: n $23 # This will NOT be replaced by anything with execline-1.y, unless # substitution is explicitly asked for in the script. # The dollar is no special character for the execline binary. baz"$1"qux # This will evaluate to the word baz$1qux baz\$1qux # Same here baz$1qux # Same here in execline-1.y ${PATH} # This will NOT be replaced by execline ; use the importas command # if you need the $PATH value. 'this is not a string' # it will be parsed as five separate words "\ " # This will be parsed as the empty word. A (backslash, newline) # sequence inside a quoted string is entirely removed. ``` -------------------------------- ### Execline `case` with Subexpression Matching Example Source: https://skarnet.org/software/execline/case This example demonstrates the usage of the `case` program with the `-N` option to capture subexpressions during regular expression matching. It shows how to define a regex with capturing groups and how the matched parts of the input value are made available in the environment variables `0`, `#`, `1`, and `2`. ```execline #!/bin/execlineb -S1 emptyenv case -N -- $1 { "([fo]+)bar(baz)" { /usr/bin/env } } ``` -------------------------------- ### Chaining pipelines in execlineb Source: https://skarnet.org/software/execline/pipeline This example demonstrates how to create a chain of pipes using the 'pipeline' program within execlineb, showing its equivalence to shell command chaining. ```execline execlineb -Pc 'pipeline { a } pipeline { b } c' ``` -------------------------------- ### Implementing ifelse with runblock in execline Source: https://skarnet.org/software/execline/runblock An example demonstrating how to implement an `ifelse` command using an execline script with the `runblock` program. This showcases `runblock`'s ability to conditionally execute blocks. ```execline #!/command/execlineb if [ { runblock 2 } { runblock -r 2 } ] runblock 1 ``` -------------------------------- ### Basic execline Script Example Source: https://skarnet.org/software/execline/grammar Illustrates a simple execline script that uses the 'nice' command to adjust process priority and then executes 'echo blah'. This demonstrates the chain loading principle without shell overhead. ```execline #!/command/execlineb -P nice -10 echo blah ``` -------------------------------- ### Example: Parallel vs. Serial Substitution with multisubstitute Source: https://skarnet.org/software/execline/multisubstitute Illustrates the difference between serial and parallel variable substitution using `multisubstitute`. The first script demonstrates serial substitution's potential for unexpected results, while the second shows how `multisubstitute` ensures simultaneous evaluation. ```execlineb #!/command/execlineb export A wrong define B ${A} importas A A echo ${B} ``` ```execlineb #!/command/execlineb export A wrong multisubstitute { define B ${A} importas A A } echo ${B} ``` -------------------------------- ### Define and Substitute Variables in Execline Source: https://skarnet.org/software/execline/quine-prj-2 This snippet shows how to define variables and use the 'multisubstitute' command in Execline to manipulate strings and substitute variable values. It demonstrates basic string concatenation and variable expansion. ```execline #!/command/execlineb define e "#!/command/execlineb define e ${q}${E}${q} multisubstitute { define q ${b}${q} define b ${b}${b} define E $e } echo $e" multisubstitute { define q " define b \ define E $e } echo $e ``` -------------------------------- ### execline background Program -d Option Example Source: https://skarnet.org/software/execline/background Demonstrates the usage of the `-d` option for the `background` program. This option causes the _prog1..._ command to run as a grandchild of the `background` process, effectively detaching it further. ```execline background -d { my_command } another_command ``` -------------------------------- ### fdmove Usage Example with Shell Equivalent (Move) Source: https://skarnet.org/software/execline/fdmove Illustrates the functionality of fdmove when moving a file descriptor, along with its equivalent command using the shell. This shows how fdmove redirects output and closes the original descriptor. ```bash # fdmove _a_ _b_ prog... is roughly equivalent to sh -c 'exec prog... _a_ >&_b_ _b_ <&-' ``` -------------------------------- ### Execline Scripting: Export and Define Variables Source: https://skarnet.org/software/execline/quine-sertonix This script demonstrates basic execlineb functionality, including exporting environment variables and defining new ones. It utilizes shell-like syntax for variable assignment and substitution. ```execline #!/bin/execlineb export # 1 define 1 "#!/bin/execlineb export ${b}# 1 define 1 ${q}${1}${q} export 1 $1 define q ${b}${q} define b ${b}${b} importas 1 1 export 1 $1 dollarat" export 1 $1 define q " define b \ importas 1 1 export 1 $1 dollarat ``` -------------------------------- ### Using fdereserve to Create a Pipe Source: https://skarnet.org/software/execline/fdreserve An example demonstrating how to use 'fdreserve' to create a pipe. It reserves 2 file descriptors, assigns them to environment variables 'fdr' and 'fdw', and then uses 'piperw' to establish the pipe. The final '_prog...' represents the program that will use the pipe. ```execline #!/command/execlineb fdreserve 2 multisubstitute { importas fdr FD0 importas fdw FD1 } piperw $fdr $fdw _prog... ``` -------------------------------- ### fdmove Usage Example with Shell Equivalent (Duplicate) Source: https://skarnet.org/software/execline/fdmove Demonstrates the fdmove -c option for duplicating a file descriptor, and its equivalent shell command. This highlights how the -c flag allows both the original and target file descriptors to remain open and connected. ```bash # fdmove -c _a_ _b_ prog... is roughly equivalent to sh -c 'exec prog... _a_ >&_b_ ' ``` -------------------------------- ### Quoting and Substitution in execline Source: https://skarnet.org/software/execline/el_substitute Illustrates execline's quoting mechanism for handling literal variable substitutions. It shows how backslashes affect whether a variable like '$A' is substituted or treated literally, and how this interacts with the shell's own backslash interpretation. The example defines 'A' as 'val' and then uses 'echo' with various backslash prefixes to demonstrate the quoting rules. ```execline #!/command/execlineb define A val foreground { echo $A \$A \\$A \\\$A \\\\$A \\\\\$A } echo $B \$B \\$B \\\$B \\\\$B \\\\\$B ``` -------------------------------- ### execline Program Interface Source: https://skarnet.org/software/execline/execline Demonstrates the basic command-line syntax for invoking the execline program. It shows how to call a subcommand with its arguments, or how execline executes a command when invoked by its name. ```shell execline _subcommand_ _subcommand_arguments... ``` -------------------------------- ### execlineb Script Syntax - Unquoted Strings and Comments Source: https://skarnet.org/software/execline/execlineb Illustrates the use of unquoted strings, comments, and character escaping in execlineb scripts. Comments start with '#' and are ignored. Backslashes can escape special characters in unquoted strings. ```execline this is an unquoted string # This is a comment and will be ignored. An escaped \# character. ``` -------------------------------- ### Typical execline Script Initialization using elgetpositionals Source: https://skarnet.org/software/execline/elgetpositionals This code snippet demonstrates a common pattern for initializing an execline script that takes arguments. It first uses `elgetopt` to parse options, then `elgetpositionals` to handle positional parameters, followed by the main script logic (`_prog...`). ```execline #!/command/execlineb elgetopt _optstring_ elgetpositionals _prog... ``` -------------------------------- ### Execline `case` Syntax and Usage Source: https://skarnet.org/software/execline/case This snippet shows the general syntax for the `case` program within an execlineb script. It outlines the placement of the value to be matched, the directives (regex and program blocks), and the default program to execute if no match is found. It's essential for understanding the basic structure of `case` commands. ```execline case [ -S | -s ] [ -E | -e ] [ -i ] [ -n | -N ] _value_ { [ regex { _prog..._ } ] [ regex { _prog..._ } ] ... } _progdefault..._ ``` -------------------------------- ### Execlineb Quine Script - Code Definition and Substitution Source: https://skarnet.org/software/execline/quine-dam This snippet demonstrates the core logic of the execlineb quine. It defines special characters and keywords using macros and then uses these definitions within a loop to substitute them, ultimately reconstructing the script's own source code. It highlights the use of `define`, `forx`, and `multisubstitute` for code generation. ```execline #! /command/execlineb -P # Public Domain. # See comments below. # (Search for "HERE".) # define -sCd "\n" lns " ${p} ${bubble} is the end of the quine's data. ${p} They represent the following code, with various quotations: ${p} ${b} (backslash) is represented as ${d}${ob}b${cb} ${p} ${q} (double quote) is represented as ${d}${ob}q${cb} ${p} ${p} (sharp/pound/shibboleth/whatever) is represented as ${d}${ob}p${cb} ${p} ${ob} (open brace) is represented as ${d}${ob}ob${cb} ${p} ${cb} (closed brace) is represented as ${d}${ob}cb${cb} ${p} ${d} (dollar) is represented as ${d}${ob}d${cb} ${p} ${bubble} (the magic word) is represented as ${d}${ob}bubble${cb} ${p} (The point of the magic word is to allow the reader ${p} to conveniently skip over the large data section.) ${p} ${p} Now we have the quine's code! ${p} ${p} First, print the lines that come before the data. foreground ${ob} printf %s ${b}${p}${b}!${q} ${q} ${cb} foreground ${ob} printf %s${b}${b}n ${q}/command/execlineb -P${q} ${cb} foreground ${ob} printf %s${b}${b}n ${b}${p}${q} Public Domain.${q} ${cb} foreground ${ob} printf %s${b}${b}n ${b}${p}${q} See comments below.${q} ${cb} foreground ${ob} printf %s ${b}${p}${q} (Search for ${q} ${cb} foreground ${ob} printf %s${b}${b}n ${b}${q}${bubble}${b}${q}.) ${cb} foreground ${ob} printf %s${b}${b}n ${b}${p} ${cb} foreground ${ob} printf %s ${q}define -sCd ${b}${q}${b}${b}n${b}${q} lns ${b}${q}${q} ${cb} ${p} Next, print the data themselves, as data. foreground ${ob} forx -E lin ${ob} ${d}${ob}lns${cb} ${cb} multisubstitute ${ob} define b ${d}${ob}b${cb} define q ${d}${ob}q${cb} define p ${d}${ob}p${cb} define ob ${d}${ob}ob${cb} define cb ${d}${ob}cb${cb} define d ${d}${ob}d${cb} define bubble ${d}${ob}bubble${cb} define intron ${d}${ob}intron${cb} ${cb} printf ${b}${b}n%s ${d}${ob}lin${cb} ${cb} foreground ${ob} printf %s${b}${b}n ${b}${q} ${cb} ${p} Finally, use the data to print the code! forx -E lin ${ob} ${d}${ob}lns${cb} ${cb} multisubstitute ${ob} define b ${b}${b} define q ${b}${q} define p ${b}${p} define ob ${b}${ob} define cb ${b}${cb} define d ${d} define bubble ${bubble} define intron ${q}${intron}${q} ${cb} printf %s${b}${b}n ${d}${ob}lin${cb} ${p} That's all, folks! - Well, that wasn't so hard, was it? ${p} (This quine was written by - see ${p} ${p} for more information on quines and how to write them.)" # HERE is the end of the quine's data. # They represent the following code, with various quotations: # \ (backslash) is represented as ${b} # " (double quote) is represented as ${q} # # (sharp/pound/shibboleth/whatever) is represented as ${p} # { (open brace) is represented as ${ob} # } (closed brace) is represented as ${cb} # $ (dollar) is represented as ${d} # HERE (the magic word) is represented as ${bubble} # (The point of the magic word is to allow the reader # to conveniently skip over the large data section.) # # Now we have the quine's code! # # First, print the lines that come before the data. foreground { printf %s #!" " } foreground { printf %s\n "/command/execlineb -P" } foreground { printf %s\n #" Public Domain." } foreground { printf %s\n #" See comments below." } foreground { printf %s #" (Search for " } foreground { printf %s\n "HERE".) } foreground { printf %s\n # } foreground { printf %s "define -sCd \"\n\" lns "" # Next, print the data themselves, as data. foreground { forx -E lin { ${lns} } multisubstitute { define b ${b} define q ${q} define p ${p} define ob ${ob} define cb ${cb} define d ${d} define bubble ${bubble} define intron ${intron} } printf \n%s ${lin} } foreground { printf %s\n "" # Finally, use the data to print the code! forx -E lin { ${lns} } multisubstitute { define b \\ define q " define p # define ob { define cb } define d $ define bubble HERE define intron "NOTICE HOW THIS SENTENCE APPEARS ONLY ONCE IN THIS QUINE?" } printf %s\n ${lin} # That's all, folks! - Well, that wasn't so hard, was it? # (This quine was written by - see # # for more information on quines and how to write them.) ``` -------------------------------- ### Shell Execution of Foreground Command with Blocks (Security Example - Safe) Source: https://skarnet.org/software/execline/el_semicolon Illustrates a secure way to handle substitution within blocks using quoted arguments, preventing unintended execution flow modifications. The `${FOO}` variable is properly quoted. ```shell $ define FOO '' foreground ' echo' ' ${FOO}' ' rm' ' -rf' ' /' '' echo blah ``` -------------------------------- ### execlineb Command-Line Interface Source: https://skarnet.org/software/execline/execlineb Shows the different ways to invoke the execlineb program, including direct script execution, script from a file, and as a shebang in an executable file. It outlines the available options for parsing and environment management. ```bash #!/command/execlineb [ -qwWpPS_nmin_ ] _script_ ``` ```bash execlineb [ -q | -w | -W ] [ -p | -P | -S _nmin_ | -s _nmin_ ] [ -e ] -c _script_ [ _args..._ ] ``` ```bash execlineb [ -q | -w | -W ] [ -p | -P | -S _nmin_ | -s _nmin_ ] [ -e ] _scriptfile_ [ _args..._ ] ``` -------------------------------- ### Shell Execution of Foreground Command with Blocks (Security Example - Unsafe) Source: https://skarnet.org/software/execline/el_semicolon Demonstrates a security vulnerability when substitution occurs within an unquoted argument inside a block. The `${FOO}` variable expands to an empty string, altering the intended command sequence. ```shell $ define FOO '' foreground echo '${FOO}' rm -rf / '' echo blah ``` -------------------------------- ### execline background Equivalent to Shell Command Source: https://skarnet.org/software/execline/background Illustrates an equivalent shell command for a specific usage of the `background` program. This shows how `background _prog1..._ "" _prog2..._` can be replicated using `sh -c`. ```execline background _prog1..._ "" _prog2..._ ``` ```shell sh -c '_prog1..._ & ; exec _prog2..._ ' ``` -------------------------------- ### redirfd - Command-line Utility Source: https://skarnet.org/software/execline/redirfd The `redirfd` program redirects a given file descriptor to a file, then executes a program. It requires one of the mode options (-r, -w, -u, -a, -x) and can optionally use -n for non-blocking mode and -b to control blocking behavior. ```APIDOC ## redirfd ### Description Redirects a file descriptor to a file and executes a program. ### Method Executable ### Endpoint N/A (Command-line utility) ### Parameters #### Path Parameters None #### Query Parameters None #### Arguments - **-r** (flag) - Required - Open file for reading. - **-w** (flag) - Required - Open file for writing, truncating if it exists. - **-u** (flag) - Required - Open file for reading and writing. - **-a** (flag) - Required - Open file for appending, creating if it doesn't exist. - **-x** (flag) - Required - Open file for writing, creating it, failing if it exists. - **-n** (flag) - Optional - Open file in non-blocking mode. - **-b** (flag) - Optional - Change file mode to non-blocking (if -n not given) or blocking (if -n given). - **_fd_** (integer) - Required - The file descriptor number to redirect. - **_file_** (string) - Required - The file path to redirect the file descriptor to. - **_prog..._** (string) - Required - The program and its arguments to execute after redirection. ### Request Example ```bash redirfd -w 1 my_log.txt echo "Hello, World!" ``` ### Response #### Success Response (0) Execution of the program `prog...` after successful redirection. #### Response Example N/A (Command-line utility execution) ### Error Handling - Exits with a non-zero status code on failure (e.g., invalid options, file access errors). ``` -------------------------------- ### getpid Program Documentation Source: https://skarnet.org/software/execline/getpid Documentation for the `getpid` program, including its interface, options, and notes. ```APIDOC ## getpid Program ### Description The `getpid` program stores its process ID in a given environment variable, then executes a program. ### Interface ``` getpid [ -E | -e ] [ -P | -p ] _var_ _prog... ``` `getpid` stores its PID in the _var_ variable, then execs into _prog_ with its arguments. ### Options * `-e`: no autoimport. This is the default. * `-E`: autoimport. Instead of exec'ing into _prog..., exec into `importas -ui _var_ _var_ _prog...`. This substitutes _var_ into the command line instead of putting it into the environment. * `-p`: get the pid of the current process. This is the default. * `-P`: use `getpid`'s _parent_ pid instead. ### Notes * _var_ must be given without a dollar! * _var_ must not contain `=`. ``` -------------------------------- ### Clone execline Git Repository Source: https://skarnet.org/software/execline/index This command allows you to download the execline source code from its official Git repository. Ensure you have Git installed on your system to use this command. It clones the entire repository, providing access to the latest development version. ```git git clone git://git.skarnet.org/execline ``` -------------------------------- ### execline trap program -x option equivalent directive Source: https://skarnet.org/software/execline/trap Demonstrates how the '-x' option of the 'trap' program can be replicated using a 'default' directive. This involves using 'multisubstitute' to import the process ID and signal number, then using 'kill' to forward the signal. ```execline default { multisubstitute { importas ! ! importas SIGNAL SIGNAL } kill -$SIGNAL $! } ``` -------------------------------- ### Potential Issue with Multiple fdereserve Calls Source: https://skarnet.org/software/execline/fdreserve Illustrates a scenario where multiple calls to 'fdreserve' might lead to overlapping file descriptors if not handled carefully. This example shows a potential failure case where 'oldfd' and 'newfd' could refer to the same descriptor if descriptors are not explicitly allocated between 'fdreserve' calls. ```execline #!/command/execlineb fdreserve 3 multisubstitute { importas fdr FD0 importas fdw FD1 } piperw $fdr $fdw fdreserve 1 multisubstitute { importas oldfd FD2 importas newfd FD0 } _prog... ``` -------------------------------- ### Execute Commands Sequentially with `foreground` (execlineb) Source: https://skarnet.org/software/execline/foreground The `foreground` command in execlineb executes a sequence of commands. It first runs a command block (`_prog1..._`), waits for its completion, and then updates the `?` environment variable with the exit code or signal status. Finally, it execs into the subsequent command (`_prog2..._`). This is fundamental for scripting sequential command execution. ```execlineb foreground { _prog1..._ } _prog2... ``` -------------------------------- ### Execline `case` with Shell Matching Example Source: https://skarnet.org/software/execline/case This snippet illustrates the `case` program's shell matching mode, activated by the `-s` option. In this mode, regular expressions are treated as shell glob patterns, and subexpression matching is disabled. This is useful for simpler pattern matching scenarios akin to shell's built-in `case` statements. ```execline case -s -- $value { "*.txt" { echo "It's a text file." } "*.sh" { echo "It's a shell script." } } ``` -------------------------------- ### execline trap program interface and directives Source: https://skarnet.org/software/execline/trap Illustrates the syntax for the 'trap' program in an execline script, including signal directives and their associated command blocks. It shows how to define handlers for specific signals (SIGTERM, quit, SIGHUP) and a default handler. ```execline trap [ -x ] { [ SIGTERM { _progsigterm..._ } ] [ quit { _progsigquit..._ } ] [ 1 { _progsighup_... } ] [ default { _progdefault_... } ] ... } _prog... ``` -------------------------------- ### Shell Execution of Foreground Command with Blocks (Quoted Arguments) Source: https://skarnet.org/software/execline/el_semicolon Shows how to execute the 'foreground' command from a shell, replicating the block syntax. Arguments within the block are quoted, and the block is terminated by an empty word (''). ```shell $ foreground ' echo' ' 1' '' echo 2 ``` -------------------------------- ### execline `shift` program interface Source: https://skarnet.org/software/execline/shift Illustrates the command-line interface for the `shift` program, specifying optional arguments for controlling the number of positional parameters and blocks to shift before executing the target program. It highlights the default behavior when options are omitted. ```execline shift [ -n _argn_ ] [ -b _blockn_ ] _prog..._ ``` -------------------------------- ### heredoc Program Interface and Usage Source: https://skarnet.org/software/execline/heredoc Describes the command-line interface for the heredoc program, including its arguments and options. It explains how heredoc executes a program with a given string available on a specific file descriptor. The -d option is also detailed for running the feeding process as a grandchild to prevent zombies. ```bash heredoc [ -d ] _fd_ _string_ _prog... # Example usage: # heredoc 3 "hello world" sh -c 'cat <&3' # This would run 'sh -c "cat <&3"' and feed "hello world" to file descriptor 3. ``` -------------------------------- ### execlineb Script with Foreground Command Source: https://skarnet.org/software/execline/el_semicolon Demonstrates the use of blocks in an execlineb script. The 'foreground' command uses a block for the first command ('echo 1') and executes the second command ('echo 2') directly. ```execlineb #!/command/execlineb foreground { echo 1 } echo 2 ``` -------------------------------- ### execlineb Command Usage Source: https://skarnet.org/software/execline/execlineb Shows the different ways to invoke the execlineb program, either with a script provided via -c, a script file, or as a shebang in an executable file. ```APIDOC ## execlineb Command Usage ### Description This section outlines the various syntaxes for invoking the `execlineb` program. ### Method N/A (Command-line utility) ### Endpoints N/A (Command-line utility) ### Parameters #### Common Options: - `-q`, `-w`, `-W`: Warning/quiet flags (specific behavior not detailed). - `-p`, `-P`, `-S _nmin_`, `-s _nmin_`: Options related to environment stack frame management. - `-e`: Ignored option, for compatibility with shell scripts. #### Execution Modes: 1. **Using `-c` option:** ``` execlineb [ -q | -w | -W ] [ -p | -P | -S _nmin_ | -s _nmin_ ] [ -e ] -c _script_ [ _args..._ ] ``` * **Description**: Executes the provided `_script` string directly. 2. **Using a script file:** ``` execlineb [ -q | -w | -W ] [ -p | -P | -S _nmin_ | -s _nmin_ ] [ -e ] _scriptfile_ [ _args..._ ] ``` * **Description**: Reads and executes the script from the specified `_scriptfile`. 3. **As a shebang in an executable file:** ``` #!/command/execlineb [ -qwWpPS_nmin_ ] _script_ ``` * **Description**: The first line of an executable script, specifying `execlineb` as the interpreter. ### Request Example N/A ### Response #### Success Response - Exit code 0: If the executed `argv` is empty. - Other success exit codes depend on the executed command. #### Error Responses: - Exit code 100: Syntax error in the script or unmatched braces. - Exit code 111: Temporary error during parsing. #### Response Example N/A ``` -------------------------------- ### Execline Recursive Substitutions with Multiple Keys Source: https://skarnet.org/software/execline/el_substitute Demonstrates how execline performs recursive substitutions when multiple keys are present in a single word and their values are split. Substitutions are processed in parallel from left to right. ```execline #!/command/execlineb define -s B "1 2 3" echo ${B}x${B} ```