1 /*
2 * StatementContainer.java
3 *
4 * Copyright (c) 2006-2008 David Holroyd
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19 package uk.co.badgersinfoil.metaas.dom;
20
21 import java.util.List;
22 import uk.co.badgersinfoil.metaas.SyntaxException;
23
24 /**
25 * Defines the common services provided by structures which can contain
26 * ActionScript 'statements'.
27 *
28 * <p>Some elements in the metaas DOM extend StatementContainer while they are not
29 * strictly containers for multiple statements. This is a convinience for
30 * the common case where the element in question usually appears with an
31 * attached block-statement. So, for example, rather than writing...</p>
32 *
33 * <pre class="eg">List stmts = ((ASBlock)ifStmt.getThenStatement()).getStatementList();</pre>
34 *
35 * <p>...we can instead write...</p>
36 *
37 * <pre class="eg">List stmts = ifStmt.getStatementList();</pre>
38 *
39 * If, in the above example, the 'then-clause' of the ASIfStatement was not
40 * actually a block, a SyntaxException would be raised.
41 */
42 public interface StatementContainer {
43 /**
44 * Checks the syntax of the given code, and then adds the statement to
45 * the end of the current block.
46 *
47 * @throws SyntaxException if the syntax of the given code fragment is
48 * incorrect.
49 */
50 public Statement addStmt(String statement);
51
52
53 /**
54 * Adds a new expression-statement to the code, and returns a reference
55 * to it. An 'expression-statement' is a statement that just contains
56 * an expression (followed in normal ActionScript by a semicolon, though
57 * that should be omitted from the supplied string).
58 */
59 public ASExpressionStatement newExprStmt(String expr);
60
61 public ASExpressionStatement newExprStmt(Expression expr);
62
63 /**
64 * Adds a single-line comment to list of statements being generated
65 *
66 * @param text the text of the comment (minus the initial '//') which
67 * must not include any newline characters.
68 */
69 public void addComment(String text);
70
71 /**
72 * Adds an if-statement to the code. e.g.
73 * <pre>block.newIf("test()").addStmt("trace('success')")</pre>
74 * results in
75 * <pre>
76 * if (test()) {
77 * trace('success');
78 * }</pre>
79 */
80 public ASIfStatement newIf(String condition);
81 public ASIfStatement newIf(Expression condition);
82
83 /**
84 * Adds a C-style for-loop to the code. e.g.
85 * <pre>block.newFor("var i=0", "i<10", "i++").addStmt("trace(i)")</pre>
86 * results in
87 * <pre>
88 * for (var i=0; i<10; i++) {
89 * trace(i);
90 * }</pre>
91 */
92 public ASForStatement newFor(String init, String condition, String update);
93 public ASForStatement newFor(Expression init, Expression condition, Expression update);
94
95 /**
96 * Adds a for-in-loop to the code. e.g.
97 * <pre>block.newForIn("var i", "myArray").addStmt("trace(i)")</pre>
98 * results in
99 * <pre>
100 * for (var i in myArray) {
101 * trace(i);
102 * }</pre>
103 */
104 public ASForInStatement newForIn(String init, String list);
105 public ASForInStatement newForIn(Expression init, Expression list);
106
107 public ASForEachInStatement newForEachIn(String init, String list);
108 public ASForEachInStatement newForEachIn(Expression init, Expression list);
109
110 /**
111 * Adds a while-loop to the code. e.g.
112 * <pre>block.newWhile("test()").addStmt("trace('hi there')")</pre>
113 * results in
114 * <pre>
115 * while (test()) {
116 * trace('hi there');
117 * }</pre>
118 */
119 public ASWhileStatement newWhile(String condition);
120 public ASWhileStatement newWhile(Expression condition);
121
122 /**
123 * Adds a do-while-loop to the code. e.g.
124 * <pre>block.newDoWhile("test()").addStmt("trace('hi there')")</pre>
125 * results in
126 * <pre>
127 * do {
128 * trace('hi there');
129 * } while (test());</pre>
130 */
131 public ASDoWhileStatement newDoWhile(String condition);
132 public ASDoWhileStatement newDoWhile(Expression condition);
133
134 /**
135 * Adds a switch-statement to the code. See {@link ASSwitchStatement}
136 * for more information.
137 */
138 public ASSwitchStatement newSwitch(String condition);
139 public ASSwitchStatement newSwitch(Expression condition);
140
141 /**
142 * Adds a new with-statement to the code, and returns a reference to
143 * it. e.g.
144 * <pre class="eg">method.newWith("value").addStmt("trace(test)");</pre>
145 * <p>results in,</p>
146 * <pre class="eg">with (value) {
147 * trace(test);
148 * }</pre>
149 */
150 public ASWithStatement newWith(String string);
151 public ASWithStatement newWith(Expression string);
152
153 /**
154 * Adds a new variable declaration to the code, and returns a reference
155 * to it. e.g.
156 * <pre class="eg">method.newDeclaration("a=1");</pre>
157 * <p>results in,</p>
158 * <pre class="eg">var a=1;</pre>
159 */
160 public ASDeclarationStatement newDeclaration(String assignment);
161 public ASDeclarationStatement newDeclaration(Expression assignment);
162
163 /**
164 * Adds a new return-statement to the code (with optional return
165 * expression), and returns a reference to it. e.g.
166 * <pre class="eg">method.newReturn(null);</pre>
167 * <p>results in a plain return statement,</p>
168 * <pre class="eg">return;</pre>
169 * <p>Whereas passing an expression,</p>
170 * <pre class="eg">method.newReturn("theVal()");</pre>
171 * <p>results will cause that expression to be returned,</p>
172 * <pre class="eg">return theVal();</pre>
173 */
174 public ASReturnStatement newReturn(String expr);
175 public ASReturnStatement newReturn(Expression expr);
176 public ASReturnStatement newReturn();
177
178 /**
179 * Adds a call to the superclass constructor (assuming that this is
180 * itself a constructor).
181 */
182 public ASSuperStatement newSuper(List arguments);
183
184 /**
185 * Creates a new <code>break</code> statement.
186 */
187 public ASBreakStatement newBreak();
188
189 public ASTryStatement newTryCatch(String var, String type);
190
191 public ASTryStatement newTryFinally();
192
193 public ASContinueStatement newContinue();
194
195 public ASThrowStatement newThrow(Expression t);
196
197 public ASDefaultXMLNamespaceStatement newDefaultXMLNamespace(String namespace);
198
199 /**
200 * Returns true if if this container currently contains at
201 * least one statement, and false if it is empty, or contains only
202 * comments and whitespace.
203 */
204 public boolean containsCode();
205
206 /**
207 * Returns a list of the {@link Statement} objects held in the
208 * containing element. The list is immutable (entries cannnot be
209 * added, removed or replaced) but the objects obtained from the list
210 * my be modified via the methods they provide.
211 */
212 public List getStatementList();
213 }