|
1 # cif_syntax.pod |
|
2 # |
|
3 # Copyright (c) 2010 Accenture. All rights reserved. |
|
4 # This component and the accompanying materials are made available |
|
5 # under the terms of the "Eclipse Public License v1.0" |
|
6 # which accompanies this distribution, and is available |
|
7 # at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 # |
|
9 # Initial Contributors: |
|
10 # Accenture - Initial contribution |
|
11 # |
|
12 |
|
13 =head1 Command Info Files |
|
14 |
|
15 I<This documentation is only useful for developers of fshell commands.> |
|
16 |
|
17 =head2 Introduction |
|
18 |
|
19 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 key-words that relate to the specifics of command interfaces. |
|
20 |
|
21 CIF files for fshell commands live in F<\resource\cif\fshell> and should be named I<commandname>.cif where I<commandname> is the same as what is returned by the command's Name() function. |
|
22 |
|
23 =head2 Syntax |
|
24 |
|
25 =head3 ==name <commandname> |
|
26 |
|
27 The name of the command, without any prefix or suffix. Eg C<==name hello>. Mandatory. |
|
28 |
|
29 =head3 ==short-description |
|
30 |
|
31 A one-line summary of the functionality of the command. Mandatory. Eg: |
|
32 |
|
33 ==short-description |
|
34 |
|
35 Classic C<Hello World!> example. |
|
36 |
|
37 =head3 ==long-description |
|
38 |
|
39 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: |
|
40 |
|
41 ==long-description |
|
42 |
|
43 Intended to be an example of a minimal command implementation. Simply prints C<Hello World!> to the console. |
|
44 |
|
45 =head3 ==argument <type> <name> [optional] [multiple | last] [<envvar-name>] |
|
46 |
|
47 One argument section is specified for each argument that the command accepts. C<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 C<==argument> sections. Example: |
|
48 |
|
49 ==argument int priority |
|
50 |
|
51 The priority to set. |
|
52 |
|
53 ==argument filename file optional multiple |
|
54 |
|
55 File or files to open. If not specified, opens an untitled document. |
|
56 |
|
57 The rules for the attributes are: |
|
58 |
|
59 =over 4 |
|
60 |
|
61 =item * |
|
62 |
|
63 An argument with the C<optional> attribute cannot be followed by a non-optional argument. |
|
64 |
|
65 =item * |
|
66 |
|
67 Only the final argument is allowed to have the C<multiple> attribute set. |
|
68 |
|
69 =item * |
|
70 |
|
71 An argument with just the C<multiple> attribute can be specified one or more times, C<optional> means zero or one times. An argument may have both C<optional> and C<multiple> to indicate it can be specified zero or more times. |
|
72 |
|
73 =item * |
|
74 |
|
75 Only the final argument is allowed to have the C<last> attribute. It indicates that further arguments are allowed without needing to quote them and will be merged into this argument. C<last> may not be combined with C<multiple>. If a string provided for a C<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 example (using fshell's 'time' command, which takes a single argument that uses the C<last> attribute): |
|
76 |
|
77 Input command-line Argument receive by the 'time' command |
|
78 |
|
79 1) time echo foo echo foo |
|
80 2) time 'echo foo' echo foo |
|
81 3) time echo^ foo echo foo |
|
82 4) time echo foo && echo bar echo foo (note, fshell intercepts the '&&' and launches 'echo bar' separately). |
|
83 5) time 'echo foo && echo bar' echo foo && echo bar |
|
84 6) time echo -h echo -h |
|
85 |
|
86 Note, the presence of C<last> in C<time>'s argument specification makes cases (1) and (6) possible. If C<last> were not used, case (1) C<CCommandBase> would have failed to parse the command-line (due to the presence of C<foo>) and in case (6) C<CCommandBase> would have treated the C<-h> as an argument to C<time> and printed its help (rather than C<echo>'s). |
|
87 |
|
88 =back |
|
89 |
|
90 If an environment variable name is specified using C<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. |
|
91 |
|
92 =head3 ==option <type> <shortname> <longname> [multiple | <envvar-name>] |
|
93 |
|
94 Each option that the command supports is specified by an C<==option> section. C<Type> is an fshell type, one of: bool, int, int64, uint, uint64, string, filename, real, enum. C<shortname> is the single letter used as the short option (eg C<-v> as a short option for C<--verbose>). If a command doesn't have any options, then there will be no C<==option> sections. Example: |
|
95 |
|
96 ==option bool c color |
|
97 |
|
98 Write C<Hello World!> in color. |
|
99 |
|
100 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 C<==option> line. For example an option which can also be specified by exporting $TAB_WIDTH would be defined as: |
|
101 |
|
102 ==option int w tab-width TAB_WIDTH |
|
103 |
|
104 Specify the tab width to use (defaults to 4 characters). |
|
105 |
|
106 =head3 ==include <ciffile> |
|
107 |
|
108 The C<==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: |
|
109 |
|
110 ==include xmodem.cif |
|
111 |
|
112 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. |
|
113 |
|
114 =head3 ==see-also |
|
115 |
|
116 Optional. If present, a section titled "See Also" is generated in the resulting documentation. For example: |
|
117 |
|
118 ==see-also |
|
119 |
|
120 L<ps|ps>, L<objinfo|objinfo> |
|
121 |
|
122 =head2 The enum type |
|
123 |
|
124 The C<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 C<enum> you must specify the possible values that the enum can take using the C<==enum-value> keyword. These may optionally have a separate description per value. If any value has an individual description, they all must. |
|
125 |
|
126 ==argument enum object-type |
|
127 |
|
128 The type of object to list. |
|
129 |
|
130 ==enum-value process |
|
131 |
|
132 ==enum-value thread |
|
133 |
|
134 ==enum-value chunk |
|
135 |
|
136 Or for an option (which, in this case, has individual descriptions for each value): |
|
137 |
|
138 ==option enum e encoding |
|
139 |
|
140 Encoding to use. If not specified, defaults to 'auto'. |
|
141 |
|
142 ==enum-value auto |
|
143 |
|
144 Use charconv to try and figure out the encoding (slow and error-prone for anything other than UTF-16 with BOM). |
|
145 |
|
146 ==enum-value binary |
|
147 |
|
148 Read the files in binary mode and do not perform any character conversion. |
|
149 |
|
150 ==enum-value utf-8 |
|
151 |
|
152 Assume the file is UTF-8 (with or without BOM). |
|
153 |
|
154 The order of the values in the CIF file must match how the enum is defined in the C++. Example usage: |
|
155 |
|
156 class CMyCommand : public CCommandBase |
|
157 { |
|
158 ... |
|
159 enum TOperation |
|
160 { |
|
161 ELoad, |
|
162 EStore, |
|
163 EDelete, |
|
164 }; |
|
165 TOperation iOperation; |
|
166 }; |
|
167 ... |
|
168 void CMyCommand::ArgumentsL(RCommandArgumentList& aArguments) |
|
169 { |
|
170 aArguments.AppendEnum((TInt&)iOperation, _L("operation")); |
|
171 } |
|
172 |
|
173 The CIF file would therefore contain: |
|
174 |
|
175 ==argument enum operation optional |
|
176 |
|
177 The operation to perform. If not specified, defaults to load. |
|
178 |
|
179 ==enum-value load |
|
180 |
|
181 ==enum-value store |
|
182 |
|
183 ==enum-value delete |
|
184 |
|
185 Note how the C++ enum values C<ELoad, EStore, EDelete> are in the same order as the CIF declaration of C<load, store, delete>. The C++ enum must not specify any custom values, ie the enum must start from zero and be sequential. |
|
186 |
|
187 =head2 CIF types and CCommandBase types |
|
188 |
|
189 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: |
|
190 |
|
191 CIF type CCommandBase type |
|
192 -------- ----------------- |
|
193 bool TBool |
|
194 int TInt |
|
195 int64 TInt64 |
|
196 uint TUint |
|
197 uint64 TUint64 |
|
198 string HBufC* |
|
199 filename IoUtils::TFileName2 |
|
200 real TReal |
|
201 enum TInt (or more usually, some enum type) |
|
202 |
|
203 If the argument/option can take multiple values (by specifying C<multiple> in the CIF), the types are: |
|
204 |
|
205 CIF type CCommandBase type |
|
206 -------- ----------------- |
|
207 bool RArray<TBool> |
|
208 int RArray<TInt> |
|
209 int64 RArray<TInt64> |
|
210 uint RArray<TUint> |
|
211 uint64 RArray<TUint64> |
|
212 string RPointerArray<HBufC> |
|
213 filename RArray<IoUtils::TFileName2> |
|
214 real RArray<TReal> |
|
215 enum RArray<TInt> |
|
216 |
|
217 =head1 Copyright |
|
218 |
|
219 Copyright (c) 2008-2010 Accenture. All rights reserved. |
|
220 |