shellmod: Principles

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:

- The shellmod utility used to run shellmod script without Linuxconf. This utility is located in /usr/bin.
- The shellmod module which allows shellmod script to interact with Linuxconf. Note that a shellmod script can be used both ways, either stand-alone or embedded in Linuxconf.
- The shellmod-lib.sh function library. This is located in /usr/lib/linuxconf/lib. This contains utility functions simplifying shellmod scripts. This file must be sourced in all scripts.
- Some sample script.
- At some point, the package will contain some contrib scripts and a browser will be designed to easily find and try those contrib scripts. If you have written something general and useful, send it on the Linuxconf mailing list, for inclusion in this package.

## 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