Core Language Implementation API

/**
 * Base class for implementing Truffle languages. Must be annotated with @Registration.
 */
public abstract class TruffleLanguage<C> {
    
    /**
     * Create a new context for this language
     * @param env The language environment
     * @return New context instance  
     */
    protected abstract C createContext(Env env);
    
    /**
     * Parse source code and return executable call target
     * @param request Parsing request with source and context
     * @return CallTarget for execution
     */
    protected abstract CallTarget parse(ParsingRequest request) throws Exception;
    
    /**
     * Get language context for current thread
     * @return Current context instance
     */
    protected final C getCurrentContext();
    
    /**
     * Get language environment
     * @return Current environment
     */
    protected final Env getCurrentEnv();
    
    /**
     * Check if context pre-initialization is supported
     * @return true if pre-initialization supported
     */
    protected boolean areOptionsCompatible(OptionValues firstOptions, OptionValues newOptions);
    
    /**
     * Language registration annotation
     */
    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.TYPE)
    public @interface Registration {
        String id();
        String name();
        String version() default "";
        String[] mimeType() default {};
        boolean interactive() default true;
        boolean internal() default false;
    }
    
    /**
     * Language environment providing access to system services
     */
    public static final class Env {
        
        /**
         * Get file system access for internal files
         * @param path File path
         * @return TruffleFile instance
         */
        public TruffleFile getInternalTruffleFile(String path);
        
        /**
         * Get public file system access
         * @param path File path  
         * @return TruffleFile instance
         */
        public TruffleFile getPublicTruffleFile(String path);
        
        /**
         * Get logger for this language
         * @param loggerName Logger name
         * @return TruffleLogger instance
         */
        public TruffleLogger getLogger(String loggerName);
        
        /**
         * Register service for other languages/instruments
         * @param service Service object
         */
        public void registerService(Object service);
        
        /**
         * Get option values for this language
         * @return OptionValues instance
         */
        public OptionValues getOptions();
        
        /**
         * Check if context pre-initialization active
         * @return true if pre-initializing
         */
        public boolean isPreInitialization();
    }
    
    /**
     * Parsing request containing source and context information
     */  
    public static final class ParsingRequest {
        
        /**
         * Get source to parse
         * @return Source instance
         */
        public Source getSource();
        
        /**
         * Get argument names for top-level function
         * @return Array of argument names
         */
        public String[] getArgumentNames();
    }
}

@TruffleLanguage.Registration(id = "mylang", name = "MyLanguage", version = "1.0")
public final class MyLanguage extends TruffleLanguage<MyContext> {
    
    @Override
    protected MyContext createContext(Env env) {
        return new MyContext(env);
    }
    
    @Override
    protected CallTarget parse(ParsingRequest request) throws Exception {
        Source source = request.getSource();
        // Parse source and build AST
        MyRootNode rootNode = MyParser.parse(source, this);
        return rootNode.getCallTarget();
    }
}

/**
 * Base class for all AST nodes in Truffle
 */
public abstract class Node implements NodeInterface, Cloneable {
    
    /**
     * Replace this node with a new node in the AST
     * @param newNode Replacement node
     * @return The new node
     */
    public final <T extends Node> T replace(T newNode);
    
    /**
     * Insert new child nodes into this node
     * @param newChildren New child nodes
     * @return Array of inserted nodes
     */
    public final <T extends Node> T[] insert(T[] newChildren);
    
    /**
     * Get execution cost hint for this node
     * @return NodeCost enum value
     */
    public final NodeCost getCost();
    
    /**
     * Get source section for this node
     * @return SourceSection or null
     */
    public final SourceSection getSourceSection();
    
    /**
     * Set source section for this node
     * @param sourceSection Source section
     */
    public final void setSourceSection(SourceSection sourceSection);
    
    /**
     * Get root node containing this node
     * @return RootNode ancestor
     */
    public final RootNode getRootNode();
    
    /**
     * Called when node is inserted into AST
     * @param newChild Child node being inserted
     */
    protected final void notifyInserted(Node newChild);
    
    /**
     * Accept node visitor
     * @param visitor NodeVisitor instance
     */
    public final void accept(NodeVisitor visitor);
    
    /**
     * Get description for debugging
     * @return String description
     */
    public String getDescription();
}

