Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

Help system
[Basic Components]


Detailed Description

Dynamic help for shell commands.

The help system is hierarchic system. On the top of which stands topics. Each topics holds commands. Each command has at least a name and a usage (help) message. Commands may have a optional short name. Their is a special topic for the drivers named "drivers". Help on drivers give the list of all loaded driver. Help on a driver name display information on that driver as well as the commands associate to it. Driver commands are stored by default in a topic of the name of the driver, but driver may choose other topic for each command it provides.

It is possible to have a the same name for different command usage in different topic. To access a command in a given topic help() command allow to specify a full qualified command name `topic/command`. The "*" star may be use as a wild-card on either topic or command. A single "*" or a "* / *" will display topics list and the listing of command for each topic. The wild-card only works for regular topics not for "drivers".

Author:
benjamin gerard


Functions

 addhelp (var name, var short_name, var topic, var help)
 Add help about a shell command.

 remove_help (var name, var short_name, var topic)
 Remove help.

 help_list (var tbl, var max_width, var wait_key)
 Display a list formatted list of commands.

 help_sort_key (var tbl)
 Build a sorted table of name (shortname) entry.

 help_list_key_table (var tbl, var label, var wait_key)
 Process listing of a table.

 help_on_topics (var wait_key)
 Display a list of all topics.

 help_on_drivers (var wait_key)
 Display a list of all drivers.

 help_on_topic (var topic, var wait_key, var no_topics)
 Display a list of all commands in given topics or the list of drivers.

 help_on_driver (var driver_name, var wait_key, var no_drivers)
 Display help a given driver.

 help_command_usage (var command, var topic, var only_one)
 Display usage for a command in a given topic.

 help_on_command (var command_name)
 Display help on a command.

 help (var name, var wait_key)
 Help about a shell command.

 help_init (var force)
 Initialize the help system.

 usage (what, wait_key)
 Alias for help().


Function Documentation

addhelp var  name,
var  short_name,
var  topic,
var  help
 

Add help about a shell command.

Parameters:
name name of command to add to the help (mandatory)
short_name optional short name for the command
topics help topics (defaulted to "general")
help help string (mandatory).
Returns:
error-code
Return values:
nil on error

remove_help var  name,
var  short_name,
var  topic
 

Remove help.

The remove_help() function removes help message for given commands. Either long or short name or both can be removed. If topic is nil "general" topic is used. If no more command remains in topic, the topic is removed.

Parameters:
name long name of command to remove
short_name short name of command to remove
topic topic in which is command has been add (defaut "general")
Returns:
error-code
Return values:
nil on error

help_list var  tbl,
var  max_width,
var  wait_key
 

Display a list formatted list of commands.

Parameters:
tbl table
max_width length of the longest name in the table
wait_key wait key stroke if listing too long.
See also:
ls_column()

help_sort_key var  tbl  ) 
 

Build a sorted table of name (shortname) entry.

Parameters:
tbl table to sort
Returns:
a sorted table

help_list_key_table var  tbl,
var  label,
var  wait_key
 

Process listing of a table.

The help_list_key_table() function sort the given table with the help_sort_key() function, finds the longest name and display the list with the help_list() function.

Parameters:
tbl topic ot driver table
label optional message to display before the listing
wait_key wait for a key stroke if listing too long
Returns:
error-code
Return values:
nil on error
See also:
help_sort_key()

help_list()

help_on_topics var  wait_key  ) 
 

Display a list of all topics.

Parameters:
wait_key wait for a key stroke if listing too long
Returns:
error-code
Return values:
nil on error

help_on_drivers var  wait_key  ) 
 

Display a list of all drivers.

Parameters:
wait_key wait for a key stroke if listing too long
Returns:
error-code
Return values:
nil on error

help_on_topic var  topic,
var  wait_key,
var  no_topics
 

Display a list of all commands in given topics or the list of drivers.

Parameters:
topic topic name or special "drivers" topic
wait_key wait for a key stroke if listing too long
Returns:
error-code
Return values:
nil on error

help_on_driver var  driver_name,
var  wait_key,
var  no_drivers
 

Display help a given driver.

Parameters:
driver_name name of driver
wait_key wait for a key stroke if listing too long
do not fall to display driver list if the driver is not found.
Returns:
error code
Return values:
nil on error (not found)

help_command_usage var  command,
var  topic,
var  only_one
 

Display usage for a command in a given topic.

Parameters:
command command name (either short or long name)
topic topic the command belong to or "*" for all
Returns:
number of matching comands
Return values:
nil on error (not found)

help_on_command var  command_name  ) 
 

Display help on a command.

This function is a alias for

help_command_usage(command_name, "*", 1)

Parameters:
command_name command name (either short or long name)
Returns:
error code

on error (not found)

See also:
help_command_usage()

help var  name,
var  wait_key
 

Help about a shell command.

Parameters:
name command name
wait_key wait for on keystroke if listing is too long
Help hierarchy:
  • name is nil or "topics", display the list of topics
  • name is "drivers", display the list of drivers
  • name is "*" display topics and topics command list (each of them)
  • name is "topic/command", display help on this fully qualified command topic and command an be "*".
  • name is a topic, display the list of commands in this topic
  • name is a driver, display driver info and its commands
  • name is a command, display usage of the first matching command on on all topics.

help_init var  force  ) 
 

Initialize the help system.

Parameters:
force force reinitialization if already initialized (discard all registrered commands, topics and drivers.

usage what  ,
wait_key 
 

Alias for help().

See also:
help()


dcplaya documentation version 2.0 Generated on November 2004 by doxygen 1.3.6