File: intro-3.html

package info (click to toggle)
linuxconf 1.26r4-2
links: PTS
area: main
in suites: woody
size: 56,432 kB
ctags: 27,217
sloc: cpp: 158,803; perl: 7,484; sh: 4,134; java: 3,105; ansic: 2,492; makefile: 2,216; python: 109
file content (688 lines) | stat: -rw-r--r-- 21,778 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
 <TITLE>shellmod: Protocol</TITLE>
 <LINK HREF="intro-4.html" REL=next>
 <LINK HREF="intro-2.html" REL=previous>
 <LINK HREF="intro.html#toc3" REL=contents>
</HEAD>
<BODY>
<A HREF="intro-4.html">Next</A>
<A HREF="intro-2.html">Previous</A>
<A HREF="intro.html#toc3">Contents</A>
<HR>
<H2><A NAME="s3">3. Protocol</A></H2>

<P>we will now present the various commands issued by the script. Those
commands will be split by task
<P>
<H2><A NAME="ss3.1">3.1 Command layout and quoting</A>
</H2>

<P>All command sent to shellmod are done using the echo shell command. They
always looks like:
<P>
<BLOCKQUOTE><CODE>
<PRE>
        echo command arg1 arg2 arg3
        
</PRE>
</CODE></BLOCKQUOTE>
<P>Arguments are either a single or multiple words (separated with spaces).
To group multiple words as a single argument, quotes must be used.
While this is standard command line practice, there is a catch: Quoting
will only affect the argument as seen by the <CODE>echo</CODE> command.
Once process, the whole line will be received as a single stream of
words separated by space and the quote will be gone. The quotes must
be part of the line received by shellmod. Here is an example
<P>
<BLOCKQUOTE><CODE>
<PRE>
        echo newf_str name \"Enter your name\" \"Tux the penguin\"
        
</PRE>
</CODE></BLOCKQUOTE>
<P>The shellmod-lib.sh define the <CODE>qecho</CODE> helper function you may used to get
a more standard shell quoting behavior. Here the same example rewritten
with <CODE>qecho</CODE>.
<P>
<BLOCKQUOTE><CODE>
<PRE>
        qecho newf_str name "Enter your name" 'Tux the penguin'
        
</PRE>
</CODE></BLOCKQUOTE>
<P>As you see, with <CODE>qecho</CODE> you can mix the different shell
quoting syntax. The <CODE>qecho</CODE> function insures that proper
double quotes surround all arguments.
<P>
<P>
<H2><A NAME="ss3.2">3.2 Sending multi-line parameters</A>
</H2>

<P>Shell scripts are not that good at handling and passing
multi-line text. The "defval" command was created to fix that.
Here is a typical usage:
<P>
<BLOCKQUOTE><CODE>
<PRE>
        echo var1 "This is the first line"
        echo var1 "This is the second line"
        echo error =var1
        
</PRE>
</CODE></BLOCKQUOTE>
<P>This creates a popup error message with two lines. "defval" is used
repeatedly to define the multi-line text and is referenced as an
argument using the = sign. The argument must not be quoted. So you
can't use the qecho helper function using a defvar parameter, because
qecho insures quoting around all parameters.
<P>
<H2><A NAME="ss3.3">3.3 Building a dialog</A>
</H2>

<P>
<P>
<H3>echo DIALOG</H3>

<P>A dialog always starts with this command. It requires no further argument.
Then you stuff it with field definitions, add optional buttons
and then you call the edit function. Here is a sample:
<P>
<BLOCKQUOTE><CODE>
<PRE>
        echo DIALOG
        echo newf_str var \"field title\" value
        edho edit \"Dialog title\" \"Dialog introduction\"
        dispatch
        echo end
        
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H3>echo settype DIATYPE_POPUP</H3>

<P>This requires the window manager to present this dialog as an
independant window in the middle of the screen. This is usually
used for transient dialog requiring immediate attention
from the user.
<P>
<H3>echo edit \"title\" \"Introduction\" [ \"button,button,...\" ]</H3>

<P>This pops up the dialog. The window title control using the
first argument and the longer dialog description is controlled
by the introduction field.
<P>The last argument is option and lets you control the buttons
displayed at the bottom of the dialog. The value "0" means to
display no button (useful to display some gauge for example).
<P>When the last argument is omitted, the button Accept and Cancel are
displayed.
<P>
<H3>echo show \"title\" \"Introduction\"</H3>

<P>This works like edit. It pops up the dialog with the same arguments.
But it return immediatly. This is generally used with the 
<A HREF="#newf_gauge">newf_gauge</A>
command.
<P>
<H3>dispatch</H3>

