Structure of thi-scripts

directories

Directories contain the following files:

  1. header (see later)
  2. dirlist
  3. filelist

dirlist and filelist are files containing the files or directories of the thi-script, respectively. The syntax is as follow:

file;UUID;tags ...;title

file
the filename
UUID
the unique idenfication number for reference
tags ...
list of tags
title
the title of the thi-script displayed

When thi-script reads a line from dirlist or filelist, the line is 'evaled', so that variables can be used as reference...;)

files

thi-scripts (files) are tar.gz files containing the following files and folders:

header
A file; contains title, tags, and other vars
main
A file; contains the main part of the thi-scripts incl. commands
commands /
A folder; contains commands for @cmf- and @cma-statements
variable.d /
A folder; contains files with possible values for variables
prescripts.d /
A folder; contains scripts that are executed just before the thi-script is displayed

The 'header' file

The header file defines the following variables:

ENCODING="ISO-8859-1"
TYPE=file|directory
TITLE="this is the title"
TAGS="some additional keywords to find"
UUID="a uniq identification number"
GROUP="an optional group name"

ENCODING
not used at present
TYPE
The type of thi-script, 'file' or 'directory'
TITLE
The title of the thi-script
TAGS
tags for search purpose
UUID
unique identifier for the thi-script
GROUP
An optional group name. thi-scripts with the same group share the same variables. This allows to set a variable in one thi-script and use it across many other thi-scripts.

The 'main' file

The file 'main' contains the text to be displayed. Colours and styles can be used (see below). tree types of commands (see below).

The commands directory

The commands directory contains the scripts for the @cma- and @cmf-statements.

The variable.d directory

Directory variable.d ($VARDLOCAL) contains files with predefined values for variables. The file containing the predefined values for a variable equals the variable name, e.g. variable '$MYVAR' will have an file MYVAR (no dollar sign) in the variable.d directory. Every variable that should be editable has to have at least an empty file in variable.d ($VARDLOCAL) named after itself. If there is no file with the variable name, the corresponding variable cannot be changed.

Every line in the variable file equals one possible value.
The first line is used as default value.

Restricting values to the values in the variable file is not possible.

Values added by the user are stored $VARIABLED. ($VARIABLED is made of  $VARDGLOBAL/<group>, or - if the group is not set - $VARDGLOBAL/<uuid>)

Note on groups:
Groups share the same variables. A value set in one thi-script will be set in other thi-scripts with the same group. However, if you create different thi-scripts and each has its own section of variable values, these values will just be available after every thi-script has been evoked. If it is not clear which thi-script will be executed first, better put the same variable file into each thi-script, so that all thi-script have all values at their disposal.

The prescript.d directory

Directory 'prescript.d ($PRESCRIPTD) contains scripts to be executed just before the thi-script is displayed.
Prescripts can be used to create possible values for variables or files to be used by the script or even create a file that is included as a part of the script itself (on-the-fly creation of thi-script).

Creating variables with prescripts

The script `users.sh' placed in prescript.d will create a list with all real users:

#!/bin/bash
awk -F : '$3>999 {print $1}' /etc/passwd >$VARDLOCAL/USER

The output of the script is redirected to the variable.d directory holding the variables. The variable $USER gets a list of real users to choose from.

Commands

There are three types of thi-commands:

  1. cmd: command
  2. cmf: link to file
  3. cma: command look alike

cmd - command

Syntax:

@cmd:<comment>:command(s)
[... command(s)] @![end-of-line]

The @cmd-statement can have one or many lines of commands.

The @cmd-statement is terminated with @! at the end of line (exact end of line).

The @cmd-statement might have a comment in <comment>-section.

cmf - link to file

Syntax:

@cmf:<comment>:script.sh

The @cmf-statement points to a script. Useful to control execution of various scripts from a . The path for scripts is relative to $CMDDIR, the `commands' directory. With full path, any script can be executed.

'x' toggles between showing the file name and the script's content.

cma - command look alike

Syntax:

@cma:[<filename>]: <command look alike> @!

The @cma-statement is a kind of alias command:  The command to be executed lies in a file (script), the text that is shown follows after the ':'.

Special characters in the command line are sometimes not shown properly. E.g., '\n' leads to a new line, instead of being shown as '\n' . @cma-statements can avoid that by separating text displayed and command executed.

You cannot toggle a @cma-statement.
Alias commands are marked with a '!'.

Scripts are sourced for execution, therefore internal variables are set.
Without a filename, cma is a dummy command. It will just set the formatting (red, numbering).

Curly braces

{{@?:<ask>}}

The ask-statement prompts with text <ask> for an input from the user before command execution. The braces are replaced by the text entered.

{{@f?:<ask>}}

The ask-f-statement is same as the ask-statement but prompts with interactive shell filename completion. (using read -e)

{{@file:<file>}}

The @file-statement inserts a file exactly at this position of itself. 'z' toggles between showing the file name or the file's content.

{{@ref:<UUID>:<comment>}}

The @reference statement points to another thi-script with uuid UUID. This allows to point to a thi-script wherever it is located inside the thi-directory hierarchy.

{{@include:<file>}}

The @include statement will include the file <file> into the thi-script as if it were part of the thi-script itself.

The file is included after the scripts in prescript.d/ are executed. This allows for on-the-fly creation of commands, either by scripts in prescript.d or through a command inside the thi-script. E.g. the first command creates more thi-commands after prompting the user for some input. This is a rather advanced options, but allows for amazing complexity ...

{{@command:<command ...>}}

The @command-statement will execute the <command(s)> and insert the command's output at its place. @command-statements are not allowed to contain '}' and are not included in thi-commands. For that, use @include and prescripts.

tmf

'tmf' stands for thi-menu-function. It offers what `select .. in` is doing but much more. The most simple invocation mimics `read ; echo $REPLY`, the same as {{@?:<ask>}}. tmf prints a list on stderr and prompts for the user to choose an entry from the list. The choice is printed on stdout.

OPTIONS

-e
use Readline to obtain the line in an interactive shell (`read -e`)
-n
return line number where line is found in file instead of string (only with -f file).
-p PROMPT
prompt with string PROMPT (`read -p PROMPT`)
-f FILE
FILE is printed on the standard error, each line preceded by a number. If -p is given, PROMPT is displayed and a line is read from the standard input. If the line consists of the number corresponding to one of the displayed lines, tmf prints the line on standard output and exits. If the line is empty or not a number, FILE and the prompt are redisplayed.
Input of 0 terminates immediately without any output.
-a STRING
STRING is echoed on stderr. Then as in -f.
-l REGEX
`ls REGEX` is executed and redirected to a file. Then as in option -f. Use `-l .` to execute ls for pwd without any argument.
-a STRING
STRING is echoed on stderr. Then as in -f.

examples

tmf

just prompt for input

tmf -p "enter value: "

... with prompt

tmf -e -p "enter file: "

readline (file completion)

tmf -l \*.pdf

list pdf files of present working directory to choose from (nb:mind escaping the '*' asterix).

tmf -p "choose user: " -a "$(sort -n -t ':' -k 3 /etc/passwd | sed -rn '/([^:]*):x:[0-9]{4,}:/{s|:.*||p}')"

list of real users to choose from