org.jruby.compiler
Interface Compiler

All Known Implementing Classes:
StandardASMCompiler

public interface Compiler

Compiler represents the current state of a compiler and all appropriate transitions and modifications that can be made within it. The methods here begin and end a class for a given compile run, begin and end methods for the script being compiled, set line number information, and generate code for all the basic operations necessary for a script to run. The intent of this interface is to provide a library-neutral set of functions for compiling a given script using any backend or any output format.


Method Summary
 void assignClassVariable(java.lang.String name)
           
 void assignConstantInCurrent(java.lang.String name)
           
 void assignConstantInModule(java.lang.String name)
           
 void assignConstantInObject(java.lang.String name)
           
 void assignGlobalVariable(java.lang.String name)
          Assign the top of the stack to the global variable with the specified name.
 void assignGlobalVariableBlockArg(int index, java.lang.String name)
          Assign the value from incoming block args to the global variable with the specified name.
 void assignInstanceVariable(java.lang.String name)
          Assign the value on top of the stack to the instance variable with the specified name on the current "self".
 void assignInstanceVariableBlockArg(int index, java.lang.String name)
          Assign the value from incoming block args instance variable with the specified name on the current "self".
 void assignLastLine()
          Assigns the special "last line" variable $_ in the outermost local scope.
 void assignLocalVariable(int index)
          Assigns the value on top of the stack to a local variable at the specified index, consuming that value in the process.
 void assignLocalVariable(int index, int depth)
          Assign the value on top of the stack to a local variable at the specified index and lexical scoping depth (0 = current scope), consuming that value in the process.
 void assignLocalVariableBlockArg(int argIndex, int varIndex)
          Assigns the value from incoming block args to a local variable at the specified index, consuming that value in the process.
 void assignLocalVariableBlockArg(int argIndex, int varIndex, int depth)
          Assign the value from incoming block args to a local variable at the specified index and lexical scoping depth (0 = current scope), consuming that value in the process.
 void assignOptionalArgs(java.lang.Object object, int expectedArgsCount, int size, ArrayCallback optEval)
           
 void asString()
           
 java.lang.Object beginMethod(java.lang.String friendlyName, ClosureCallback argsHandler)
          Begin compilation for a method that has the specified number of local variables.
 void consumeCurrentValue()
          As code executes, values are assumed to be "generated", often by being pushed on to some execution stack.
 void createEmptyArray()
          Create an empty Ruby array
 void createEmptyHash()
          Create an empty Ruby Hash object and put a reference on top of the stack.
 void createNewArray()
          Given an aggregated set of objects (likely created through a call to createObjectArray) create a Ruby array object.
 void createNewBignum(java.math.BigInteger value)
          Generate a new "Bignum" value.
 void createNewClosure(StaticScope scope, int arity, ClosureCallback body, ClosureCallback args)
          Create a new closure (block) using the given lexical scope information, call arity, and body generated by the body callback.
 void createNewFixnum(long value)
          Generate a new "Fixnum" value.
 void createNewFloat(double value)
          Generate a new "Float" value.
 void createNewHash(java.lang.Object elements, ArrayCallback callback, int keyCount)
          Create a new hash by calling back to the specified ArrayCallback.
 void createNewRange(boolean isExclusive)
          Create a new range.
 void createNewRegexp(ByteList value, int options, java.lang.String lang)
           
 void createNewString(ArrayCallback callback, int count)
          Generate a new dynamic "String" value.
 void createNewString(ByteList value)
          Generate a new "String" value.
 void createNewSymbol(java.lang.String name)
          Generate a new "Symbol" value (or fetch the existing one).
 void createObjectArray(int elementCount)
          Combine the top
 void createObjectArray(java.lang.Object[] elementArray, ArrayCallback callback)
           
 void defineAlias(java.lang.String newName, java.lang.String oldName)
          Define an alias for a new name to an existing oldName'd method.
 void defineClass(java.lang.String name, StaticScope staticScope, ClosureCallback superCallback, ClosureCallback pathCallback, ClosureCallback bodyCallback)
           
 void defineModule(java.lang.String name, StaticScope staticScope, ClosureCallback pathCallback, ClosureCallback bodyCallback)
           
 void defineNewMethod(java.lang.String name, StaticScope scope, ClosureCallback body, ClosureCallback args)
          Define a new method with the given name, arity, local variable count, and body callback.
 void duplicateCurrentValue()
          Push a copy the topmost value on the stack.
 void endMethod(java.lang.Object token)
          End compilation for the method associated with the specified token.
 void endScript()
          End compilation for the current script, closing all context and structures used for the compilation.
 void ensureRubyArray()
          Ensures that the present value is an IRubyObject[] by wrapping it with one if it is not.
 void forEachInValueArray(int count, int start, java.lang.Object source, ArrayCallback callback)
          Given an IRubyObject[] on the stack (or otherwise available as the present object) call back to the provided ArrayCallback 'callback' for 'count' elements, starting with 'start'.
 void invokeAttrAssign(java.lang.String name)
          Attr assign calls have slightly different semantics that normal calls, so this method handles those additional semantics.
 void invokeDynamic(java.lang.String name, boolean hasReceiver, boolean hasArgs, CallType callType, ClosureCallback closureArg, boolean attrAssign)
          Invoke the named method as a "function", i.e.
 void issueBreakEvent()
           
 void lineNumber(ISourcePosition position)
          This method provides a way to specify a line number for the current piece of code being compiled.
 void loadFalse()
          Load a Ruby "false" value on top of the stack.
 void loadInteger(int value)
          Load an integer value suitable for numeric comparisons
 void loadNil()
          Load a Ruby "nil" value on top of the stack.
 void loadObject()
          Load the Object class
 void loadRubyArraySize()
           
 void loadSymbol(java.lang.String symbol)
          Load the given string as a symbol on to the top of the stack.
 void loadTrue()
          Load a Ruby "true" value on top of the stack.
 void match()
           
 void match2()
           
 void match3()
           
 void negateCurrentValue()
          Perform a logical Ruby "not" operation on the value on top of the stack, leaving the negated result.
 void nthRef(int match)
           
 void performBooleanBranch(BranchCallback trueBranch, BranchCallback falseBranch)
          Perform a boolean branch operation based on the Ruby "true" value of the top value on the stack.
 void performBooleanLoop(BranchCallback condition, BranchCallback body, boolean checkFirst)
          Perform a boolean loop using the given condition-calculating branch and body branch.
 void performGEBranch(BranchCallback trueBranch, BranchCallback falseBranch)
          Perform a greater-than-or-equal test and branch, given the provided true and false branches.
 void performGTBranch(BranchCallback trueBranch, BranchCallback falseBranch)
          Perform a greater-than test and branch, given the provided true and false branches.
 void performLEBranch(BranchCallback trueBranch, BranchCallback falseBranch)
          Perform a greater-than-or-equal test and branch, given the provided true and false branches.
 void performLogicalAnd(BranchCallback longBranch)
          Perform a logical short-circuited Ruby "and" operation, using Ruby notions of true and false.
 void performLogicalOr(BranchCallback longBranch)
          Perform a logical short-circuited Ruby "or" operation, using Ruby notions of true and false.
 void performLTBranch(BranchCallback trueBranch, BranchCallback falseBranch)
          Perform a greater-than test and branch, given the provided true and false branches.
 void performReturn()
          Return the current value on the top of the stack, taking into consideration surrounding blocks.
 void pollThreadEvents()
           
 void processRequiredArgs(Arity arity, int totalArgs)
           
 void retrieveBackRef()
          Retrieve the special "back ref" variable $~ from the outermost local scope.
 void retrieveClassVariable(java.lang.String name)
           
 void retrieveConstant(java.lang.String name)
          Retrieve the constant with the specified name available at the current point in the program's execution.
 void retrieveGlobalVariable(java.lang.String name)
          Retrieve the global variable with the specified name to the top of the stack.
 void retrieveInstanceVariable(java.lang.String name)
          Retrieve the instance variable with the given name, based on the current "self".
 void retrieveLastLine()
          Retrieve the special "last line" variable $_ from the outermost local scope.
 void retrieveLocalVariable(int index)
          Retrieve the local variable at the specified index to the top of the stack, using whatever local variable store is appropriate.
 void retrieveLocalVariable(int index, int depth)
          Retrieve the local variable as the specified index and lexical scoping depth to the top of the stack, using whatever local variable store is appropriate.
 void retrieveSelf()
          Retrieve the current "self" and put a reference on top of the stack.
 void retrieveSelfClass()
          Retrieve the current "self" object's metaclass and put a reference on top of the stack
 void singlifySplattedValue()
          Given a splatted value, extract a single value.
 void splatCurrentValue()
          Convert the current value into a "splatted value" suitable for passing as method arguments or disassembling into multiple variables.
 void startScript()
          Begin compilation for a script, preparing all necessary context and code to support this script's compiled representation.
 void swapValues()
          Swap the top and second values on the stack.
 void yield(boolean hasArgs)
          Invoke the block passed into this method, or throw an error if no block is present.
 

