com.google.template.soy.basetree.Node Maven / Gradle / Ivy
Show all versions of soy Show documentation
/*
* Copyright 2008 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.google.template.soy.basetree;
import com.google.template.soy.base.SourceLocation;
import javax.annotation.Nullable;
/**
* This class defines the base interface for a node in the parse tree, as well as a number of
* subinterfaces that extend the base interface in various aspects. Every concrete node implements
* some subset of these interfaces.
*
* The top level definition is the base node interface.
*
*
Important: Do not use outside of Soy code (treat as superpackage-private).
*
*/
public interface Node {
/**
* Returns a pair (syntaxVersion, reasonStr), where the first item is the lowest known upper bound
* (exclusive!) for the syntax version of this node, and the second item is a user-friendly
* explanation of the reason for the bound. For example: (V2_1, "Function hasData() is unnecessary
* and no longer allowed.") Returns null if there is no known upper bound on this node's syntax
* version.
*/
@Nullable
SyntaxVersionUpperBound getSyntaxVersionUpperBound();
/**
* Records a newly discovered upper bound for the syntax version of this node.
*
* @param newSyntaxVersionBound A newly discovered upper bound (exclusive!) for the syntax version
* of this node.
*/
void maybeSetSyntaxVersionUpperBound(SyntaxVersionUpperBound newSyntaxVersionBound);
/**
* Returns false if we know that this node's syntax version must be lower than the given value.
* Returns true otherwise (i.e. with what we know so far, this node could be the given syntax
* version or higher).
*
* @param syntaxVersionCutoff The syntax version cutoff to check.
*/
boolean couldHaveSyntaxVersionAtLeast(SyntaxVersion syntaxVersionCutoff);
/** Returns the source location (file path and line number) for this node. */
SourceLocation getSourceLocation();
/**
* Sets this node's parent.
*
* @param parent The parent node to set.
*/
void setParent(ParentNode parent);
/**
* Gets this node's parent.
*
* @return This node's parent.
*/
ParentNode getParent();
/**
* Determines whether this node has an ancestor of the given type. The ancestor can be this node
* (i.e. doesn't have to be a proper ancestor).
*
* @param ancestorClass The type of ancestor to look for.
* @return True if this node has an ancestor of the given type.
*/
boolean hasAncestor(Class ancestorClass);
/**
* Finds and returns this node's nearest ancestor of the given type. The ancestor can be this node
* (i.e. doesn't have to be a proper ancestor).
*
* @param The type of ancestor to retrieve.
* @param ancestorClass The class object for the type of ancestor to retrieve.
* @return This node's nearest ancestor of the given type, or null if none.
*/
N getNearestAncestor(Class ancestorClass);
/**
* Builds a Soy source string that could be the source for this node. Note that this is not the
* actual original source string, but a (SORT OF, NOT QUITE) canonical equivalent.
*
* Note: Some nodes do not have a direct mapping to Soy source (such as nodes created during
* some optimization passes). Thus this method may not always be supported.
*
* @return A Soy string that could be the source for this node.
* @throws UnsupportedOperationException If this node does not directly map to Soy source.
*/
String toSourceString();
/**
* Copies this node. The copy's parent pointer is set to null.
*
*
All copy() overrides should follow this contract:
*
*
* - only leaf classes (in the class hierarchy) should have non-abstract clone methods
*
- all leaf classes should be final
*
- all leaf copy constructors should be private
*
- all clone methods should look exactly like:
*
{@code
* {@literal @}Override public T copy(CopyState copyState) {
* return new T(this, copyState);
* }
* }
*
* - all non-leaf copy constructors should be protected
*
*
* TODO(lukes): The usecases for a copy method are few and far between. Making the AST nodes
* immutable (or at least unmodifiable) would be preferable to maintaining our copy() methods.
*
*
Don't clone nodes unless you know what you're doing. The Soy AST is not actually a tree (it
* contains back edges from variables to their definitions), and naively copying nodes can result
* in pointers into stale ASTs
*
* @return A clone of this code.
*/
Node copy(CopyState copyState);
}