| [Top] | [Contents] | [Index] | [ ? ] |
1. The Concepts of Kaptain 2. Invoking Kaptain 3. Grammar Scripts 4. Examples 5. External Control 6. Errors 7. Reference of Special Symbols A. Reference of Modifiers Concept Index Concept index.
This is a manual for Kaptain, the Universal Graphical Front-end.
Copyright © 2000-2003 Zsolt Terék
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Kaptain is a universal graphical front-end. It was originally developed in order to provide a simple and efficient tool for creating dialog-based interface for command line programs. Now, its communication features allow it to serve the graphical user interface of a program without directly using a graphical library, such as GTK or Qt.
When Kaptain is started, it reads a so-called grammar script. This is a text file, which contains a description in a form of a context-free grammar and optionally some other instructions. This manual refers to the input file of Kaptain as a grammar script. See 3. Grammar Scripts for a complete overview on grammar script syntax.
According to the grammar script, Kaptain builds a graphical dialog box. Certain parts of the dialog box are associated with certain elements of the grammar. This association is quite natural, thats why Kaptain's language is so easy to learn.
In the dialog box, several widgets are present. These objects can be manipulated by the user--text can be entered into input fields, checkboxes can be set on and off. When a certain push button is pressed, Kaptain reads the data specified by the user in the dialog box and uses the context-free grammar to generate text. The generated text is then executed as a command, just like as if it were entered at the command prompt.
Suppose we have a program named prog that runs in two different
modes. For its first mode, an integer parameter should be given, and the
second mode needs some text as parameter. An example for starting
prog in its first mode:
start -> "prog " parameter ; parameter -> "-x " @integer | "-y " @string ; |
The grammar in the example above is almost enough for Kaptain to build a dialog containing an integer input box and a string input field, each having a radio button. Additionally a push button is needed and some text might be specified in order to label the input fields.
Given a file containing such a description, Kaptain parses the grammar and builds a dialog box. When the push button is pressed, the text is generated according to the settings of the user.
The complete grammar for the program above might look like this:
start -> "prog " parameter @action(start)="Ok"; parameter -> x | y ; x "First mode" -> "-x " @integer; y "Second mode" -> "-y " @string; |
According to the settings in the figure, the generated text is `prog -x 0', since the first radio button is selected.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Kaptain needs a grammar script in order to display the dialog. This is usually located in a file, and the name of that file is passed to Kaptain as an argument. The grammar script can be written to the standart input of Kaptain, too.
The running mode of Kaptain can be normal or test mode. In test mode, commands are not executed, they are printed to the standard output instead.
The command line of Kaptain generally looks like this:
Kaptain [options] file |
Some options are used to specify running mode, while others set up different kinds of communication channels for external control. Kaptain accepts the following switches and parameters:
These are the possible parameters and options accepted by Kaptain called from the command prompt.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The input file of Kaptain is a grammar script. It contains the description of a context-free grammar in a form of rules. Beside the rules, it might also contain so-called descriptions and constraints.
Comments can be placed in grammar scripts. Hashmark (`#') is a comment character, which means that all characters after the hashmark up to the end of the line are ignored together with the hashmark. This is not true if the hashmark appears inside a quoted string, see 3.3 Quotations.
3.1 Grammars 3.2 Special symbols 3.3 Quotations 3.4 Regulas expressions and translations 3.5 Using text manipulation in grammar rules
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The program Kaptain reads an input file containing the description in the form of a context-free grammar. The concept of context-free grammar is coming form formal linguistic. A grammar is built up of several rules. Each rule contains a left hand side symbol and some symbols on the right hand side separated by an arrow:
start -> "progname" options parameters ; |
Nonterminal symbols are similar to variables in other programming languages. Their name can contain alphanumeric characters and underscore, and should not begin with numbers.
Terminal symbols are written between quotation marks. Kaptain has many ways for specifying terminal symbols, see 3.3 Quotations
The text generation process is an iterated application of rules on the current sentence. Starting from the nonterminal symbol `start', every step consists of an application of a rule. This means that a nonterminal symbol in the current sentence--which is the left hand side of the applied rule--is replaced by the symbols on right hand side of the rule. This process ends if there are no more nonterminal symbols in the current sentence.
To illustrate text generation, let us have the following grammar:
start -> "Your " animal "is " size ; animal -> "dog " ; animal -> "cat " ; size -> "big." ; size -> "small." ; |
Starting with the sentence `start', only the first rule can be applied. The current sentence is then `"Your " animal "is " size'. Here both `animal' and `size' is nonterminal, thus any of the rules but the first can be applied. This way exactly four different sentences can be generated by this grammar:
Your dog is big. Your cat is small. Your dog is big. Your cat is small. |
As a syntactic simplification, different rules of the same left hand side can be written in one complex rule using `|' character as a separator of the different right hand sides. The grammar above is equivalent to the following:
start -> "Your " animal "is " size ; animal -> "dog " | "cat " ; size -> "big." | "small." ; |
The set of sentences that can be generated using a certain grammar is called the language generated by that grammar. Formal languages is a branch of mathematics that deals with languages and grammars.
3.2 Special symbols
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The expression power of grammars is great. However, sometimes it is quite comlicated to express simple things. For example, the definition of numbers is quite long and messy: (Of course, it is possible to write a different grammar for the numbers, this is not a unique definition.)
number -> digits ;
digits -> digit digits | digit ;
digit -> "0" | "1" | "2" | "3" | "4"
| "5" | "6" | "7" | "8" | "9" ;
|
Beside terminal and nonterminal symbols, Kaptain offers so-called special symbols to appear in grammars. Special symbols always start with `@'. Such a symbol almost always refers to a widget in the dialog. For example `@integer' represents a widget, which is a rectangular area where the user can write a decimal number. The special symbol evaluates to the value that it contains at the time of the text generation process.
Special symbols may accept different number of parameters and an optional initial value. The general form is as follows:
@specname(param_1, param_2, ..., param_n)=initvalue |
@specname @specname=initvalue @specname(param_1, param_2, ...) @specname(param_1, param_2, ...)=initvalue |
The complete reference of special symbols can be found in 7. Reference of Special Symbols.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
\n, \t, \", \\. Other characters
are not modified if preceeded by backslash. This way one can place
double quote character inside a string:
"Double quotes \" are easy to write." |
Double quotes " are easy to write. |
An other meta-character is the dollar sign ($), which is used for
inserting environmental variables into strings. For example in
"$HOME/hello" the sequence $HELLO is replaced by the
content of the HELLO environmental variable. If the environmental
variable name contains other characters than letters, the following form
should be used: ${ANY89}.
This kind of quotation should always end on the same line it was started. If the end-of-line symbol is reached within the string, Kaptain prints a warning.
'No way to have apostrophes in this string' |
`ls`
evaluates to a string which contains the file names of the current
directory. An easy way to create a list box containing the available
files is the following:
@list(`ls`) |
ls returns the files separated by a newline symbol,
`@list' inserts the different lines of its parameter value as
different list items. See section 7. Reference of Special Symbols.
The commands are passed to `/bin/sh', so any shell constructions can be given, e.g., pipes.
Using backquots is a strong form of quoting: there are no special characters. As a consequence of this, no backquote (`) can appear inside.
q%any characters except the delimiter% |
any characters except the delimiter |
% can be replaced by any
except the following: letters, numbers, ;().=:_- and
whitespace.
The letter `q' at the beginning stands for quotation.
x%shell command line not containing the delimiter% |
shell command line not containing the delimiter |
When Kaptain parses two less signs (<<), the text up to the end of the
line is stored as a delimiter string and it starts to scan a quotation.
The quotation is ended if a line occurs that is exactly same as the
delimiter string.
... <<LINE_DELIMITER Here goes the long text LINE_DELIMITER |
Here goes the long text |
<< sequence needs not to be on the
beginning of a line. The quotation above is equivalent to the following:
... "Here goes\nthe long text" |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
3.4.1 Regular expressions 3.4.2 Substitutions 3.4.3 Transliterations
All expressions mentioned here use / (slash) as bounding
character. This can be replaced by any expect letters, numbers, blanks,
underscore, hyphen and semicolon. But the beginning and the ending
bounding characters must be the same, there is no way to refer to that
character inside the expression. For example, instead of
m/hello/, one can write m%hello%, m^hello^, and so
on.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Kaptain understands regular expressions like grep or perl. For a
detailed review, type man grep or man perlre at the
command prompt. You can give a regular expression as a parameter to some
special symbols, like this:
@string(m/$[0-9]*^/, ... |
Here m/$[0-9]*^/ means that the string value in the input line
must match the corresponding regular expression. In this
particular case, this means the user can only type integers into the
line input field.
When parentheses are found in the regular expression, a subexpression is
matched which can be referred with \d where d is a
digit. (\1, \2, ... \9) For example:
@multicol(m/([^[:blank:]]*)[[:blank:]]+([^[:blank:]]*)/,
"First_name Last_name",
"Albert Einstein Dr.", "Isaac Newton", "Rudolf Kepler")
|
"Dr." in line "Albert Einstein Dr." is not
matched by the second subexpression, so it is not displayed.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Substitution is based on regular expression matching just like in perl or sed. (For some metacharacters, sed uses different syntax.) Substitution expression needs a regular expression and a substitution string as an input:
s/regexp/subs/ |
For example, to replace the words "dog" in a text to "cat, just write
s/dog/cat/g. That g at the end means that substitution is
repeated until the regular expression cannot match. In the second part,
you can refer to the matched subexpressions by \d, where d
is a digit. \0 refers to the whole matched string. Thus the
following swaps the first two words in the text:
s/([^[:blank:]]*)[[:blank:]]+([^[:blank:]]*)/\2 \1/ |
You can use it in listbox:
@list(s/([^[:blank:]]*)[[:blank:]]+([^[:blank:]]*)/\2 \1/,
"Albert Einstein Dr.", "Isaac Newton", "Rudolf Kepler")
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Transliteration is a very simple operation which replaces some characters with some others.
tr/abc/def/ |
a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces a with d, b with e, cE>\0This replaces