<P>This yield control to Linuxconf/shellmod and wait for results.
Field variable are updated and the CODE variable is set to the
button value selected by the user: This is either "accept" or
"cancel".
<P>
<H3>echo end</H3>

<P>This deletes the dialog. It is removed from the screen and
forgotten. We often issue the end command right after the
dispatch command. But more complex dialog may use the end
command after a validation loop.
<P>
<H3>A complete example</H3>

<P>
<BLOCKQUOTE><CODE>
<PRE>
#!/usr/bin/shellmod
. /usr/lib/linuxconf/lib/shellmod-lib.sh
main(){
        echo DIALOG
        echo newf_str name \"User name\"
        while true
        do
                echo edit \"User query\" \"Enter the user name\"
                dispatch
                if [ "$CODE" = "cancel" ] ; then
                        break
                elif [ "$name" = "" ] ; then
                        echo error \"Please provide a name\"
                else
                        echo notice \"Doing something with the user account\"
                        break
                fi
        done
        echo end
}
dispatch
        
</PRE>
</CODE></BLOCKQUOTE>
                        
<P>
<H2><A NAME="ss3.4">3.4 Building a menu</A>
</H2>

<P>This is handled by the DIALOG_MENU and new_menuitem commands.
<P>
<H3>echo DIALOG_MENU</H3>

<P>This does not require any argument.
<P>
<H3>echo new_menuitem function prompt title</H3>

<P>This records one menu entry. Each menu entry is associated
with one script function (that must be defined). The prompt
is generally a keyword. The title is the rest of the menu entry.
<P>
<H3>echo editmenu \"Menu title\" \"Introduction\"</H3>

<P>This pops the menu. It is followed by a call to dispatch.
<P>
<H3>dispatch</H3>

<P>This is where everything is done for a menu. The dispatch
function will run until the user select the "quit" button.
The corrresponding function is called whenever a menu entry
is selected. This is handled transparently by the dispatch
function.
<P>Note that the dispatch function also exits if the user
select an optional buttons (added with the button command).
So it is possible to handle a in a loop like the example
dialog above.
<P>
<H3>echo end</H3>

<P>This deletes the menu.
<P>
<H3>A complete example</H3>

<P>
<BLOCKQUOTE><CODE>
<PRE>
#!/usr/bin/shellmod
. /usr/lib/linuxconf/lib/shellmod-lib.sh
menufunc1(){
        echo notice \"menufunc1 selected\"
}
menufunc2(){
        echo notice \"menufunc2 selected\"
}
main(){
        echo DIALOG_MENU
        echo new_menuitem menufunc1 Select \"First option\"
        echo new_menuitem menufunc2 \"\" \"Second option\"
        echo editmenu \"Main menu\" \"Pick an option\"
        dispatch
        echo end
}
dispatch
        
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="ss3.5">3.5 Managing a list of records</A>
</H2>

<P>
<H3>echo DIALOG_LIST</H3>

<P>A DIALOG_LIST is just a variation of a menu. The main difference
is that the number of entry might be very long. In that case
a filter dialog will popup so restrict the amount of diaplayed
record. You can deal with very large list of item.
<P>DIALOG_LIST does not require any argument.
<P>
<H3>echo newf_head \"Column1 title\" \"Column2 title\" ...</H3>

<P>You can define the heading of the list. This is optional, but
looks much more nicer.
<P>
<H3>echo new_menuitem \"function args\" \"Column1 value\" \"Column2 value\" ...</H3>

<P>It works like DIALOG_MENU, except that we often supply more columns.
There is another variation as the function is defined with arguments.
Note that this may be used with DIALOG_MENU as well. We generally
define one function per menu entry and a single function to
process each record of the list, using the argument to
differentiate the processing.
<P>Note also that you can use a mixed solution within the same DIALOG_MENU
or DIALOG_LIST: You can use a single function to provide
a common processing for some record and different function
to manage exception.
<P>
<H3>echo editmenu \"List title\" \"Introduction\"</H3>

<P>Same as with DIALOG_MENU.
<P>
<H3>dispatch</H3>

<P>This behave like the DIALOG_MENU.
<P>
<H3>echo end</H3>

<P>This delete the list.
<P>
<H3>A complete example</H3>

