Next Previous Contents

2. Principles

In this section we will see the basic layout of a shellmod script, how to use it and how it communicate with Linuxconf.

2.1 Components of the shellmod package

The shellmod package provides the following parts:

2.2 How to use shellmod scripts

A script may be used either stand-alone or within Linuxconf. It can be used both ways.

As a stand-alone utility

To run a shellmod script, you either do

        shellmod path_of_the_script [ arguments ]
        

Or if the script start with #!/usr/bin/shellmod, you simply run it like any utility. Note that in all cases, the script must be executable (chmod +x script).

As a Linuxconf module

To be used this way, it must be registered in Linuxconf. This is done either interactively or using a special command line. The shellmod module register its configuration menu in the Control files and systems menu. You will find there a dialog to register your script. Just enter the path of your script and that's it. The script will be visible in Linuxconf at the next run.

The script may be registered using the following command line. This is especially useful if you include your script in a package and would like to register the script in Linuxconf at package installation (RPM packagers might consider the trigger facility to do this).

        linuxconf --modulemain shellmod --setmod script_path
        

Note that the linuxconf --modulemain construct is the normal way to yield control to a module own command line: shellmod is not different.

You may unregister a script from Linuxconf by doing:

        linuxconf --modulemain shellmod --unsetmod script_path
        

Note that the above syntax replicate the way normal (C++) Linuxconf modules may be registered and unregistered, by using the linuxconf --setmod and linuxconf --unsetmod command lines.

2.3 Layout of a shellmod script

A shellmod script will always look like this:

        #!/usr/bin/shellmod
        . /usr/lib/linuxconf/lib/shellmod-lib.sh
        register(){
                # Put regmenu and comanager calls here
        }
        # Put here the various functions referenced above
        
        main(){
                # We define a sub-menu or a dialog
        }
        # The script always end with the dispatch function call. Always
        dispatch
        

The shellmod-lib.sh function library

The register function

The register function is required if the script is used as a Linuxconf module. Linuxconf will call the function expecting the script to pass back the list of menu and dialog in which it want to register. Here is an example of a register function installing two sub-menu and one co-manager.

        # Register in the "miscellaneous service" menu
        echo regmenu main MENU_MISCSERV \"main menu of the module\"
        # Register at the end of the dnsconf menu
        echo regmenu function2 dnsconf \"Some title\"
        # Register as a co-manager in the user account dialog
        echo comanager function-prefix user
        

The register function for stand-alone only module

The register function is not needed for stand-alone module. It is a good idea to provide a minimal one in case a user try to register this module in Linuxconf. The following one will make it clear the script is not intended to be use this way:

        register(){
                echo error \"This shellmod script can't be use as a module\"
        }
        

The main function

If the script is used stand-alone, it requires a function called main. The shellmod utility will blindly call this function. It is a good idea to always provide one. In the register function we often register in a Linuxconf menu the main function. Done this way, the script provides a consistent interface used either stand-alone or as a Linuxconf module.

The main function will generally define a menu or a dialog. Note that the main function is the one which will receive the script arguments. The arguments will often be used as default values for the dialog fields. Here is a small example.

        main(){
                echo DIALOG
                echo newf_str path \"Document path\" $1
                echo newf_str mail \"Email this document to\" $2
                echo newf_str fax \"Fax this document to\" $3
                echo edit \"Document manager\" \"Fill this form to send the document\"
                dispatch
                echo end
                if [ "$CODE" = "accept" ] ; then
                        if [ "$mail" != "" ] ; then
                                cat $path | mail $mail
                        fi
                        if [ "$fax" != "" ] ; then
                                spoolfax $fax $path
                        fi
                fi
        }
        

The dispatch function

A module always ends with a call to the dispatch function. A shellmod script may be seen as a set of function waiting to be called (A library). Based on context, Linuxconf (or shellmod for stand-alone scripts) will call the appropriate one.

Note that the script can perform some initialization before calling the dispatch function. As explain later, a script may be seen as a small server which keeps its state between calls to its various functions.

2.4 How does it works

A shellmod script interact with shellmod or Linuxconf by echoing commands on it standard output. It receives directives by simply reading its standard input. The dispatch function takes care of reading and processing (dispatching) the request it receives. We can think of the script as being in sandwich between two shellmod process like this

        shellmod | script | shellmod
        

Everything echoed by the script is grabbed by shellmod and interpreted as protocol commands. It is important to redirect the output of sub-command you are using either to the error channel (command >&2) or to /dev/null. Failing to do so will trigger many error messages from shellmod.


Next Previous Contents