Method Detail

startScript

public void startScript()
Begin compilation for a script, preparing all necessary context and code to support this script's compiled representation.


endScript

public void endScript()
End compilation for the current script, closing all context and structures used for the compilation.


beginMethod

public java.lang.Object beginMethod(java.lang.String friendlyName,
                                    ClosureCallback argsHandler)
Begin compilation for a method that has the specified number of local variables. The returned value is a token that can be used to end the method later.

Parameters:
friendlyName - The outward user-readable name of the method. A unique name will be generated based on this.
Returns:
An Object that represents the method within this compiler. Used in calls to endMethod once compilation for this method is completed.

endMethod

public void endMethod(java.lang.Object token)
End compilation for the method associated with the specified token. This should close out all structures created for compilation of the method.

Parameters:
token - A token identifying the method to be terminated.

consumeCurrentValue

public void consumeCurrentValue()
As code executes, values are assumed to be "generated", often by being pushed on to some execution stack. Generally, these values are consumed by other methods on the context, but occasionally a value must be "thrown out". This method provides a way to discard the previous value generated by some other call(s).


duplicateCurrentValue

public void duplicateCurrentValue()
Push a copy the topmost value on the stack.


swapValues

public void swapValues()
Swap the top and second values on the stack.


lineNumber

public void lineNumber(ISourcePosition position)
This method provides a way to specify a line number for the current piece of code being compiled. The compiler may use this information to create debugging information in a bytecode-format-dependent way.

