1 /*
2 * ASIfStatement.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 uk.co.badgersinfoil.metaas.SyntaxException;
22
23 /**
24 * An if-statement, such as <code>if (a) { doSomething(); }</code>.
25 *
26 * <p>ASIfStatement is a {@link StatementContainer} to simplify the common
27 * case where the attached statement (as returned by getThenStatement()) is
28 * a block (very handy if you are <em>generating</em> code using metaas). If
29 * the attached statement is not a block, attempting to call StatementContainer
30 * methods directly on this if-statement will fail with an exception, so it is
31 * generally required to call getThenStatement() rather than attempting to
32 * use StatementContainer methods on the ASIfStatement, or code which was
33 * parsed.</p>
34 *
35 * <p>e.g. To simply add statements to the 'then' branch (executed when
36 * the condition holds true),</p>
37 * <pre class="eg">
38 * ASIfStatement ifStmt = method.newIf("test()");
39 * isStmt.addStmt("trace('test succeeded')");</pre>
40 * <p>will result in ActionScript code like,</p>
41 * <pre class="eg">
42 * if (test()) {
43 * trace('test succeeded');
44 * }</pre>
45 *
46 * <p>To add code to both 'then' and 'else' branches,</p>
47 * <pre class="eg">
48 * ASIfStatement ifStmt = method.newIf("test()");
49 * ifStmt.addStmt("trace('test succeeded')");
50 * ifStmt.elseBlock().addStmt("trace('test failed')");</pre>
51 * <p>will result in ActionScript code like,</p>
52 * <pre class="eg">
53 * if (test()) {
54 * trace('test succeeded');
55 * } else {
56 * trace('test failed');
57 * }</pre>
58 *
59 * <p>Note that the first call to elseBlock() will cause the else-clause to be
60 * created with a block attached to it (even if no statements are subsequently
61 * added). Subsequent calls to elseBlock() will return references to the same
62 * block, rather than creating further code.</p>
63 *
64 * @see StatementContainer#newIf(Expression)
65 */
66 public interface ASIfStatement extends Statement, StatementContainer {
67
68 /**
69 * @deprecated use {@link #elseBlock()}.
70 */
71 public ASBlock getElse();
72
73 /**
74 * Returns a reference to an object which can populate the else-clause
75 * of this ActionScript if-statement with new code. If no else-clause
76 * is attached to this if-statement, one will be automatically added as
77 * a result of calling this method.
78 *
79 * @throws SyntaxException if this if-statement already has an
80 * else-clause attached and the statement in the else-clause is
81 * something other than a block-statement.
82 */
83 public ASBlock elseBlock();
84
85 /**
86 * Returns the statement attached to the else-clause of this
87 * if-statement, or null if no else-clause is present.
88 */
89 public Statement getElseStatement();
90
91 public Statement getThenStatement();
92
93 public void setThenStatement(Statement then);
94
95 /** @deprecated Use {@link #setThenStatement(Statement)} */
96 public void setThen(ASBlock thenBlock);
97
98 /**
99 * Returns a string representation of the condition-expression for
100 * this if-statement. e.g. for the expression
101 * <code>if (test()) { }</code>, this method will return the string
102 * <code>"test()"</code>.
103 */
104 public String getConditionString();
105
106 public Expression getCondition();
107
108 /**
109 * Changes the condition-expression for this if-statement.
110 *
111 * @throws uk.co.badgersinfoil.metaas.SyntaxException if the given
112 * string is not a valid ActionScript expression.
113 */
114 public void setCondition(String expr);
115
116 public void setCondition(Expression expr);
117 }