klish/klish.xsd

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://clish.sourceforge.net/XMLSchema" targetNamespace="http://clish.sourceforge.net/XMLSchema">


	<xs:annotation>
		<xs:appinfo>XML schema for klish configuration files</xs:appinfo>
		<xs:documentation xml:lang="en">
		The klish utility uses XML files for configuration. This schema
		allows to validate klish XML files. To check XML files use the
		following command:
		'xmllint --schema /path/to/klish.xsd --noout *.xml'
		</xs:documentation>
		<xs:documentation xml:lang="ru">
		Утилита klish использует формат XML для своих конфигурационных
		файлов. Схема позволяет проверить эти конфигурационные XML файлы
		на правильность. Следующая команда выполнит проверку:
		'xmllint --schema /path/to/klish.xsd --noout *.xml'
		</xs:documentation>
	</xs:annotation>


	<xs:element name="KLISH" type="klish_t"/>
	<xs:element name="ENTRY" type="entry_t"/>
	<xs:element name="VIEW" type="view_t"/> <!-- Wrapper -->
	<xs:element name="COMMAND" type="command_t"/> <!-- Wrapper -->
	<xs:element name="FILTER" type="command_t"/> <!-- Wrapper -->
	<xs:element name="STARTUP" type="startup_t"/>
	<xs:element name="ACTION" type="action_t"/>
	<xs:element name="OVERVIEW" type="overview_t"/>
	<xs:element name="DETAIL" type="detail_t"/>
	<xs:element name="PTYPE" type="ptype_t"/> <!-- Wrapper -->
	<xs:element name="PARAM" type="param_t"/> <!-- Wrapper -->
	<xs:element name="NAMESPACE" type="namespace_t"/> <!-- Wrapper -->
	<xs:element name="VAR" type="var_t"/>
	<xs:element name="WATCHDOG" type="wdog_t"/>
	<xs:element name="HOTKEY" type="hotkey_t"/>
	<xs:element name="PLUGIN" type="plugin_t"/>
	<xs:element name="HOOK" type="hook_t"/>


	<xs:complexType name="klish_t">
		<xs:annotation>
			<xs:documentation xml:lang="en">
			'KLISH' is the top level container. Any object (command,
			type, var) which are defined within this tag are global
			in scope i.e. it is visible from all 'VIEW's.
			</xs:documentation>
			<xs:documentation xml:lang="ru">
			Тег 'KLISH' - контейнер верхнего уровня. Все остальные
			теги должны быть вложенными. Любой объект (команда,
			тип, переменная т.д.), заданный внутри этого тега,
			считается глобальным, т.е. видимым их любых 'VIEW".
			</xs:documentation>
		</xs:annotation>
		<xs:sequence>
			<xs:element ref="PLUGIN" minOccurs="0" maxOccurs="unbounded"/>
			<xs:element ref="HOOK" minOccurs="0" maxOccurs="unbounded"/>
			<xs:element ref="HOTKEY" minOccurs="0" maxOccurs="unbounded"/>
			<xs:element ref="WATCHDOG" minOccurs="0" maxOccurs="1"/>
			<xs:element ref="PTYPE" minOccurs="0" maxOccurs="unbounded"/>
			<xs:element ref="OVERVIEW" minOccurs="0"/>
			<xs:element ref="STARTUP" minOccurs="0"/>
			<xs:element ref="VAR" minOccurs="0" maxOccurs="unbounded"/>
			<xs:element ref="VIEW" minOccurs="0" maxOccurs="unbounded"/>
			<xs:element ref="ENTRY" minOccurs="0" maxOccurs="unbounded"/>
		</xs:sequence>
	</xs:complexType>


<!--
*******************************************************
* <PTYPE> is used to define the syntax for a parameter type.
*
* name="<string>" - A textual name for this type. This name can be used to
*	reference this type within a PARAM's ptype attribute.
*
* help="<string>" - Help string.
*
********************************************************
-->
	<xs:complexType name="ptype_t">
		<xs:sequence>
			<xs:element ref="ACTION" minOccurs="0" maxOccurs="unbounded"/>
		</xs:sequence>
		<xs:attribute name="name" type="xs:string" use="required"/>
		<xs:attribute name="help" type="xs:string" use="required"/>
	</xs:complexType>


