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

parse(arg, typeSpec, context)
  Takes the currently-typed user string and returns an object with completion suggestions. The arguments to this method 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 property {lastParseTimestamp: number}, which can aid in determining when the completion suggestions being returned should be recomputed

The return value for this method 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 provided 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 provided for it by the parse service implementation is used as its display string.
  The arguments to this method 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)