<P>Here is a realistic example where we display a directory
and let the user pick one file and do something with it.
We see in this example how easy it is to parse the output
of the "<CODE>ls -l</CODE>" command and present the file name, the
size and revision date in three formatted column.
<BLOCKQUOTE><CODE>
<PRE>
#!/usr/bin/shellmod
. /usr/lib/linuxconf/lib/shellmod-lib.sh
fileshow(){
        echo notice \"Processing file $1\"
}
main(){
        echo DIALOG_LIST
        echo newf_head \"File name\" Sise \"Revision date\"
        ls -l $1 | \
                (
                read total
                while read perm count user group size month day hour name
                do
                        echo new_menuitem \"fileshow $name\" $name $size \"$month $day $hour\"
                done
                )
        echo editmenu \"Current directory\" \"This show all file in the current directory\"
        dispatch
        echo end
}
dispatch
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="ss3.6">3.6 Defining fields</A>
</H2>

<P>All commands defining a dialog field start with the prefix <CODE>newf_</CODE>.
We have used the same name and same parameter order (when possible)
as the C++ module API.
<P>The first argument is always the name of the shell variable which
will receive the value entered by the user. You will often use
the following construct to edit (correct the current value) of a
given variable.
<P>
<BLOCKQUOTE><CODE>
<PRE>
        qecho newf_str var "title" "$var"
        .
        qecho edit ...
        dispatch
        if [ "$CODE" = "accept" ] ; then
                if [ "$var" = "..." ] ;then
                        .
                        .
                fi
        fi
        
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="ss3.7">3.7 Command list</A>
</H2>

<P>Here is the list of all field definition commands:
<P>
<UL>
<LI>
<A HREF="#newf_chk">newf_chk</A></LI>
<LI>
<A HREF="#newf_chkm">newf_chkm</A></LI>
<LI>
<A HREF="#newf_combo">newf_combo</A></LI>
<LI>
<A HREF="#newf_dbl">newf_dbl</A></LI>
<LI>
<A HREF="#newf_enum">newf_enum</A></LI>
<LI>
<A HREF="#newf_gauge">newf_gauge</A></LI>
<LI>
<A HREF="#newf_hexnum">newf_hexnum</A></LI>
<LI>
<A HREF="#newf_list">newf_list</A></LI>
<LI>
<A HREF="#newf_num">newf_num</A></LI>
<LI>
<A HREF="#newf_pass">newf_pass</A></LI>
<LI>
<A HREF="#newf_radio">newf_radio</A></LI>
<LI>
<A HREF="#newf_slider">newf_slider</A></LI>
<LI>
<A HREF="#newf_str">newf_str</A></LI>
<LI>
<A HREF="#newf_title">newf_title</A></LI>
</UL>
<P>
<P>
<P>
<H3><A NAME="newf_chk"></A> echo newf_chk var \"field title\" \"Initial 0 or 1 value\" \"Suffix title\"        </H3>

<P>Setup a check box field (on/off or yes/no). The variable var will
be setup to either 0 or 1. This field has two title. One on the left
of the check box and one on the right. This is often used like this
in Linuxconf:
<P>
<BLOCKQUOTE><CODE>
<PRE>
        The current feature [ ] is selected
        
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H3>Variation of the newf_chk syntax</H3>

<P>When using newf_chk, you must pass a 0 or 1 as the value. The edit variable
will receive the result as 0 or 1. This is not so useful as often
shell script are dealing with different type of boolean value. For
example, a script dealing with an SQL server may find itself dealing
with Y and N values. To avoid translating from one system to the
other, the syntax of the initial value has been expanded.
<P>
<UL>
<LI>To make things easy, shellmod will accept as a selected value
anything in 1,Y and Yes (case insensitive). Unless told
differently, these values will be translated to 1. Anything else
will be translated to 0.</LI>
<LI>By using a special triplet format, one can specify the actual
value and the dictionary used to interpret it. You specify
the value like this:

<BLOCKQUOTE><CODE>
<PRE>
                value:on_value:off_value
                
</PRE>
</CODE></BLOCKQUOTE>


So if you application is dealing with ON/OFF values, you can specify
the initial value like this:

<BLOCKQUOTE><CODE>
<PRE>
                $var:ON:OFF
                
</PRE>
</CODE></BLOCKQUOTE>


Not only ON and OFF will be accepted to interpret the value, but
the end result will be sent to the script using one of those
word.</LI>
</UL>
<P>
<H3><A NAME="newf_chkm"></A> echo newf_chkm var \"field title\" \"Initial numeric value\" \"value1\" \"value2\" ...        </H3>

<P>Setup of multiple selection field using check boxes. The boxes are
presented horizontally. Here is an example followed with
the field it produced in text mode:
<P>
<BLOCKQUOTE><CODE>
<PRE>
        echo newf_chkm sel \"Which position\" 1 left center right
        
