General options¶

Basic features¶

On debian systems the following described script hello_world may be found at /usr/share/doc/shellia/examples/hello_world.

If called without option, it will just print the words hello and world:

$ /usr/share/doc/shellia/examples/hello_world
hello
world

If called with option -i, you will have some interactive choices:

$ /usr/share/doc/shellia/examples/hello_world -i
=== hello_world ===
1 echo "hello"
2 echo "world"
c continue without questionsq quit
? [1]

Entering 1 would execute the first step and print the word hello. Actually, because 1 is preselected as shown in the last line, just entering RETURN, would do the same. Step 2 is equivalent to step 1. After step 2 the preselection would change to q. q means quit and can be pressed anytime to leave the current step level, Which would leave the shell script in our case. Instead of entering 1, 2 and q, c could have been entered to continue automatically.

A discussion of the source of this shell script can be found in shellia(3) Basic features.

Interactive-mode¶

In Basic features all steps shown in Interactive-mode have been at the same level. In Interactive-mode muliple levels are supported.

On debian systems the following described script hello_world_fun may be found at /usr/share/doc/shellia/examples/hello_world_fun.

If called without shellia specific option, but with the name "Test User", the output will be:

$ /usr/share/doc/shellia/examples/hello_world_fun "Test User"
hello Test User

If additionally called with option -i, you will have some interactive choices:

$ /usr/share/doc/shellia/examples/hello_world_fun -i -- "Test User"
=== hello_world_fun ===
1 say_hello -i -- "Test User"
i toggle -i flag
q quit?
[1]

Entering i turns -i on and off as shown above and in the next line:

1 say_hello -- "Test User"

If we would press 1 while -i is off, the function say_hello would be executed at once. Pressing 1 while -i is on would start function say_hello in interactive-mode and display the following menu with steps in a deeper level:

=== hello_world_fun/say_hello ===
1 name="Test User"
2 echo "hello $name"
c continue without questions
q quit?
[1]

In the heading we can see, the name of the current function. Because we have to start with the first step in this function again 1 is preselected. To run all steps in this function we can press c. After executing, we will return to the previous menu and can press RETURN to select the preselected quit.

A discussion of the source of this shell script can be found in shellia(3) Interactive-mode.

Debug-mode¶

Each debug-statement in a script-using-shellia has additionally to the debug-output a debug-statement-level, and a debug-statement-topic with the defaults 1 and none.

At runtime the script gets a debug-runtime-level and a debug-runtime-topic list with the defaults 0 and empty.

The debug-output will be shown if the, the debug-runtime-level is higher or equal to the debug-statement-level and either the debug-statement-topic is in the debug-runtime-topic list, or the debug-runtime-topic list is empty.

On debian systems the example script hello_world_debug may be found at /usr/share/doc/shellia/examples/hello_world_debug.

In the header of the script we can read, that the used debug-topics are none, start and end and that the higest debug-level is 3.

To see all debug-output we can start with an empty debug-runtime-topic list and the very high debug-runtime-level 99:

$ /usr/share/doc/shellia/examples/hello_world_debug -d 99
DEBUG main program
DEBUG say_hello function start
hello world
DEBUG say_hello function end

To see only the debug-topics none and start in interactive-mode we can call:

$ /usr/share/doc/shellia/examples/hello_world_debug -d "99 none start"
=== hello_world_debug ===
1 dbg "main program"
2 say_hello_world
d ... change dbg: 99 none start
c continue without questions
q quit
? [1]

If we now change our mind, to not see the debug-topic start anymore and to change the debug-level 2 we can change this by entering d start 2 before continuing with c:

? [1] d start 2
=== hello_world_debug ===
1 dbg "main program"
2 say_hello_world
d ... change dbg: 2 none
c continue without questions
q quit
? [1] c
DEBUG main program
hello world

The interactive-mode can be used to turn on debug-output only in steps where we need it.

Log-mode¶

If the script-using-shellia creates a logfile as described in shellia(3) logfile-mode, the created logfile has some features as shown in the example script hello_world_log. On debian systems it may be found at /usr/share/doc/shellia/examples/hello_world_log. The example script will automatically display the logfile at the end.

First we call it without options:

$ /usr/share/doc/shellia/examples/hello_world_log "shellia user"
hello shellia user
--- LOGFILE ---
|hello_world_log
||hello_world_log/say_hello
||s:hello shellia user
---------------

The first line shows how the script is called. The second line shows the output of the script hello shellia user Then the logfile is displayed in two lines starting with dashes. The first line of the logfile has one bar, indicating that we are in the first level, which is the main script in file hello_world_log The second line of the logfile has two bars, indicating we are in the next level, followed by the filename and the function name. The third line is from the same function and show with an s:, that stdout hello shellia user has been created by this function.

We will now run the same script with all debug output enabled to see debug information with the word DEBUG added

$ /usr/share/doc/shellia/examples/hello_world_log -d 99 "shellia user"
DEBUG main program begin
DEBUG function say_hello called with 1 arguments
hello shellia user
DEBUG function say_hello end
DEBUG main program end
--- LOGFILE ---
|hello_world_log
|DEBUG main program begin
||hello_world_log/say_hello
||DEBUG function say_hello called with 1 arguments
||s:hello shellia user
||DEBUG function say_hello end
|DEBUG main program end
---------------

Another way is to start in interactive mode, manually select the function with 2, continue all steps in the function with c and then quit with q. Now also the interactive input and output will be logged and the logfile will be too large, to display it here.

variable in Interactive-mode¶

If you see $<var> in interactive mode, the meaning is like \${var}, but you can press v to see the actual value of the variable. If you press v again, the name of the variable is shown as before.