/**
 * Root node of an executable AST
 */
public abstract class RootNode extends Node {
    
    /**
     * Create root node for language
     * @param language TruffleLanguage instance
     */
    protected RootNode(TruffleLanguage<?> language);
    
    /**
     * Create root node with frame descriptor
     * @param language TruffleLanguage instance
     * @param frameDescriptor Frame descriptor
     */
    protected RootNode(TruffleLanguage<?> language, FrameDescriptor frameDescriptor);
    
    /**
     * Execute this root node
     * @param frame Execution frame
     * @return Execution result
     */
    public abstract Object execute(VirtualFrame frame);
    
    /**
     * Get call target for this root node
     * @return CallTarget instance
     */
    public final CallTarget getCallTarget();
    
    /**
     * Get name of this root node
     * @return Name string
     */
    public String getName();
    
    /**
     * Get frame descriptor
     * @return FrameDescriptor instance
     */
    public final FrameDescriptor getFrameDescriptor();
    
    /**
     * Check if this root node can be cloned
     * @return true if clonable
     */
    public boolean isCloningAllowed();
    
    /**
     * Create split version of this root node
     * @return Split RootNode
     */
    protected RootNode cloneUninitialized();
}

/**
 * Node for executing other executable nodes
 */
public abstract class ExecutableNode extends Node {
    
    /**
     * Execute this node
     * @param frame Execution frame
     * @return Execution result
     */
    public abstract Object execute(VirtualFrame frame);
}

/**
 * Node for direct method calls with caching
 */
public abstract class DirectCallNode extends Node {
    
    /**
     * Create direct call node
     * @param callTarget Target to call
     * @return DirectCallNode instance
     */
    public static DirectCallNode create(CallTarget callTarget);
    
    /**
     * Call target with arguments
     * @param arguments Call arguments
     * @return Call result
     */
    public abstract Object call(Object[] arguments);
    
    /**
     * Get call target
     * @return CallTarget instance
     */
    public abstract CallTarget getCallTarget();
    
    /**
     * Check if call site is inlinable
     * @return true if inlinable
     */
    public abstract boolean isInlinable();
    
    /**
     * Check if call can be inlined
     * @return true if can inline
     */
    public abstract boolean isCallTargetCloningAllowed();
}

/**
 * Node for indirect method calls
 */
public abstract class IndirectCallNode extends Node {
    
    /**
     * Create indirect call node
     * @return IndirectCallNode instance
     */
    public static IndirectCallNode create();
    
    /**
     * Call target with arguments
     * @param callTarget Target to call
     * @param arguments Call arguments
     * @return Call result
     */
    public abstract Object call(CallTarget callTarget, Object[] arguments);
}

/**
 * Base interface for execution frames
 */
public interface Frame {
    
    /**
     * Get frame descriptor
     * @return FrameDescriptor instance
     */
    FrameDescriptor getFrameDescriptor();
    
    /**
     * Get call arguments
     * @return Arguments array
     */
    Object[] getArguments();
}

/**
 * Virtual frame for efficient execution
 */
public interface VirtualFrame extends Frame {
    
    /**
     * Get object value from frame slot
     * @param slot Frame slot index
     * @return Object value
     * @throws FrameSlotTypeException if wrong type
     */
    Object getObject(int slot) throws FrameSlotTypeException;
    
    /**
     * Set object value in frame slot
     * @param slot Frame slot index
     * @param value Object value  
     */
    void setObject(int slot, Object value);
    
    /**
     * Get byte value from frame slot
     * @param slot Frame slot index
     * @return byte value
     * @throws FrameSlotTypeException if wrong type
     */
    byte getByte(int slot) throws FrameSlotTypeException;
    
    /**
     * Set byte value in frame slot
     * @param slot Frame slot index
     * @param value byte value
     */
    void setByte(int slot, byte value);
    
    /**
     * Get boolean value from frame slot
     * @param slot Frame slot index
     * @return boolean value
     * @throws FrameSlotTypeException if wrong type
     */
    boolean getBoolean(int slot) throws FrameSlotTypeException;
    
    /**
     * Set boolean value in frame slot
     * @param slot Frame slot index
     * @param value boolean value
     */
    void setBoolean(int slot, boolean value);
    
