___Requirements___
gsu is implemented in bash, and thus gsu depends on bash. Bash version
-3 is required, version 4 is recommended. Besides bash, gsu depends
-only on programs which are usually installed on any Unix system (awk,
-grep, sort, ...). Care has been taken to not rely on GNU specific
-behavior of these programs, so it should work on non GNU systems
-(MacOS, FreeBSD, NetBSD) as well. The gui module depends on the dialog utility.
+4.3 is required. Besides bash, gsu depends only on programs which are
+usually installed on any Unix system (awk, grep, sort, ...). Care has
+been taken to not rely on GNU specific behavior of these programs,
+so it should work on non GNU systems (MacOS, FreeBSD, NetBSD) as
+well. The gui module depends on the dialog utility.
___Download___
All gsu modules are contained in a git repository. Get a copy with
- git clone git://git.tuebingen.mpg.de/gsu.git
+ git clone https://git.tuebingen.mpg.de/gsu.git
-There is also a [gitweb](http://git.tuebingen.mpg.de/gsu.git) page.
+There is also a [gitweb](https://git.tuebingen.mpg.de/gsu.git) page.
___Installation___
echo 'hello world'
}
-The subcommand documentation consists of three parts:
+The subcommand documentation consists of the following parts:
- The summary. One line of text,
- the usage/synopsis string,
-- free text section.
+- free text section 1,
+- options (if any),
+- free text section 2.
-The three parts should be separated by lines consisting of two `#` characters
-only. Example:
+The last three parts are optional. All parts should be separated by
+lines consisting of two `#` characters only. Example:
com_world()
##
## Print the string "hello world" to stdout.
##
- ## Usage: world
+ ## Usage: world [-v]
##
## Any arguments to this function are ignored.
##
+ ## -v: Enable verbose mode
+ ##
## Warning: This subcommand may cause the top most line of your terminal to
## disappear and may cause DATA LOSS in your scrollback buffer. Use with
## caution.
{
- echo 'hello world'
+ printf 'hello world'
+ [[ "$1" == '-v' ]] && printf '!'
+ printf '\n'
}
Replace `hello` with the above and try:
gsu_getopts 't:v'
eval "$result"
- (($ret < 0)) && return
+ ((ret < 0)) && return
[[ -z "$o_t" ]] && o_t='ext3' # default to ext3 if -t is not given
[[ "$o_v" == 'true' ]] && awk_field=0 # $0 is the whole line
com_world()
{
gsu_check_arg_count $# 0 0 # no arguments allowed
- (($ret < 0)) && return
+ ((ret < 0)) && return
echo 'hello world'
}
___HTML output___
-The output of the auto-generated man subcommand is a suitable input for the
-grutatxt plain text to html converter. Hence
+The auto-generated man subcommand produces plain text, html, or
+roff output.
+
+ ./hello man -m html > index.html
- ./hello man | grutatxt > index.html
+is all it takes to produce an html page for your
+application. Similarly,
-is all it takes to produce an html page for your application.
+ ./hello man -m roff > hello.1
+
+creates a manual page.
___Interactive completion___
local optstring='t:v'
gsu_complete_options $optstring "$@"
- (($ret > 0)) && return
+ ((ret > 0)) && return
gsu_cword_is_option_parameter $optstring "$@"
[[ "$result" == 't' ]] && awk '{print $3}' "$f"
tree could look like this:
menu_tree='
- load_average
- processes
- hardware/
- cpu
- scsi
- storage/
- df
- mdstat
- log/
- syslog
- dmesg
+ load_average System load
+ processes Running processes of a user
+ hardware/ Hardware related information
+ cpu Show prozessor type and features
+ scsi Show SCSI devices
+ storage/ Filesystems and software raid
+ df List of mounted filesystems
+ mdstat Status of software raid arrays
+ log/ System and kernel logs
+ syslog System log
+ dmesg Kernel log
'
-In this tree, `hardware/`, `block_devices/` and `log/` are the only
-internal nodes. Note that these are written with a trailing slash
-character while the leaf nodes have no slash at the end. All entries
-of the menu tree must be indented by tab characters.
+Each line of the menu tree consists of an identifier, suffixed with an
+optional slash, and a description. The identifier becomes part of the
+name of a bash function and should only contain alphabetic characters
+and underscores. The description becomes the text shown as the menu
+item. Identifiers suffixed with a slash are regarded as internal nodes
+which represent submenus. In the above tree, `hardware/`, `storage/`
+and `log/` are internal nodes. All entries of the menu tree must be
+properly indented by tab characters.
___Action handlers___
}
The function name `lsi_df` is derived from the name of the script
-(`lsi`) and the name of the leaf node (`df`). The function simply
+(`lsi`) and the identifier of the leaf node (`df`). The function simply
passes the output of the `df(1)` command as the first argument to the
public gsu function `gsu_msgbox()` which runs dialog(1) to display
a message box that shows the given text.
local username
gsu_inputbox 'Enter username' "$LOGNAME"
- (($ret != 0)) && return
+ ((ret != 0)) && return
username="$result"
gsu_msgbox "$(pgrep -lu "$username")"
}
___Example___
-The complete lsi script below can be used as a starting point
-for your own gsu gui application. If you cut and paste it, be
-sure to not turn tab characters into space characters.
+The complete lsi script below can be used as a starting point for your
+own gsu gui application. If you cut and paste it, be sure to not turn
+tab characters into space characters. The script must be named "lsi".
#!/bin/bash
menu_tree='
- load_average
- processes
- hardware/
- cpu
- scsi
- storage/
- df
- mdstat
- log/
- syslog
- dmesg
+ load_average System load
+ processes Running processes of a user
+ hardware/ Hardware related information
+ cpu Show prozessor type and features
+ scsi Show SCSI devices
+ storage/ Filesystems and software raid
+ df List of mounted filesystems
+ mdstat Status of software raid arrays
+ log/ System and kernel logs
+ syslog System log
+ dmesg Kernel log
'
lsi_load_average()
local username
gsu_inputbox 'Enter username' "$LOGNAME"
- (($ret < 0)) && return
+ ((ret < 0)) && return
username="$result"
gsu_msgbox "$(pgrep -lu "$username")"
}
If an option is set both in the environment and in the config file,
the environment takes precedence.
+The `$gsu_config_file` variable can actually contain more than one
+filename, separated by spaces. The config files are processed in
+order, so that an option that is specified in the second config file
+overwrites the definition given in the first. This is useful for
+applications which implement a system-wide config file in addition
+to a per-user config file.
+
___Checking config options___
The gsu config module defines two public functions for this purpose:
- `$gsu_config_var_prefix`. Used by the config module to set up
the variables defined in `$gsu_options`.
+- `$gsu_package`. Text shown at the bottom left of the man page,
+usually the name and version number of the software package. Defaults
+to `$gsu_name`.
+
License
-------
gsu is licensed under the GNU LESSER GENERAL PUBLIC LICENSE (LGPL), version 3.
----------
- [bash](http://www.gnu.org/software/bash/bash.html)
- [dialog](http://www.invisible-island.net/dialog/dialog.html)
-- [grutatxt](http://triptico.com/software/grutatxt.html)
+- [The author's home page](https://people.tuebingen.mpg.de/maan/)