</PRE>
</CODE></BLOCKQUOTE>
<P>This produces:
<P>
<BLOCKQUOTE><CODE>
<PRE>
        Which position    ( ) left  (o) center ( ) right
        
</PRE>
</CODE></BLOCKQUOTE>
<P>The variable var will take the numerical index of the selected item,
starting at 0.
<P>
<H3><A NAME="newf_combo"></A> echo newf_combo var \"field title\" \"Initial value\"        </H3>

<P>Setup a single line + selector field. The user will be able to pick a value
out of a pick list or enter another by hand. The variable var will
contain the textual value either entered or selected.
<P>newf_combo is used with the comboitem command. You setup first the
combo field and then you pass one by one the possible values using
comboitem. Note that the values are followed by a descriptive text
(optional). Here is a code sample:
<P>
<BLOCKQUOTE><CODE>
<PRE>
        echo newf_combo port \"Which port\" ttyS1
        echo comboitem ttyS0 \"COM1 in DOS\"
        echo comboitem ttyS1 \"COM2 in DOS\"
        echo comboitem ttyS2 \"COM3 in DOS\"
        
</PRE>
</CODE></BLOCKQUOTE>
<P>The variable $port will take the value ttyS0, ttyS1, ttyS2 or anything
the user dares to enter. See 
<A HREF="#newf_enum">newf_enum</A>
and 
<A HREF="#newf_list">newf_list</A> for a variation
of this input field.
<P>
<H3><A NAME="newf_dbl"></A> echo newf_dbl var \"field title\" \"Initial numeric value\" number-of-decimal        </H3>

<P>Setup a numerical input field with decimal notation. Works
like <CODE>
<A HREF="#newf_num">newf_num</A></CODE>
except that a decimal point is allowed. The number of decimal parameter
control the number of digits allowed after the decimal point as well
as the formatting of the field.
<P>
<H3><A NAME="newf_enum"></A> echo newf_enum var \"field title\" \"Initial numeric value\"        </H3>

<P>Setup a selector field. The user will be able to pick a value
out of a pick list. The variable var will contain the index of the
selected item. The user is limited to picking one item of the list.
<P>newf_enum is used with the enumitem command. You setup first the
enum field and then you pass one by one the possible values using
enumitem. Here is a code sample:
<P>
<BLOCKQUOTE><CODE>
<PRE>
        echo newf_enum no \"Which port\" 1
        echo enumitem ttyS0 \"COM1 in DOS\"
        echo enumitem ttyS1 \"COM2 in DOS\"
        echo enumitem ttyS2 \"COM3 in DOS\"
        
</PRE>
</CODE></BLOCKQUOTE>
<P>The variable $no will take the value 0 1 or 2. See
<A HREF="#newf_combo">newf_combo</A> and
<A HREF="#newf_list">newf_list</A>
for a variation of this input field.
<P>
<H3><A NAME="newf_gauge"></A> echo newf_gauge ID \"field title\" \"Initial decimal value\" \"Maximum value\"        </H3>

<P>Setup a visual gauge, generally used to display the completion
status of a process (loading, installing). The state of the gauge
is changed by calling this command again. The first call defines
the field, the next ones update the gauge. This widget is
generally used with the "show" command so the script never
stop in the "edit" state. Here is a small example
<P>
<BLOCKQUOTE><CODE>
<PRE>
        echo DIALOG
        qecho newf_gauge ID "Status" 0 10
        qecho show "Status" ""
        i=0
        while [ "$i" != "10" ] ; do
            i=`expr $i + 1`
            sleep 1
            qecho newf_gauge ID "Status" $i 10
            qecho show "Status" ""
        done
        
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H3><A NAME="newf_hexnum"></A> echo newf_hexnum var \"field title\" \"Initial hexa-decimal value\"        </H3>

<P>Setup a numerical input field (integer). Works like
<CODE>
<A HREF="#newf_num">newf_num</A></CODE>
but accept digits and hexa-decimal digits.
<P>
<H3><A NAME="newf_list"></A> echo newf_list var \"field title\" \"Initial value\"        </H3>

<P>Setup a selector field. The user will be able to pick a value
out of a pick list only The variable var will
contain the textual value selected.
<P>newf_list is used with the listitem command. You setup first the
list field and then you pass one by one the possible values using
listitem. Note that the values are followed by a descriptive text
(optional). Here is a code sample:
<P>
<BLOCKQUOTE><CODE>
<PRE>
        echo newf_list port \"Which port\" ttyS1
        echo listitem ttyS0 \"COM1 in DOS\"
        echo listitem ttyS1 \"COM2 in DOS\"
        echo listitem ttyS2 \"COM3 in DOS\"
        