Parameters:
position - The ISourcePosition information to use.

invokeDynamic

public void invokeDynamic(java.lang.String name,
                          boolean hasReceiver,
                          boolean hasArgs,
                          CallType callType,
                          ClosureCallback closureArg,
                          boolean attrAssign)
Invoke the named method as a "function", i.e. as a method on the current "self" object, using the specified argument count. It is expected that previous calls to the compiler has prepared the exact number of argument values necessary for this call. Those values will be consumed, and the result of the call will be generated.


invokeAttrAssign

public void invokeAttrAssign(java.lang.String name)
Attr assign calls have slightly different semantics that normal calls, so this method handles those additional semantics.


yield

public void yield(boolean hasArgs)
Invoke the block passed into this method, or throw an error if no block is present. If arguments have been prepared for the block, specify true. Otherwise the default empty args will be used.


assignLocalVariable

public void assignLocalVariable(int index)
Assigns the value on top of the stack to a local variable at the specified index, consuming that value in the process. This assumes a lexical scoping depth of 0.

Parameters:
index - The index of the local variable to which to assign the value.

assignLastLine

public void assignLastLine()
Assigns the special "last line" variable $_ in the outermost local scope.


assignLocalVariableBlockArg

public void assignLocalVariableBlockArg(int argIndex,
                                        int varIndex)
