This documentation is only useful for developers of fshell commands.
Command Info Files (CIFs) can be used to define the interface and documentation for fshell commands that are implemented using CCommandBase. Where previously details of arguments and options etc. were specified in C++ source code, the majority of this information can now be defined in a CIF, which is a plain text file. The format of CIFs is similar to POD (Perl's documentation source format), but with an additional set of keywords that relate to the specifics of command interfaces.
CIF files for fshell commands live in \resource\cif\fshell and should be named commandname.cif where commandname is the same as what is returned by the command's Name() function.
The name of the command, without any prefix or suffix. Eg ==name hello. Mandatory.
A one-line summary of the functionality of the command. Mandatory. Eg:
==short-description
Classic C<Hello World!> example.
A fuller description of the command can go here. Full POD syntax is supported, including lists and multiple paragraphs. The POD is terminated by the next CIF double-equals line, or the end of the file. Optional. For example:
==long-description
Intended to be an example of a minimal command implementation. Simply prints C<Hello World!> to the console.
One argument section is specified for each argument that the command accepts. type is the type of the argument, one of the supported fshell types: int, int64, uint, uint64, string, filename, real, enum. See later for more details about the enum type. If a command doesn't take any arguments, then there will be no ==argument sections. Example:
==argument int priority
The priority to set.
==argument filename file optional multiple
File or files to open. If not specified, opens an untitled document.
The rules for the attributes are:
An argument with the optional attribute cannot be followed by a non-optional argument.
Only the final argument is allowed to have the multiple attribute set.
An argument with just the multiple attribute can be specified one or more times, optional means zero or one times. An argument may have both optional and multiple to indicate it can be specified zero or more times.
Prior to fshell Release 005, optional was incorrectly assumed for any multiple filename arguments. It is now required to state it explicitly if desired. Note that a wildcarded expression that matches no files still counts as having supplied an argument, even though the filename array will be empty.
Only the final argument is allowed to have the last attribute. It indicates that further arguments are allowed without needing to quote them and will be merged into this argument. last may not be combined with multiple. If a string provided for a last argument naturally (i.e. as a result of normal string quote and escape handling) forms a single argument and consumes the whole of the remainder of the command line, the resulting single argument will be used as is. Otherwise, the string will be used without any quote or escape handling. Here are some examples (using fshell's 'time' command, which takes a single argument that uses the last attribute):
Input command-line Argument receive by the 'time' command
1) time echo foo echo foo 2) time 'echo foo' echo foo 3) time echo^ foo echo foo 4) time echo foo && echo bar echo foo (note, fshell intercepts the '&&' and launches 'echo bar' separately). 5) time 'echo foo && echo bar' echo foo && echo bar 6) time echo -h echo -h
Note, the presence of last in time's argument specification makes cases (1) and (6) possible. If last were not used, case (1) CCommandBase would have failed to parse the command-line (due to the presence of foo) and in case (6) CCommandBase would have treated the -h as an argument to time and printed its help (rather than echo's).
If an environment variable name is specified using envvar-name, then fshell will use it to attempt to fill in this argument's value, if it isn't specified on the command line. Any arguments that are "filled in" in this manner cannot cause any non-filled in arguments to be reordered. In other words you can't try to supply arguments 1 and 3 on the command line and have argument 2 filled in from the environment. If an argument isn't supplied on the command line, and isn't available from the environment, and isn't optional, then it is a syntax error.
Each option that the command supports is specified by an ==option section. Type is an fshell type, one of: bool, int, int64, uint, uint64, string, filename, real, enum. shortname is the single letter used as the short option (eg -v as a short option for --verbose). If a command doesn't have any options, then there will be no ==option sections. Example:
==option bool c color
Write C<Hello World!> in color.
Some commands have configuration options which can also be specified by defining an environment variable. The environment variable can be specified on the end of the ==option line. For example an option which can also be specified by exporting $TAB_WIDTH would be defined as:
==option int w tab-width TAB_WIDTH
Specify the tab width to use (defaults to 4 characters).
The ==include tag can be used to import information from another CIF file. This is useful for commands that inherit from other commands for which the base class documentation is still relevant. For example, ymodem.cif includes xmodem.cif, and just overrides the options and arguments (and description) that differs between the xmodem and ymodem protocols. Optional. Example:
==include xmodem.cif
CIF files are processed sequentially, therefore any includes should normally be specified at the top of the file, so that later sections can override the included ones.
Optional. If present, a section titled "See Also" is generated in the resulting documentation. For example:
==see-also
L<ps|ps>, L<objinfo|objinfo>
Commands may optionally specify a snippet of code to test the basic functionality of the command. See the ciftest documentation for more details.
The enum type can be used for an option or argument that takes a limited number of named values, in much the same was as C/C++ enums are used. For an option or argument of type enum you must specify the possible values that the enum can take using the ==enum-value keyword. These may optionally have a separate description per value. If any value has an individual description, they all must.
==argument enum object-type
The type of object to list.
==enum-value process
==enum-value thread
==enum-value chunk
Or for an option (which, in this case, has individual descriptions for each value):
==option enum e encoding
Encoding to use. If not specified, defaults to 'auto'.
==enum-value auto
Use charconv to try and figure out the encoding (slow and error-prone for anything other than UTF-16 with BOM).
==enum-value binary
Read the files in binary mode and do not perform any character conversion.
==enum-value utf-8
Assume the file is UTF-8 (with or without BOM).
The order of the values in the CIF file must match how the enum is defined in the C++. Example usage:
class CMyCommand : public CCommandBase
{
...
enum TOperation
{
ELoad,
EStore,
EDelete,
};
TOperation iOperation;
};
...
void CMyCommand::ArgumentsL(RCommandArgumentList& aArguments)
{
aArguments.AppendEnumL((TInt&)iOperation, _L("operation"));
}
The CIF file would therefore contain:
==argument enum operation optional
The operation to perform. If not specified, defaults to load.
==enum-value load
==enum-value store
==enum-value delete
Note how the C++ enum values ELoad, EStore, EDelete are in the same order as the CIF declaration of load, store, delete. The C++ enum must not specify any custom values, ie the enum must start from zero and be sequential.
Each of the argument and option types mentioned here corresponds to a C++ type that is used in the command's implementation. In summary they are:
CIF type CCommandBase type
-------- -----------------
bool TBool
int TInt
int64 TInt64
uint TUint
uint64 TUint64
string HBufC*
filename IoUtils::TFileName2
real TReal
enum TInt (or more usually, some enum type)
If the argument/option can take multiple values (by specifying multiple in the CIF), the types are:
CIF type CCommandBase type
-------- -----------------
bool RArray<TBool>
int RArray<TInt>
int64 RArray<TInt64>
uint RArray<TUint>
uint64 RArray<TUint64>
string RPointerArray<HBufC>
filename RArray<IoUtils::TFileName2>
real RArray<TReal>
enum RArray<TInt>
Copyright (c) 2008-2010 Accenture. All rights reserved.