/ 
Image-DS9-v1.0.0
River stage zero No dependents
/ Image::DS9::Parser

NAME

Image::DS9::Parser - Parser driver

VERSION

version v1.0.0

Command specification structure.

Commands may have "sub-commands" and arguments. A given sub-command is allowed to have alternate argument lists. Sub-commands may be queries as well as directives, and thus will return information.

Commands are specified as arrays. Each element in the array is a separate sub-command. Sub-commands are specified via arrays, the first element of which defines the sub-command tokens, the rest the alternate argument lists.

Sub-command tokens are presented as an array of strings or regular expressions. If there is more than one, the input list of tokens must match exactly in order.

An argument list is a hash which describes the order and type of arguments and whether and how the sub-command can be queried with the specified argument list.

In detail, here's what a sub-command specification looks like:

Subcommand

This is an arrayref which contains strings or RE's to match. all must match, in the specified order. It may be empty.

Argument list

A hashref with the following possible keys:

args

An array of argument types. The types may be strings, regular expressions (generated with the qr operator), or subroutine refs. The arguments must match the types, in the specified order.

query

This determines how and if the sub-command with the specified arguments may be queried. It may have the following values:

QNONE

This sub-command with the specified argument list may not be queried.

QARGS

This sub-command with the specified argument list may only be queried. All of the arguments must specified.

QONLY

This sub-command may only be queried. No arguments may be specified.

QYES

This sub-command may be queried. No arguments may be specified for the query. This is the default if query isn't specified.

QATTR

Query may have attributes.

bufarg

The last argument passed to the command should be sent via the XPASet buf argument.

cvt

If true (the default) returned results are converted if their type has a conversion routine available. The list of arguments is used to determine the return types.

retref

If true, a reference to the queried value is returned if the user queries the command in a scalar context.

attrs

If this is present and the last element in the argument list is a hashref, it will be scanned for attributes which will modify the query or directive. Attributes are command specific, typed, and may be specified in combination or exclusion. Attributes are specified in an array as keyword/type pairs. Attributes which must appear together should be in their own array, preceded by the token -a. Attributes which must not appear together should be in their own array, preceded by the token -o. Such clauses may be nested.

For example:

ydim and xdim must both be specified:
-a => [ xdim => FLOAT, ydim => FLOAT ]
night and day must not both be specified:
-o => [ night => BOOL, day => BOOL ]
ydim and xdim must both be specified, but cannot be specified with dim:
-o => [ ( -a => [ xdim => FLOAT, ydim => FLOAT ] ),
        ( dim => FLOAT ) ]

Note that all clauses are evaluated, to catch possibly typos by the user.

SUPPORT

Bugs

Please report any bugs or feature requests to bug-image-ds9@rt.cpan.org or through the web interface at: https://rt.cpan.org/Public/Dist/Display.html?Name=Image-DS9

Source

Source is available at

https://gitlab.com/djerius/image-ds9

and may be cloned from

https://gitlab.com/djerius/image-ds9.git

SEE ALSO

Please see those modules/websites for more information related to this module.

AUTHOR

Diab Jerius <djerius@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2017 by Smithsonian Astrophysical Observatory.

This is free software, licensed under:

The GNU General Public License, Version 3, June 2007