Assigns the value from incoming block args to a local variable at the specified index, consuming that value in the process. This assumes a lexical scoping depth of 0.


retrieveLocalVariable

public void retrieveLocalVariable(int index)
Retrieve the local variable at the specified index to the top of the stack, using whatever local variable store is appropriate. This assumes the local variable in question should be present at the current lexical scoping depth (0).

Parameters:
index - The index of the local variable to retrieve

retrieveLastLine

public void retrieveLastLine()
Retrieve the special "last line" variable $_ from the outermost local scope.


retrieveBackRef

public void retrieveBackRef()
Retrieve the special "back ref" variable $~ from the outermost local scope.


assignLocalVariable

public void assignLocalVariable(int index,
                                int depth)
Assign the value on top of the stack to a local variable at the specified index and lexical scoping depth (0 = current scope), consuming that value in the process.

Parameters:
index - The index in which to store the local variable
depth - The lexical scoping depth in which to store the variable

assignLocalVariableBlockArg

public void assignLocalVariableBlockArg(int argIndex,
                                        int varIndex,
                                        int depth)
Assign the value from incoming block args to a local variable at the specified index and lexical scoping depth (0 = current scope), consuming that value in the process.

Parameters:
depth - The lexical scoping depth in which to store the variable

retrieveLocalVariable

public void retrieveLocalVariable(int index,
                                  int depth)
Retrieve the local variable as the specified index and lexical scoping depth to the top of the stack, using whatever local variable store is appropriate.

Parameters:
index - The index of the local variable to retrieve
depth - The lexical scoping depth from which to retrieve the variable

assignOptionalArgs

public void assignOptionalArgs(java.lang.Object object,
                               int expectedArgsCount,
                               int size,
                               ArrayCallback optEval)

retrieveSelf

public void retrieveSelf()
Retrieve the current "self" and put a reference on top of the stack.


retrieveSelfClass

public void retrieveSelfClass()
Retrieve the current "self" object's metaclass and put a reference on top of the stack


retrieveClassVariable

public void retrieveClassVariable(java.lang.String name)

assignClassVariable

public void assignClassVariable(java.lang.String name)

createNewFixnum

public void createNewFixnum(long value)
Generate a new "Fixnum" value.


createNewFloat

public void createNewFloat(double value)
Generate a new "Float" value.


createNewBignum

public void createNewBignum(java.math.BigInteger value)
Generate a new "Bignum" value.


createNewString

public void createNewString(ByteList value)
Generate a new "String" value.


createNewString

public void createNewString(ArrayCallback callback,
                            int count)
Generate a new dynamic "String" value.


createNewSymbol

public void createNewSymbol(java.lang.String name)
Generate a new "Symbol" value (or fetch the existing one).


createObjectArray

public void createObjectArray(java.lang.Object[] elementArray,
                              ArrayCallback callback)

createObjectArray

public void createObjectArray(int elementCount)
Combine the top
elementCount
elements into a single element, generally an array or similar construct. The specified number of elements are consumed and an aggregate element remains.

Parameters:
elementCount - The number of elements to consume

createNewArray

public void createNewArray()
Given an aggregated set of objects (likely created through a call to createObjectArray) create a Ruby array object.


createEmptyArray

public void createEmptyArray()
Create an empty Ruby array


createEmptyHash

public void createEmptyHash()
Create an empty Ruby Hash object and put a reference on top of the stack.


createNewHash

public void createNewHash(java.lang.Object elements,
                          ArrayCallback callback,
                          int keyCount)
Create a new hash by calling back to the specified ArrayCallback. It is expected that the keyCount will be the actual count of key/value pairs, and the caller will handle passing an appropriate elements collection in and dealing with the sequential indices passed to the callback.

Parameters:
elements - An object holding the elements from which to create the Hash.
callback - An ArrayCallback implementation to which the elements array and iteration counts are passed in sequence.
keyCount - the total count of key-value pairs to be constructed from the elements collection.

