1 /*
2 * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package jdk.incubator.code;
27
28 import java.util.List;
29 import java.util.Objects;
30 import java.util.function.BiFunction;
31 import java.util.function.Predicate;
32 import java.util.stream.Gatherer;
33 import java.util.stream.Stream;
34
35 /**
36 * A code element, one of {@link Body body}, {@link Block block}, or {@link Op operation}.
37 * <p>
38 * A code may have a parent code element. An unbound code element is an operation, an unbound operation, that has no
39 * parent block. An unbound operation may also be considered a root operation if never bound. A code element and all its
40 * ancestors can be traversed, up to and including the unbound or root operation.
41 * <p>
42 * A code element may have child code elements, and so on. An unbound or root operation and all its descendants can be
43 * traversed, down to and including operations with no children. Bodies and blocks have at least one child element.
44 *
45 * @param <E> the code element type
46 * @param <C> the child code element type.
47 * @sealedGraph
48 */
49 // @@@ E may not be needed
50 public sealed interface CodeElement<
51 E extends CodeElement<E, C>,
52 C extends CodeElement<C, ?>>
53 extends CodeItem
54 permits Body, Block, Op {
55
56 /**
57 * {@return a stream of code elements sorted topologically in pre-order traversal.}
58 */
59 default Stream<CodeElement<?, ?>> elements() {
60 return Stream.of(this).gather(() -> (_, e, downstream) -> traversePreOrder(e, downstream));
61 }
62
63 private static boolean traversePreOrder(CodeElement<?, ?> e, Gatherer.Downstream<? super CodeElement<?, ?>> d) {
64 if (!d.push(e)) {
65 return false;
66 }
67 for (CodeElement<?, ?> c : e.children()) {
68 if (!traversePreOrder(c, d)) {
69 return false;
70 }
71 }
72 return true;
73 }
74
75 /**
76 * Returns the parent element, otherwise {@code null}
77 * if there is no parent.
78 *
79 * @return the parent code element.
80 * @throws IllegalStateException if this element is an operation whose parent block is unbuilt.
81 */
82 CodeElement<?, E> parent();
83
84 // Nearest ancestors
85
86 /**
87 * Finds the nearest ancestor operation, otherwise {@code null}
88 * if there is no nearest ancestor.
89 *
90 * @return the nearest ancestor operation.
91 * @throws IllegalStateException if an operation with unbuilt parent block is encountered.
92 */
93 default Op ancestorOp() {
94 return switch (this) {
95 // block -> body -> op~
96 case Block block -> block.parent().parent();
97 // body -> op~
98 case Body body -> body.parent();
99 // op -> block? -> body -> op~
100 case Op op -> {
101 // Throws ISE if op is not bound
102 Block parent = op.parent();
103 yield parent == null ? null : parent.parent().parent();
104 }
105 };
106 }
107
108 /**
109 * Finds the nearest ancestor body, otherwise {@code null}
110 * if there is no nearest ancestor.
111 *
112 * @return the nearest ancestor body.
113 * @throws IllegalStateException if an operation with unbuilt parent block is encountered.
114 */
115 default Body ancestorBody() {
116 return switch (this) {
117 // block -> body
118 case Block block -> block.parent();
119 // body -> op~ -> block? -> body
120 case Body body -> {
121 // Throws ISE if block is partially constructed
122 Block ancestor = body.parent().parent();
123 yield ancestor == null ? null : ancestor.parent();
124 }
125 // op~ -> block? -> body
126 case Op op -> {
127 // Throws ISE if op is not bound
128 Block parent = op.parent();
129 yield parent == null ? null : parent.parent();
130 }
131 };
132 }
133
134 /**
135 * Finds the nearest ancestor block, otherwise {@code null}
136 * if there is no nearest ancestor.
137 *
138 * @return the nearest ancestor block.
139 * @throws IllegalStateException if an operation with unbuilt parent block is encountered.
140 */
141 default Block ancestorBlock() {
142 return switch (this) {
143 // block -> body -> op~ -> block?
144 // Throws ISE if op is not bound
145 case Block block -> block.parent().parent().parent();
146 // body -> op~ -> block?
147 // Throws ISE if op is not bound
148 case Body body -> body.parent().parent();
149 // op~ -> block?
150 // Throws ISE if op is not bound
151 case Op op -> op.parent();
152 };
153 }
154
155 /**
156 * Returns true if this element is an ancestor of the descendant element.
157 *
158 * @param descendant the descendant element.
159 * @return true if this element is an ancestor of the descendant element.
160 */
161 default boolean isAncestorOf(CodeElement<?, ?> descendant) {
162 Objects.requireNonNull(descendant);
163
164 CodeElement<?, ?> e = descendant.parent();
165 while (e != null && e != this) {
166 e = e.parent();
167 }
168 return e != null;
169 }
170
171 /**
172 * Returns the child code elements, as an unmodifiable list.
173 *
174 * @return the child code elements
175 */
176 List<C> children();
177
178 // Siblings
179 // Left, right
180
181 // Des
182 }