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 branchIfModule(BranchCallback moduleCallback, BranchCallback notModuleCallback)
           
 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 retrieveConstantFromModule(java.lang.String name)
          Retreive a named constant from the RubyModule/RubyClass that's just been pushed.
 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

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


endScript

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


beginMethod

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.
arity - The arity of the method's argument list
localVarCount - The number of local variables that will be used by the method.
Returns:
An Object that represents the method within this compiler. Used in calls to endMethod once compilation for this method is completed.

endMethod

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

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

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


swapValues

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


lineNumber

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

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

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


yield

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

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

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


assignLocalVariableBlockArg

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.

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

retrieveLocalVariable

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

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


retrieveBackRef

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


assignLocalVariable

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

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:
index - The index in which to store the local variable
depth - The lexical scoping depth in which to store the variable

retrieveLocalVariable

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

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

retrieveSelf

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


retrieveSelfClass

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


retrieveClassVariable

void retrieveClassVariable(java.lang.String name)

assignClassVariable

void assignClassVariable(java.lang.String name)

createNewFixnum

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


createNewFloat

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


createNewBignum

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


createNewString

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


createNewString

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


createNewSymbol

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


createObjectArray

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

createObjectArray

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

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


createEmptyArray

void createEmptyArray()
Create an empty Ruby array


createEmptyHash

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


createNewHash

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

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

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

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

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

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

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


createNewClosure

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

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.
arity - The arity of the method's argument list
localVarCount - The number of local variables within the method
body - The callback which will generate the method's body.

processRequiredArgs

void processRequiredArgs(Arity arity,
                         int totalArgs)

defineAlias

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

void assignConstantInCurrent(java.lang.String name)

assignConstantInModule

void assignConstantInModule(java.lang.String name)

assignConstantInObject

void assignConstantInObject(java.lang.String name)

retrieveConstant

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

retrieveConstantFromModule

void retrieveConstantFromModule(java.lang.String name)
Retreive a named constant from the RubyModule/RubyClass that's just been pushed.

Parameters:
name - The name of the constant

loadFalse

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


loadTrue

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


loadNil

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


loadSymbol

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

void loadObject()
Load the Object class


retrieveInstanceVariable

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

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

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

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

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

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

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


splatCurrentValue

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


singlifySplattedValue

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


forEachInValueArray

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

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


loadInteger

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


performGEBranch

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


performGTBranch

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


performLEBranch

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


performLTBranch

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


loadRubyArraySize

void loadRubyArraySize()

issueBreakEvent

void issueBreakEvent()

asString

void asString()

nthRef

void nthRef(int match)

match

void match()

match2

void match2()

match3

void match3()

createNewRegexp

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

defineClass

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

defineModule

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

pollThreadEvents

void pollThreadEvents()

branchIfModule

void branchIfModule(BranchCallback moduleCallback,
                    BranchCallback notModuleCallback)


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