createNewRange

public void createNewRange(boolean isExclusive)
Create a new range. It is expected that the stack will contain the end and begin values for the range as its topmost and second topmost elements.

Parameters:
isExclusive - Whether the range is exclusive or not (inclusive)

performBooleanBranch

public void performBooleanBranch(BranchCallback trueBranch,
                                 BranchCallback falseBranch)
Perform a boolean branch operation based on the Ruby "true" value of the top value on the stack. If Ruby "true", invoke the true branch callback. Otherwise, invoke the false branch callback.

Parameters:
trueBranch - The callback for generating code for the "true" condition
falseBranch - The callback for generating code for the "false" condition

performLogicalAnd

public void performLogicalAnd(BranchCallback longBranch)
Perform a logical short-circuited Ruby "and" operation, using Ruby notions of true and false. If the value on top of the stack is false, it remains and the branch is not executed. If it is true, the top of the stack is replaced with the result of the branch.

Parameters:
longBranch - The branch to execute if the "and" operation does not short-circuit.

performLogicalOr

public void performLogicalOr(BranchCallback longBranch)
Perform a logical short-circuited Ruby "or" operation, using Ruby notions of true and false. If the value on top of the stack is true, it remains and the branch is not executed. If it is false, the top of the stack is replaced with the result of the branch.

Parameters:
longBranch - The branch to execute if the "or" operation does not short-circuit.

performBooleanLoop

public void performBooleanLoop(BranchCallback condition,
                               BranchCallback body,
                               boolean checkFirst)
Perform a boolean loop using the given condition-calculating branch and body branch. For while loops, pass true for checkFirst. For statement-modifier while loops, pass false. For unless loops, reverse the result of the condition after calculating it.

Parameters:
condition - The code to execute for calculating the loop condition. A Ruby true result will cause the body to be executed again.
body - The body to executed for the loop.
checkFirst - whether to check the condition the first time through or not.

performReturn

public void performReturn()
Return the current value on the top of the stack, taking into consideration surrounding blocks.


createNewClosure

public void createNewClosure(StaticScope scope,
                             int arity,
                             ClosureCallback body,
                             ClosureCallback args)
Create a new closure (block) using the given lexical scope information, call arity, and body generated by the body callback. The closure will capture containing scopes and related information.

Parameters:
scope - The static scoping information
arity - The arity of the block's argument list
body - The callback which will generate the closure's body

defineNewMethod

public void defineNewMethod(java.lang.String name,
                            StaticScope scope,
                            ClosureCallback body,
                            ClosureCallback args)
Define a new method with the given name, arity, local variable count, and body callback. This will create a new compiled method and bind it to the given name at this point in the program's execution.

Parameters:
name - The name to which to bind the resulting method.
body - The callback which will generate the method's body.

processRequiredArgs

public void processRequiredArgs(Arity arity,
                                int totalArgs)

defineAlias

public void defineAlias(java.lang.String newName,
                        java.lang.String oldName)
Define an alias for a new name to an existing oldName'd method.

Parameters:
newName - The new alias to create
oldName - The name of the existing method or alias

assignConstantInCurrent

public void assignConstantInCurrent(java.lang.String name)

assignConstantInModule

public void assignConstantInModule(java.lang.String name)

assignConstantInObject

public void assignConstantInObject(java.lang.String name)

retrieveConstant

public void retrieveConstant(java.lang.String name)
Retrieve the constant with the specified name available at the current point in the program's execution.

Parameters:
name - The name of the constant

loadFalse

public void loadFalse()
Load a Ruby "false" value on top of the stack.


loadTrue

public void loadTrue()
Load a Ruby "true" value on top of the stack.


loadNil

public void loadNil()
Load a Ruby "nil" value on top of the stack.


loadSymbol

public void loadSymbol(java.lang.String symbol)
Load the given string as a symbol on to the top of the stack.