<!--
*******************************************************
* <ENTRY> This tag is used to define wide class of elements.
*
* name - A text name for entry.
*
* help - A text string which describes the purpose of the entry.
*
* ptype - Reference to a PTYPE name. This parameter will be 
*	validated against the syntax specified for that type.
*	The special value of "" indicates the parameter is a boolean flag.
*	The verbatim presence of the texual name on the command line
*	simply controls the conditional variable expansion for this 
*	parameter.
*
* [mode] - Parameter mode. It can be "common", "switch", "subcommand", "multi".
*
* [prefix] - defines the prefix for an optional parameter. A prefix
*	with this value on the command line will signify the presence
*	of an additional argument which will be validated as the
*	value of this parameter.
*
* [optional] - Specify whether parameter is optional. The allowed values
*	is "true" or "false". It's false by default.
*
* [order] - Used only together with "optional=true" field.
*	If order="true" then user can't enter previously declared
*	optional parameters after current validated parameter.
*	The allowed values is "true" or "false". It's false by default.
*
* [default] - defines a default value for a parameter. Any parameters
*	at the end of command line which have default values need 
*	not explicitly be entered.
*
* [value] - defines the user's value for subcommand. If this option
*	is defined the entered parameter will be compared to this
*	value instead the "name" field. If this field is defined
*	the mode of PARAM will be forced to "subcommand". The
*	feature is implemented to support subcommands with the
*	same names.
*
* [hidden] - define the visibility of the parameter while ${__line}
*	and ${__params} auto variables expanding. The allowed values
*	is "true" and "false".
*
* [test] - define the condition (see the description of 'test'
*	utility) to process this parameter.
*
* [access]  - access rights
*
* [filter="true/false"] - Developer can define 'filter' command to filter stdout
*	of piped ("|") commands. Filter can't contain 'sync' ACTIONs. It will be
*	always fork()-ed. Only filters can be on the right hand to pipe "|".
*	Consider filters as a special type of commands.
*
********************************************************
-->
	<xs:simpleType name="entry_mode_t">
		<xs:restriction base="xs:string">
			<xs:enumeration value="sequence"/>
			<xs:enumeration value="switch"/>
			<xs:enumeration value="empty"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:simpleType name="entry_purpose_t">
		<xs:restriction base="xs:string">
			<xs:enumeration value="common"/>
			<xs:enumeration value="ptype"/>
			<xs:enumeration value="prompt"/>
			<xs:enumeration value="cond"/>
			<xs:enumeration value="completion"/>
			<xs:enumeration value="help"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:group name="entry_group_t">
		<xs:choice>
			<xs:element ref="ENTRY" minOccurs="0" maxOccurs="unbounded"/>
			<xs:element ref="ACTION" minOccurs="0" maxOccurs="unbounded"/>
		</xs:choice>
	</xs:group>

	<xs:complexType name="entry_t">
		<!--  Any order of tags and any number -->
		<xs:sequence>
			<xs:group ref="entry_group_t" minOccurs="0" maxOccurs="unbounded"/>
		</xs:sequence>
		<xs:attribute name="name" type="xs:string" use="required"/>
		<xs:attribute name="help" type="xs:string" use="optional"/>
		<xs:attribute name="container" type="xs:boolean" use="optional" default="false"/>
		<xs:attribute name="mode" type="param_mode_t" use="optional" default="switch"/>
		<xs:attribute name="purpose" type="param_purpose_t" use="optional" default="common"/>
		<xs:attribute name="min" type="xs:string" use="optional" default="1"/>
		<xs:attribute name="max" type="xs:string" use="optional" default="1"/>
		<xs:attribute name="ptype" type="xs:string" use="optional"/>
		<xs:attribute name="ref" type="xs:string" use="optional"/>
		<xs:attribute name="value" type="xs:string" use="optional"/>
		<xs:attribute name="restore" type="xs:boolean" use="optional" default="false"/>
		<xs:attribute name="order" type="xs:boolean" use="optional" default="false"/>
		<xs:attribute name="filter" type="xs:boolean" use="optional" default="false"/>
	</xs:complexType>