    /**
     * Get int value from frame slot
     * @param slot Frame slot index
     * @return int value
     * @throws FrameSlotTypeException if wrong type
     */
    int getInt(int slot) throws FrameSlotTypeException;
    
    /**
     * Set int value in frame slot
     * @param slot Frame slot index
     * @param value int value
     */
    void setInt(int slot, int value);
    
    /**
     * Get long value from frame slot
     * @param slot Frame slot index
     * @return long value
     * @throws FrameSlotTypeException if wrong type
     */
    long getLong(int slot) throws FrameSlotTypeException;
    
    /**
     * Set long value in frame slot
     * @param slot Frame slot index
     * @param value long value
     */
    void setLong(int slot, long value);
    
    /**
     * Get float value from frame slot
     * @param slot Frame slot index
     * @return float value
     * @throws FrameSlotTypeException if wrong type
     */
    float getFloat(int slot) throws FrameSlotTypeException;
    
    /**
     * Set float value in frame slot
     * @param slot Frame slot index
     * @param value float value
     */
    void setFloat(int slot, float value);
    
    /**
     * Get double value from frame slot
     * @param slot Frame slot index
     * @return double value
     * @throws FrameSlotTypeException if wrong type
     */
    double getDouble(int slot) throws FrameSlotTypeException;
    
    /**
     * Set double value in frame slot
     * @param slot Frame slot index
     * @param value double value
     */
    void setDouble(int slot, double value);
    
    /**
     * Materialize this virtual frame
     * @return MaterializedFrame instance
     */
    MaterializedFrame materialize();
}

/**
 * Materialized frame for persistent access
 */
public interface MaterializedFrame extends Frame {
    
    /**
     * Get object value from frame slot
     * @param slot Frame slot index
     * @return Object value
     */
    Object getObject(int slot);
    
    /**
     * Set object value in frame slot
     * @param slot Frame slot index
     * @param value Object value
     */
    void setObject(int slot, Object value);
}

/**
 * Descriptor defining frame layout
 */
public final class FrameDescriptor implements Cloneable {
    
    /**
     * Create new frame descriptor
     * @return FrameDescriptor instance
     */
    public static FrameDescriptor create();
    
    /**
     * Create frame descriptor with default value
     * @param defaultValue Default slot value
     * @return FrameDescriptor instance
     */
    public static FrameDescriptor create(Object defaultValue);
    
    /**
     * Add new frame slot
     * @param identifier Slot identifier
     * @return FrameSlot instance
     */
    public FrameSlot addFrameSlot(Object identifier);
    
    /**
     * Add frame slot with type hint
     * @param identifier Slot identifier
     * @param kind Type hint
     * @return FrameSlot instance
     */
    public FrameSlot addFrameSlot(Object identifier, FrameSlotKind kind);
    
    /**
     * Find existing frame slot
     * @param identifier Slot identifier
     * @return FrameSlot or null
     */
    public FrameSlot findFrameSlot(Object identifier);
    
    /**
     * Get all frame slots
     * @return List of FrameSlot instances
     */
    public List<? extends FrameSlot> getSlots();
    
    /**
     * Get frame size
     * @return Number of slots
     */
    public int getSize();
}

/**
 * Frame slot for variable storage
 */
public final class FrameSlot implements Cloneable {
    
    /**
     * Get slot identifier
     * @return Identifier object
     */
    public Object getIdentifier();
    
    /**
     * Get slot type hint
     * @return FrameSlotKind enum
     */
    public FrameSlotKind getKind();
    
    /**
     * Set slot type hint
     * @param kind New type hint
     */
    public void setKind(FrameSlotKind kind);
    
    /**
     * Get slot index
     * @return Slot index
     */
    public int getIndex();
}

/**
 * Type hints for frame slots
 */
public enum FrameSlotKind {
    Object, Long, Int, Double, Float, Boolean, Byte, Illegal
}

/**
 * Exception for frame slot type mismatches
 */
public final class FrameSlotTypeException extends SlowPathException {
    public static FrameSlotTypeException create();
}

/**
 * Represents source code for parsing and execution
 */
public final class Source {
    
    /**
     * Create source builder
     * @param language Language identifier
     * @param characters Source text
     * @param name Source name
     * @return Builder instance
     */
    public static Builder newBuilder(String language, CharSequence characters, String name);
    