Parameters:
symbol - The symbol to load.

loadObject

public void loadObject()
Load the Object class


retrieveInstanceVariable

public void retrieveInstanceVariable(java.lang.String name)
Retrieve the instance variable with the given name, based on the current "self".

Parameters:
name - The name of the instance variable to retrieve.

assignInstanceVariable

public void assignInstanceVariable(java.lang.String name)
Assign the value on top of the stack to the instance variable with the specified name on the current "self". The value is consumed.

Parameters:
name - The name of the value to assign.

assignInstanceVariableBlockArg

public void assignInstanceVariableBlockArg(int index,
                                           java.lang.String name)
Assign the value from incoming block args instance variable with the specified name on the current "self".

Parameters:
index - The index in the incoming arguments from which to get the ivar value
name - The name of the ivar to assign.

assignGlobalVariable

public void assignGlobalVariable(java.lang.String name)
Assign the top of the stack to the global variable with the specified name.

Parameters:
name - The name of the global variable.

assignGlobalVariableBlockArg

public void assignGlobalVariableBlockArg(int index,
                                         java.lang.String name)
Assign the value from incoming block args to the global variable with the specified name.

Parameters:
index - The index in the incoming arguments from which to get the gvar value
name - The name of the global variable.

retrieveGlobalVariable

public void retrieveGlobalVariable(java.lang.String name)
Retrieve the global variable with the specified name to the top of the stack.

Parameters:
name - The name of the global variable.

negateCurrentValue

public void negateCurrentValue()
Perform a logical Ruby "not" operation on the value on top of the stack, leaving the negated result.


splatCurrentValue

public void splatCurrentValue()
Convert the current value into a "splatted value" suitable for passing as method arguments or disassembling into multiple variables.


singlifySplattedValue

public void singlifySplattedValue()
Given a splatted value, extract a single value. If no splat or length is zero, use nil


forEachInValueArray

public void forEachInValueArray(int count,
                                int start,
                                java.lang.Object source,
                                ArrayCallback callback)
Given an IRubyObject[] on the stack (or otherwise available as the present object) call back to the provided ArrayCallback 'callback' for 'count' elements, starting with 'start'.


ensureRubyArray

public void ensureRubyArray()
Ensures that the present value is an IRubyObject[] by wrapping it with one if it is not.


loadInteger

public void loadInteger(int value)
Load an integer value suitable for numeric comparisons


performGEBranch

public void performGEBranch(BranchCallback trueBranch,
                            BranchCallback falseBranch)
Perform a greater-than-or-equal test and branch, given the provided true and false branches.


performGTBranch

public void performGTBranch(BranchCallback trueBranch,
                            BranchCallback falseBranch)
Perform a greater-than test and branch, given the provided true and false branches.


performLEBranch

public void performLEBranch(BranchCallback trueBranch,
                            BranchCallback falseBranch)
Perform a greater-than-or-equal test and branch, given the provided true and false branches.


performLTBranch

public void performLTBranch(BranchCallback trueBranch,
                            BranchCallback falseBranch)
Perform a greater-than test and branch, given the provided true and false branches.


loadRubyArraySize

public void loadRubyArraySize()

issueBreakEvent

public void issueBreakEvent()

asString

public void asString()

nthRef

public void nthRef(int match)

match

public void match()

match2

public void match2()

match3

public void match3()

createNewRegexp

public void createNewRegexp(ByteList value,
                            int options,
                            java.lang.String lang)

defineClass

public void defineClass(java.lang.String name,
                        StaticScope staticScope,
                        ClosureCallback superCallback,
                        ClosureCallback pathCallback,
                        ClosureCallback bodyCallback)

defineModule

public void defineModule(java.lang.String name,
                         StaticScope staticScope,
                         ClosureCallback pathCallback,
                         ClosureCallback bodyCallback)

pollThreadEvents

public void pollThreadEvents()


Copyright © 2002-2007 JRuby Team. All Rights Reserved.