</PRE>
</CODE></BLOCKQUOTE>
<P>The variable $port will take the value ttyS0, ttyS1 or ttyS2.
See 
<A HREF="#newf_enum">newf_enum</A>
and 
<A HREF="#newf_combo">newf_combo</A>
for a variation of this input field.
<P>
<H3><A NAME="newf_num"></A> echo newf_num var \"field title\" \"Initial numeric value\"        </H3>

<P>Setup a numerical input field (integer). Works like <CODE>newf_str</CODE>
but accept only digit.
<P>
<H3><A NAME="newf_pass"></A> echo newf_pass var \"field title\" \"Initial value\"        </H3>

<P>Setup a password field. Works like a <CODE>newf_str</CODE> field except
the input is not echoed (invisible typing).
<P>
<H3><A NAME="newf_radio"></A> echo newf_radio var \"field title\" numeric-value instance-value \"suffix title\"        </H3>

<P>Setup a radio button field. Several radio button fields must be
defined for each possible selection. All radio buttons sharing the
same input variable (var above) operate together: Selecting one
De-select the other. The var variable will get the numeric-value
of the selected radio button field.
<P>Related radio buttons may be placed anywhere in a dialog. They do not
have to be sequential or even on the same page of the notebook dialog
<P>
<H3><A NAME="newf_slider"></A> echo newf_slider var \"field title\" \"Initial decimal value\" \"minimum value\" \"Maximum value\"        </H3>

<P>This works like the newf_num, to edit a decimal value. But it is
shown as a visual slider. The minimum and maximum value represent
the left and right edge of the slider.
<P>
<BLOCKQUOTE><CODE>
<PRE>
        qecho newf_slider var "Meeting hour" 15 9 16
        
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H3><A NAME="newf_str"></A> echo newf_str var \"field title\" \"Initial value\"        </H3>

<P>Setup a one line text input.
<P>
<H3><A NAME="newf_title"></A> echo newf_title "Pad title" level "Left title" "Text mode title"        </H3>

<P>This is not an input field but a way to organize a large dialog
in section. The end result is far different in graphic mode than
in text or HTML mode. In graphic mode, this will create a notebook
dialog and each newf_title defines one page (one pad) of the notebook.
<P>The first argument, pad title, is only used in graphic mode.
<P>The  second argument is a number and represent the notebook level. This
allows very complex dialogs with notebook within notebook. In text
and HTML mode, this argument has no effect.
<P>
<UL>
<LI>A value of 0 add an horizontal splitter between two fields. The
"Text mode title" is centered in that splitter.</LI>
<LI>A value of 1 create the first level of notebook. A value of 2
create a sub-notebook with the current one.</LI>
</UL>
<P>The third argument, left title, is used only in text and HTML mode.
It places a small title on the left of the input fields.
<P>The last argument, text mode title, appears centered between two
input fields.
<P>
<H2><A NAME="ss3.8">3.8 Adding buttons</A>
</H2>

<P>You can add optional buttons simply by using the button command. It
requires to arguments. The first is the button ID which will be passed
to the script using the CODE variable. The second is the label
(title) of the button. Here is an example:
<P>
<BLOCKQUOTE><CODE>
<PRE>
        echo DIALOG
        echo newf_str name \"User name\" $name
        echo button Add \"Add a new user\"
        echo edit "title" \"User management\"
        dispatch
        echo end
        if [ "$CODE" = "Add" ] ; then
                # Adding a new user
        elif [ "$CODE" = "accept" ] ; then
                # Inspecting a user record
        fi
        
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="ss3.9">3.9 Set the current input field</A>
</H2>

<P>The "setcurfield" opcode sets the keyboard focus on a specific field.
You must pass the field ID as a single argument. Here is an example:
<P>
<BLOCKQUOTE><CODE>
<PRE>
        qecho DIALOG
        qecho newf_str uid "User id" 
        qecho newf_str name "Name" 
        qecho newf_str phone "Name"
        qecho setcurfield name
        qecho edit "sample" "The focus is now on name"
        dispatch
        echo end 
        
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="ss3.10">3.10 Miscellaneous</A>
</H2>

<P>
<H3>echo remove_all</H3>

<P>Remove all fields from a dialog, allowing you to redefine its content.
<P>
<P>
<HR>
<A HREF="intro-4.html">Next</A>
<A HREF="intro-2.html">Previous</A>
<A HREF="intro.html#toc3">Contents</A>
</BODY>
</HTML>