    /**
     * Create source from file
     * @param language Language identifier
     * @param file TruffleFile instance
     * @return Builder instance
     */
    public static Builder newBuilder(String language, TruffleFile file);
    
    /**
     * Get source characters
     * @return Source text
     */
    public CharSequence getCharacters();
    
    /**
     * Get source name
     * @return Source name
     */
    public String getName();
    
    /**
     * Get source language
     * @return Language identifier
     */
    public String getLanguage();
    
    /**
     * Get source path
     * @return Path string or null
     */
    public String getPath();
    
    /**
     * Get source URI
     * @return URI or null
     */
    public URI getURI();
    
    /**
     * Check if source is interactive
     * @return true if interactive
     */
    public boolean isInteractive();
    
    /**
     * Check if source is internal
     * @return true if internal
     */
    public boolean isInternal();
    
    /**
     * Get MIME type
     * @return MIME type string
     */
    public String getMimeType();
    
    /**
     * Get character count
     * @return Number of characters
     */
    public int getLength();
    
    /**
     * Get line count
     * @return Number of lines
     */
    public int getLineCount();
    
    /**
     * Create source section
     * @param startIndex Start character index
     * @param length Character length
     * @return SourceSection instance
     */
    public SourceSection createSection(int startIndex, int length);
    
    /**
     * Create unavailable source section
     * @return SourceSection instance
     */
    public SourceSection createUnavailableSection();
    
    /**
     * Source builder class
     */
    public static final class Builder {
        
        /**
         * Set source name
         * @param name Source name
         * @return Builder instance
         */
        public Builder name(String name);
        
        /**
         * Set MIME type
         * @param mimeType MIME type
         * @return Builder instance
         */
        public Builder mimeType(String mimeType);
        
        /**
         * Mark as interactive source
         * @return Builder instance
         */
        public Builder interactive();
        
        /**
         * Mark as internal source
         * @return Builder instance
         */
        public Builder internal();
        
        /**
         * Set encoding
         * @param encoding Character encoding
         * @return Builder instance
         */
        public Builder encoding(Charset encoding);
        
        /**
         * Set URI
         * @param uri Source URI
         * @return Builder instance
         */
        public Builder uri(URI uri);
        
        /**
         * Build source
         * @return Source instance
         */
        public Source build() throws IOException;
    }
}

/**
 * Represents a section of source code
 */
public final class SourceSection {
    
    /**
     * Check if source section is available
     * @return true if available
     */
    public boolean isAvailable();
    
    /**
     * Get containing source
     * @return Source instance
     */
    public Source getSource();
    
    /**
     * Get start line number (1-based)
     * @return Start line
     */
    public int getStartLine();
    
    /**
     * Get start column number (1-based)
     * @return Start column
     */
    public int getStartColumn();
    
    /**
     * Get end line number (1-based)
     * @return End line
     */
    public int getEndLine();
    
    /**
     * Get end column number (1-based)
     * @return End column
     */
    public int getEndColumn();
    
    /**
     * Get character index (0-based)
     * @return Start character index
     */
    public int getCharIndex();
    
    /**
     * Get character length
     * @return Number of characters
     */
    public int getCharLength();
    
    /**
     * Get end character index (0-based)
     * @return End character index
     */
    public int getCharEndIndex();
    
    /**
     * Get source characters for this section
     * @return Character sequence
     */
    public CharSequence getCharacters();
}

/**
 * Executable call target
 */
public interface CallTarget {
    
    /**
     * Call with arguments
     * @param arguments Call arguments
     * @return Execution result
     */
    Object call(Object... arguments);
}

/**
 * Root call target for RootNode execution
 */  
public interface RootCallTarget extends CallTarget {
    
    /**
     * Get root node
     * @return RootNode instance
     */
    RootNode getRootNode();
}

/**
 * Node execution cost hint
 */
public enum NodeCost {
    NONE, MONOMORPHIC, POLYMORPHIC, MEGAMORPHIC, UNINITIALIZED
}

/**
 * Node visitor interface
 */
public interface NodeVisitor {
    
    /**
     * Visit node
     * @param node Node to visit
     * @return true to continue visiting
     */
    boolean visit(Node node);
}