Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Orion/Documentation/Developer Guide/Plugging into the shell"
(→Service methods) |
(add the orion.shell.type spec) |
||
Line 34: | Line 34: | ||
:::The parameter's identifier | :::The parameter's identifier | ||
::;type | ::;type | ||
− | :::One of { string | boolean | number | array | selection | | + | :::One of { string | boolean | number | array | selection | a custom orion.shell.type} |
::;description | ::;description | ||
:::(Recommended) A brief description of the parameter | :::(Recommended) A brief description of the parameter | ||
Line 40: | Line 40: | ||
:::(Optional) The value assumed by the parameter if the user does not supply a value for it, makes the parameter optional | :::(Optional) The value assumed by the parameter if the user does not supply a value for it, makes the parameter optional | ||
− | == | + | = orion.shell.type = |
+ | |||
+ | The <tt>orion.shell.type</tt> service is used to contribute parameter types to the Shell page. These enable contributed commands to have custom parameters with dynamically-computed completion suggestions. The service is executed when the Shell page needs either completion suggestion values to display, or the string representation for a given value. | ||
+ | |||
+ | == Service methods == | ||
+ | |||
+ | Implementations of <tt>orion.shell.type</tt> define the following functions: | ||
+ | |||
+ | ;parse(arg, typeSpec, context) | ||
+ | : Takes the currently-typed user string and returns an object with completion suggestions. The arguments to this function are: | ||
+ | :;arg | ||
+ | ::An object with properties {prefix: string, suffix: string, text: string}, contains the user's currently-typed string for an instance of this parameter | ||
+ | :;typeSpec | ||
+ | ::This parameter's typeSpec as defined by the command that is using it | ||
+ | :;context | ||
+ | ::An object with additional information; currently its only property is {lastParseTimestamp: number}, which can aid in determining when the completion suggestions being returned should be recomputed | ||
+ | |||
+ | The return value for this service must be either an orion.Deferred (if computation of the result object has to be done asynchronously), or an object with the following properties: | ||
+ | |||
+ | :;status | ||
+ | ::One of the following numbers: | ||
+ | :::0: (MATCH) the currently-typed string matches a valid value (ie.- the typing of this parameter value can now be considered complete) | ||
+ | :::1: (PARTIAL) the currently-typed string partially matches a valid value (ie.- the typing of a valid value in progress) | ||
+ | :::2: (ERROR) the currently-typed string does not match a subset of the initial characters of any valid values | ||
+ | :;message | ||
+ | ::(Optional) An error message to display in the Shell page | ||
+ | :;predictions | ||
+ | ::An array of {name: string, value: object} objects that are valid completions for the currently-typed string (name is the string to display in the suggestions list) | ||
+ | :;value | ||
+ | ::If the currently-typed string is a match for a valid value then set this property to that {name: string, value: object} value, otherwise set its value to undefined | ||
+ | |||
+ | ;stringify(object, typeSpec) | ||
+ | : (Optional) Returns an object's string representation that is appropriate for display in the Shell page's output area. An example case where this string may not be the same as the "name" that was specified for it by the parse service is if a typed relative path should be resolved to an absolute path. If this service is not implemented then the object's "name" that was specified for it by the parse service implementation is used as its display string. The arguments to this function are: | ||
+ | :;object | ||
+ | ::The object to stringify | ||
+ | :;typeSpec | ||
+ | ::This parameter's typeSpec as defined by the command that is using it | ||
+ | |||
+ | == Service attributes == | ||
+ | |||
+ | Implementations of <tt>orion.shell.type</tt> define the following attribute: | ||
+ | |||
+ | ;name | ||
+ | :The name of the parameter type (used in the plug-in definition of contributed commands) | ||
+ | |||
+ | = Example = | ||
The following sample plug-in contributes an "echo" command to the Shell: | The following sample plug-in contributes an "echo" command to the Shell: |
Revision as of 12:35, 14 June 2013
Contents
Overview of contributing services to the Shell
The Shell page provides a view through which users can interact with Orion via a command-line interface. The page provides some basic commands for navigating Orion's workspace, and defines a service that allows plug-ins to contribute additional commands.
orion.shell.command
The orion.shell.command service is used to contribute commands to the Shell page. When the service is executed, an object containing the user-supplied argument values is passed to the service's callback method. The command then optionally returns a response (a return value) to be displayed in the Shell.
Service methods
Implementations of orion.shell.command may define the following function:
- callback(args)
- Takes the user-supplied command-line arguments (if any) as an argument, and optionally returns a response string in plain text (no HTML is allowed).
The only context where a contributed command would not define a service method is to assist with the contribution of sub-commands. For example, to contribute commands "tar create" and "tar extract", a parent command "tar" without a service method must first be contributed.
Service attributes
Implementations of orion.shell.command define the following attributes:
- name
- The name that is typed at the command line to invoke the command
- description
- (Recommended) A brief description of the command
- manual
- (Optional) A longer description of the command
- parameters
- (Optional) An array of the parameters that the command accepts
The Shell page currently uses GCLI as its underlying shell widget, and consequently has adopted its syntax for parameter specification. For details on this syntax begin reading at the "## Default argument values" header in the GCLI Writing Commands doc. The basic parameter object attributes are:
- name
- The parameter's identifier
- type
- One of { string | boolean | number | array | selection | a custom orion.shell.type}
- description
- (Recommended) A brief description of the parameter
- defaultValue
- (Optional) The value assumed by the parameter if the user does not supply a value for it, makes the parameter optional
orion.shell.type
The orion.shell.type service is used to contribute parameter types to the Shell page. These enable contributed commands to have custom parameters with dynamically-computed completion suggestions. The service is executed when the Shell page needs either completion suggestion values to display, or the string representation for a given value.
Service methods
Implementations of orion.shell.type define the following functions:
- parse(arg, typeSpec, context)
- Takes the currently-typed user string and returns an object with completion suggestions. The arguments to this function are:
- arg
- An object with properties {prefix: string, suffix: string, text: string}, contains the user's currently-typed string for an instance of this parameter
- typeSpec
- This parameter's typeSpec as defined by the command that is using it
- context
- An object with additional information; currently its only property is {lastParseTimestamp: number}, which can aid in determining when the completion suggestions being returned should be recomputed
The return value for this service must be either an orion.Deferred (if computation of the result object has to be done asynchronously), or an object with the following properties:
- status
- One of the following numbers:
- 0: (MATCH) the currently-typed string matches a valid value (ie.- the typing of this parameter value can now be considered complete)
- 1: (PARTIAL) the currently-typed string partially matches a valid value (ie.- the typing of a valid value in progress)
- 2: (ERROR) the currently-typed string does not match a subset of the initial characters of any valid values
- message
- (Optional) An error message to display in the Shell page
- predictions
- An array of {name: string, value: object} objects that are valid completions for the currently-typed string (name is the string to display in the suggestions list)
- value
- If the currently-typed string is a match for a valid value then set this property to that {name: string, value: object} value, otherwise set its value to undefined
- stringify(object, typeSpec)
- (Optional) Returns an object's string representation that is appropriate for display in the Shell page's output area. An example case where this string may not be the same as the "name" that was specified for it by the parse service is if a typed relative path should be resolved to an absolute path. If this service is not implemented then the object's "name" that was specified for it by the parse service implementation is used as its display string. The arguments to this function are:
- object
- The object to stringify
- typeSpec
- This parameter's typeSpec as defined by the command that is using it
Service attributes
Implementations of orion.shell.type define the following attribute:
- name
- The name of the parameter type (used in the plug-in definition of contributed commands)
Example
The following sample plug-in contributes an "echo" command to the Shell:
<html> <head> <script src="http://orionhub.org/orion/plugin.js"></script> <script> var serviceImpl = { callback: function(args) { return "'" + args.string + "'"; } }; var serviceProperties = { name: "echo", description: "Echo a string", parameters: [{ name: "string", type: "string", description: "The string to echo back" }] }; var provider = new orion.PluginProvider(); provider.registerServiceProvider( "orion.shell.command", serviceImpl, serviceProperties); provider.connect(); </script> </head> </html>
When this plug-in is installed the user can use the "echo" command in the Shell. In the first image shown below a user is in the process of entering an echo command, and is shown a hint that argument "string" (the string to echo) is expected.
In the following image the echo command has executed and its result is shown in the output area.