<!--
*******************************************************
* <VIEW> defines the contents of a specific CLI view.
*
* name - a textual name for the view
*
* prompt - a textual definition of the prompt to be
*	used whilst in this view.
*	NB. The prompt may contain environment
*	or dynamic variables which are expanded
*	before display.
*
* [access] - access rights
*
********************************************************
-->
	<xs:complexType name="view_t">
		<xs:sequence>
			<xs:element ref="NAMESPACE" minOccurs="0" maxOccurs="unbounded"/>
			<xs:element ref="COMMAND" minOccurs="0" maxOccurs="unbounded"/>
			<xs:element ref="HOTKEY" minOccurs="0" maxOccurs="unbounded"/>
			<xs:element ref="ENTRY" minOccurs="0" maxOccurs="unbounded"/>
		</xs:sequence>
		<xs:attribute name="name" type="xs:string" use="required"/>
		<xs:attribute name="prompt" type="xs:string" use="optional"/>
		<xs:attribute name="access" type="xs:string" use="optional"/>
	</xs:complexType>


<!--
*******************************************************
* <STARTUP> is used to define what happens when the CLI
* is started. Any text held in a <DETAIL> sub-element will
* be used as banner text, then any defined <ACTION> will be 
* executed. This action may provide Message Of The Day (MOTD)
* type behaviour.
*
* view - defines the view which will be transitioned to, on 
*	successful execution of any <ACTION> tag.
*
* [viewid] - defined the new value of the ${VIEWID} variable to
*	be used if a transition to a new view occurs.
*
* [default_shebang] - The default shebang for all commands.
*
* [timeout] - The idle timeout. The clish will exit if user
*	have not press any key while this timeout.
*
* [lock] - The same as lock for COMMAND tag.
*
* [interrupt] - The same as interrupt for COMMAND tag.
*
* [default_plugin] - Use (or don't use) default plugin.
*	It can be true or false.
********************************************************
-->
	<xs:complexType name="startup_t">
		<xs:sequence>
			<xs:element ref="DETAIL" minOccurs="0"/>
			<xs:element ref="ACTION" minOccurs="0" maxOccurs="unbounded"/>
		</xs:sequence>
		<xs:attribute name="view" type="xs:string" use="required"/>
		<xs:attribute name="viewid" type="xs:string" use="optional"/>
		<xs:attribute name="default_shebang" type="xs:string" use="optional"/>
		<xs:attribute name="timeout" type="xs:string" use="optional"/>
		<xs:attribute name="default_plugin" type="xs:boolean" use="optional" default="true"/>
	</xs:complexType>


<!--
*******************************************************
* <PARAM> This tag is used to define a parameter for a command.
*
* name - a textual name for this parameter. 
*
* help - a textual string which describes the purpose of the
*	parameter.
*
* ptype - Reference to a PTYPE name. This parameter will be 
*	validated against the syntax specified for that type.
*	The special value of "" indicates the parameter is a boolean flag.
*	The verbatim presence of the texual name on the command line
*	simply controls the conditional variable expansion for this 
*	parameter.
*
* [mode] - Parameter mode. It can be "common", "switch", "subcommand", "multi".
*
* [prefix] - defines the prefix for an optional parameter. A prefix
*	with this value on the command line will signify the presence
*	of an additional argument which will be validated as the
*	value of this parameter.
*
* [optional] - Specify whether parameter is optional. The allowed values
*	is "true" or "false". It's false by default.
*
* [order] - Used only together with "optional=true" field.
*	If order="true" then user can't enter previously declared
*	optional parameters after current validated parameter.
*	The allowed values is "true" or "false". It's false by default.
*
* [default] - defines a default value for a parameter. Any parameters
*	at the end of command line which have default values need 
*	not explicitly be entered.
*
* [value] - defines the user's value for subcommand. If this option
*	is defined the entered parameter will be compared to this
*	value instead the "name" field. If this field is defined
*	the mode of PARAM will be forced to "subcommand". The
*	feature is implemented to support subcommands with the
*	same names.
*
* [hidden] - define the visibility of the parameter while ${__line}
*	and ${__params} auto variables expanding. The allowed values
*	is "true" and "false".
*
* [test] - define the condition (see the description of 'test'
*	utility) to process this parameter.
*
* [access]  - access rights
*
********************************************************
-->
	<xs:group name="param_group_t">
		<xs:choice>
			<xs:element ref="PARAM"/>
			<xs:element ref="ENTRY"/>
		</xs:choice>
	</xs:group>

	<xs:complexType name="param_t">
		<!--  Any order of tags and any number -->
		<xs:sequence>
			<xs:group ref="param_group_t" minOccurs="0" maxOccurs="unbounded"/>
		</xs:sequence>
		<xs:attribute name="name" type="xs:string" use="required"/>
		<xs:attribute name="help" type="xs:string" use="required"/>
		<xs:attribute name="ptype" type="xs:string" use="required"/>
		<xs:attribute name="mode" type="entry_mode_t" use="optional" default="common"/>
		<xs:attribute name="order" type="xs:boolean" use="optional" default="false"/>
		<xs:attribute name="value" type="xs:string" use="optional"/>
	</xs:complexType>


<!--
********************************************************
* <ACTION> specifies the action to be taken for
* a command.
*
* In addition the optional 'sym' attribute can specify
* the name of an internal command which will be invoked
* to handle script.
*
* [sym="<symbol>"] - specify the name of an internally registered
*	function. The content of the ACTION tag is
*	taken as the arguments to this builtin function.
*
* [lock="<name>"] - Named lock. It will use special lockfile while
*	action execution.
*
* [interrupt="true/false"] - The boolean field that specify that action can be
*	be interrupted by Ctrl^C. Default is false. Ignored for non-interactive
*	actions.
*
* [interactive="true/false"] - Is action interactive.
*
* [exec_on="fail/success/always/never"] - ACTION's execution depends on
*	return code of previous elements of ACTION chain. If the
*	condition is not met then ACTION will not be executed. The "always"
*	value means that ACTION will be always executed and chain return
*	code will be ignored. Default is "success".
*
* [update_retcode="true/false"] - The chain return value can be updated
*	by current ACTION's return code or ACTION's return code can be ignored.
*	Default is "true".
*
* [permanent="true/false"] - The klish can be invoked with --dry-run option. In
*	this case all ACTIONs will be not actually executed but will always
*	return success. But some actions like navigation is necessary to be
*	executed in any case. Permanent flag will inform engine to always
*	execute ACTION.
*
* [sync="true/false"] - Common behaviour is to fork() process before ACTION
*	execution. But ACTION may be executed in-place (without fork()) if sync
*	flag is set to true. It's not recommended to use sync ACTIONs widely.
*	It's usefull for small fast functions only.
*
********************************************************
-->
	<xs:simpleType name="action_cond_t">
		<xs:restriction base="xs:string">
			<xs:enumeration value="fail"/>
			<xs:enumeration value="success"/>
			<xs:enumeration value="always"/>
			<xs:enumeration value="never"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:complexType name="action_t">
		<xs:simpleContent>
			<xs:extension base="xs:string">
				<xs:attribute name="sym" type="xs:string" use="optional"/>
				<xs:attribute name="lock" type="xs:string" use="optional"/>
				<xs:attribute name="interrupt" type="xs:boolean" use="optional" default="false"/>
				<xs:attribute name="interactive" type="xs:boolean" use="optional" default="false"/>
				<xs:attribute name="exec_on" type="action_cond_t" use="optional" default="success"/>
				<xs:attribute name="update_retcode" type="xs:boolean" use="optional" default="true"/>
				<xs:attribute name="permanent" type="xs:boolean" use="optional" default="false"/>
				<xs:attribute name="sync" type="xs:boolean" use="optional" default="false"/>
			</xs:extension>
		</xs:simpleContent>
	</xs:complexType>


<!--
*******************************************************
* <COMMAND> is used to define a command within the CLI.
*
* name="<string>" - A textual name for this command. (This may contain
*	spaces e.g. "display acl")
*
* help="<string>" - Help for command.
*
* [view] - defines the view which will be transitioned to, on 
*	successful execution of any <ACTION> tag. By default the
*	current view stays in scope.
*
* [viewid] - defined the new value of the ${VIEWID} variable to
*	be used if a transition to a new view occurs. By default
*	the viewid will retain it's current value.
*
* [access] - defines the user group/level to which execution of this 
*	command is restricted. By default there is no restriction.
*	The exact interpretation of this field is dependant on the
*	client of libclish but for example the clish and tclish 
*	applications map this to the UNIX user groups.
*
* [escape_chars] - defines the characters which will be escaped (e.g. \$) before
*	being expanded as a variable. By default the following
*	characters will be escaped `|$<>&()#
*
* [args] - defines a parameter name to be used to gather the rest of the
*	command line after the formally defined parameters 
*	(PARAM elements). The formatting of this parameter is a raw
*	string containing as many words as there are on the rest of the
*	command line.
*
* [args_help] - a textual string which describes the purpose of the 'args' 
*	parameter. If the "args" attribute is given then this MUST be
*	given also.
*
********************************************************
-->
	<xs:complexType name="command_t">
		<xs:sequence>
			<xs:element ref="DETAIL" minOccurs="0"/>
			<!--  Any order of PARAM tags and any number -->
			<xs:group ref="param_group_t" minOccurs="0" maxOccurs="unbounded"/>
			<xs:element ref="ACTION" minOccurs="0" maxOccurs="unbounded"/>
			<xs:element ref="COMMAND" minOccurs="0" maxOccurs="unbounded"/>
		</xs:sequence>
		<xs:attribute name="name" type="xs:string" use="required"/>
		<xs:attribute name="help" type="xs:string" use="required"/>
		<xs:attribute name="ref" type="xs:string" use="optional"/>
		<xs:attribute name="view" type="xs:string" use="optional"/>
		<xs:attribute name="viewid" type="xs:string" use="optional"/>
		<xs:attribute name="access" type="xs:string" use="optional"/>
		<xs:attribute name="args" type="xs:string" use="optional"/>
		<xs:attribute name="args_help" type="xs:string" use="optional"/>
		<xs:attribute name="escape_chars" type="xs:string" use="optional"/>
	</xs:complexType>


<!--
********************************************************
* <OVERVIEW> specifies a textual description of the shell.
*
* This should provide instructions about key bindings and
* escape sequences which can be used in the CLI.
*
********************************************************
-->
	<xs:simpleType name="overview_t">
		<xs:restriction base="xs:string">
			<xs:whiteSpace value="preserve"/>
		</xs:restriction>
	</xs:simpleType>


<!--
********************************************************
* <DETAIL> specifies a textual description.
*
* This may be used within the scope of a <COMMAND> 
* element, in which case it would typically contain 
* detailed usage instructions including examples.
*
* This may also be used within the scope of a <STARTUP>
* element, in which case the text is used as the banner
* details which are displayed on shell startup. This is
* shown before any specified <ACTION> is executed.
*
* This text may also be used in the production of user manuals.
********************************************************
-->
	<xs:simpleType name="detail_t">
		<xs:restriction base="xs:string">
			<xs:whiteSpace value="preserve"/>
		</xs:restriction>
	</xs:simpleType>


<!--
*******************************************************
* <NAMESPACE> import commands from specific view to current view.
*
* ref - the view to import commands from
*
* [prefix] - the prefix for imported commands
*
* [prefix_help] - the help for namespace prefix
*
* [help] - a boolean flag to use imported
*	commands while help
*
* [completion] - a boolean flag to use imported
*	commands while completion
*
* [context_help] - a boolean flag to use imported
*	commands while context help
*
* [inherit] - a boolean flag to inherit nested
*	namespace commands recursively
*
* [access] - access rights
*
********************************************************
-->
	<xs:complexType name="namespace_t">
		<xs:attribute name="ref" type="xs:string" use="required"/>
		<xs:attribute name="prefix" type="xs:string" use="optional"/>
		<xs:attribute name="prefix_help" type="xs:string" use="optional"/>
		<xs:attribute name="help" type="xs:boolean" use="optional" default="false"/>
		<xs:attribute name="completion" type="xs:boolean" use="optional" default="true"/>
		<xs:attribute name="context_help" type="xs:boolean" use="optional" default="false"/>
		<xs:attribute name="inherit" type="xs:boolean" use="optional" default="true"/>
		<xs:attribute name="access" type="xs:string" use="optional"/>
	</xs:complexType>


<!--
*******************************************************
* <VAR> Specify the variable.
*
*
*
********************************************************
-->
	<xs:complexType name="var_t">
		<xs:sequence>
			<xs:element ref="ACTION" minOccurs="0" maxOccurs="unbounded"/>
		</xs:sequence>
		<xs:attribute name="name" type="xs:string" use="required"/>
		<xs:attribute name="help" type="xs:string" use="optional"/>
		<xs:attribute name="value" type="xs:string" use="optional"/>
		<xs:attribute name="dynamic" type="xs:boolean" use="optional" default="false"/>
	</xs:complexType>


<!--
*******************************************************
* <WATCHDOG> is used to recover system after errors.
*
********************************************************
-->
	<xs:complexType name="wdog_t">
		<xs:sequence>
			<xs:element ref="ACTION" minOccurs="1" maxOccurs="unbounded"/>
		</xs:sequence>
	</xs:complexType>


<!--
*******************************************************
* <HOTKEY> is used to define hotkey actions
*
********************************************************
-->
	<xs:complexType name="hotkey_t">
		<xs:attribute name="key" type="xs:string" use="required"/>
		<xs:attribute name="cmd" type="xs:string" use="required"/>
	</xs:complexType>


<!--
*******************************************************
* <PLUGIN> is used to dynamically load plugins.
* Plugin contains symbols that can be used for ACTIONs.
*
* name - Plugin name. If "file" attribute is not specified then plugin's
*	filename is autogenerated as "klish-plugin-<name>.so".
* [id] - Internal plugin name. Can be the same as "name".
* [file] - File name if standard autogenerated filename (using "name" field)
*	is not appropriate.
********************************************************
-->
	<xs:complexType name="plugin_t">
		<xs:simpleContent>
			<xs:extension base="xs:string">
				<xs:attribute name="name" type="xs:string" use="required"/>
				<xs:attribute name="id" type="xs:string" use="optional"/>
				<xs:attribute name="file" type="xs:string" use="optional"/>
			</xs:extension>
		</xs:simpleContent>
	</xs:complexType>


<!--
*******************************************************
* <HOOK> is used to redefine internal hooks
*
* name - The name of internal hook (init, fini, access, log).
*
* [builtin] - specify the name of an internally registered
*	function.
*
********************************************************
-->
	<xs:simpleType name="hook_list_e">
		<xs:restriction base="xs:string">
			<xs:enumeration value="init"/>
			<xs:enumeration value="fini"/>
			<xs:enumeration value="access"/>
			<xs:enumeration value="log"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:complexType name="hook_t">
		<xs:attribute name="name" type="hook_list_e"/>
		<xs:attribute name="builtin" type="xs:string" use="optional"/>
	</xs:complexType>

</xs:schema>