1<!-- 2 Copyright 2012 The Android Open Source Project 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15--> 16 17# Command File Format 18 19A command file allows one to specify sets of TF commands (that is, configurations with their 20associated arguments) to be specified all at once. Further, the format used in the command file 21supports simple macro expansions, which makes it very useful without being unwieldy. You can see a 22relatively involved example at the bottom of the page, as well as more gradual documentation 23immediately below. 24 25 26## Lines 27 28The format is line-based. 29 30* Each output line will be considered as the arguments for a single Configuration for Trade 31 Federation to run. 32* Each input line will turn into one or more output lines. 33 34In essence, the command file format combinatorially creates a sequence of Configuration specifications that it passes to Trade Federation to run. Blank lines are ignored. Comments are delimited by the "#" character and may only be preceded by whitespace. 35 36 37## Macros 38 39The specific syntax for defining a macro is discussed below in the Short Macro and Long Macro sections. The following rules apply to all macros 40 41* The name of a macro must begin with an alpha character. Each subsequent character may be any 42 alphanumeric, an underscore, or a hyphen. 43* A macro with name "macro_name" is invoked by adding macro_name() as an argument on some subsequent 44 line. 45* The macro format does not support passing arguments to macros. It allows only concatenation. 46* A macro's expansion may contain invocations of other macros. Technically, a macro's expansion may 47 contain invocations of itself, but in that case, the macro will never fully expand. 48* The parser currently has a hard limit of 10 iterations of expansion. This will be made 49 configurable at some point. 50* During a single iteration of expansion: 51 * All short macro invocations on a line will be expanded a single level — macro invocations 52 embedded within the first-level expansions will not be expanded yet 53 * Only one long macro invocation on a line will be expanded. This will be the left-most long 54 macro invocation. 55 56 57## Short Macros 58 59A short macro can be defined with the syntax: 60 61 MACRO macro_name = this is the macro expansion 62 63The macro expansion terminates at the end of the line. For multi-line expansion, see Long Macros 64below. 65 66### Short Macro Expansion 67 68* `a macro_name() invocation`<br /> 69 will be replaced by<br /> 70 `a this is the macro expansion invocation` 71* `three macro_name() A macro_name() B macro_name()`<br /> 72 will be replaced by (all during the first iteration)<br /> 73 `three this is the macro expansion A this is the macro expansion B this is the macro expansion` 74 75 76## Long Macros 77 78A long macro can be defined with the syntax: 79 80 LONG MACRO macro_name 81 expansion line 1 82 expansion line 2 83 expansion line 3 84 END MACRO 85 86The macro is then invoked with th enormal `macro_name()` syntax. Leading whitespace/indentation 87will be ignored. 88 89### Long Macro Expansion 90 91The output of a single input line will include one line for each combination of macro expansions on 92that line. That is, the number of output lines is multiplicatively related to the number of macro 93expansions on that line: 94 95* Only a single long macro invocation per line will be expanded during a single iteration. This 96 means that a line may only contain 10 long macro invocations to stay under the iteration count 97 limit. 98* A single invocation of a long macro on a single line will cause that line to expand to the number 99 of lines of the long macro's expansion. On each expanded line, the invocation will be replaced 100 by the corresponding line of the macro's expansion. 101 102* Example 1: 103 104 a macro_name() invocation 105 106 will be replaced by (in a single iteration) 107 108 a expansion line 1 invocation 109 a expansion line 2 invocation 110 a expansion line 3 invocation 111 112* Example 2: 113 114 alpha macro_name() beta macro_name() 115 116 will be replaced by (during the first iteration) 117 118 alpha expansion line 1 beta macro_name() 119 alpha expansion line 2 beta macro_name() 120 alpha expansion line 3 beta macro_name() 121 122 which will be replaced by (during the second iteration) 123 124 alpha expansion line 1 beta expansion line 1 125 alpha expansion line 1 beta expansion line 2 126 alpha expansion line 1 beta expansion line 3 127 alpha expansion line 2 beta expansion line 1 128 alpha expansion line 2 beta expansion line 2 129 alpha expansion line 2 beta expansion line 3 130 alpha expansion line 3 beta expansion line 1 131 alpha expansion line 3 beta expansion line 2 132 alpha expansion line 3 beta expansion line 3 133 134