Compiler


1   /***** BEGIN LICENSE BLOCK *****
2    * Version: CPL 1.0/GPL 2.0/LGPL 2.1
3    *
4    * The contents of this file are subject to the Common Public
5    * License Version 1.0 (the "License"); you may not use this file
6    * except in compliance with the License. You may obtain a copy of
7    * the License at http://www.eclipse.org/legal/cpl-v10.html
8    *
9    * Software distributed under the License is distributed on an "AS
10   * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
11   * implied. See the License for the specific language governing
12   * rights and limitations under the License.
13   *
14   * Copyright (C) 2006 Charles O Nutter <headius@headius.com>
15   *  
16   * Alternatively, the contents of this file may be used under the terms of
17   * either of the GNU General Public License Version 2 or later (the "GPL"),
18   * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
19   * in which case the provisions of the GPL or the LGPL are applicable instead
20   * of those above. If you wish to allow use of your version of this file only
21   * under the terms of either the GPL or the LGPL, and not to allow others to
22   * use your version of this file under the terms of the CPL, indicate your
23   * decision by deleting the provisions above and replace them with the notice
24   * and other provisions required by the GPL or the LGPL. If you do not delete
25   * the provisions above, a recipient may use your version of this file under
26   * the terms of any one of the CPL, the GPL or the LGPL.
27   ***** END LICENSE BLOCK *****/
28  
29  package org.jruby.compiler;
30  
31  import org.jruby.lexer.yacc.ISourcePosition;
32  import org.jruby.parser.StaticScope;
33  import org.jruby.util.ByteList;
34  
35  /**
36   * Compiler represents the current state of a compiler and all appropriate
37   * transitions and modifications that can be made within it. The methods here begin
38   * and end a class for a given compile run, begin and end methods for the script being
39   * compiled, set line number information, and generate code for all the basic
40   * operations necessary for a script to run.
41   * 
42   * The intent of this interface is to provide a library-neutral set of functions for
43   * compiling a given script using any backend or any output format.
44   */
45  public interface Compiler {
46      /**
47       * Begin compilation for a script, preparing all necessary context and code
48       * to support this script's compiled representation.
49       */
50      public void startScript();
51      
52      /**
53       * End compilation for the current script, closing all context and structures
54       * used for the compilation.
55       */
56      public void endScript();
57      
58      /**
59       * Begin compilation for a method that has the specified number of local variables.
60       * The returned value is a token that can be used to end the method later.
61       * 
62       * @param localVarCount The number of local variables that will be used by the method.
63       * @return An Object that represents the method within this compiler. Used in calls to
64       * endMethod once compilation for this method is completed.
65       */
66      public Object   beginMethod(String   friendlyName, int arity, int localVarCount);
67      
68      /**
69       * End compilation for the method associated with the specified token. This should
70       * close out all structures created for compilation of the method.
71       */
72      public void endMethod(Object   token);
73      
74      /**
75       * As code executes, values are assumed to be "generated", often by being pushed
76       * on to some execution stack. Generally, these values are consumed by other
77       * methods on the context, but occasionally a value must be "thrown out". This method
78       * provides a way to discard the previous value generated by some other call(s).
79       */
80      public void consumeCurrentValue();
81      
82      /**
83       * This method provides a way to specify a line number for the current piece of code
84       * being compiled. The compiler may use this information to create debugging
85       * information in a bytecode-format-dependent way.
86       */
87      public void lineNumber(ISourcePosition node);
88      
89      /**
90       * Invoke the named method as a "function", i.e. as a method on the current "self"
91       * object, using the specified argument count. It is expected that previous calls
92       * to the compiler has prepared the exact number of argument values necessary for this
93       * call. Those values will be consumed, and the result of the call will be generated.
94       */
95      public void invokeDynamic(String   name, boolean hasReceiver, boolean hasArgs, ClosureCallback closureArg);
96      
97      /**
98       * Invoke the block passed into this method, or throw an error if no block is present.
99       * If arguments have been prepared for the block, specify true. Otherwise the default
100      * empty args will be used.
101      */
102     public void yield(boolean hasArgs);
103     
104     /**
105      * Assigns the previous value to a local variable at the specified index, consuming
106      * that value in the process.
107      * 
108      * @param index The index of the local variable to which to assign the value.
109      */
110     public void assignLocalVariable(int index);
111     
112     public void retrieveLocalVariable(int index);
113     
114     public void assignLocalVariable(int index, int depth);
115     
116     public void retrieveLocalVariable(int index, int depth);
117     
118     public void retrieveSelf();
119     
120     /**
121      * Generate a new "Fixnum" value.
122      */
123     public void createNewFixnum(long value);
124 
125     /**
126      * Generate a new "Bignum" value.
127      */
128     public void createNewBignum(java.math.BigInteger   value);
129     
130     /**
131      * Generate a new "String" value.
132      */
133     public void createNewString(ByteList value);
134 
135     /**
136      * Generate a new "Symbol" value (or fetch the existing one).
137      */
138     public void createNewSymbol(String   name);
139     
140     /**
141      * Combine the top <pre>elementCount</pre> elements into a single element, generally
142      * an array or similar construct. The specified number of elements are consumed and
143      * an aggregate element remains.
144      * 
145      * @param elementCount The number of elements to consume
146      */
147     public void createObjectArray(Object  [] elementArray, ArrayCallback callback);
148 
149     /**
150      * Given an aggregated set of objects (likely created through a call to createObjectArray)
151      * create a Ruby array object.
152      */
153     public void createNewArray();
154 
155     /**
156      * Create an empty Ruby array
157      */
158     public void createEmptyArray();
159     
160     public void performBooleanBranch(BranchCallback trueBranch, BranchCallback falseBranch);
161     
162     public void performLogicalAnd(BranchCallback longBranch);
163     
164     public void performLogicalOr(BranchCallback longBranch);
165     
166     public void performBooleanLoop(BranchCallback condition, BranchCallback body, boolean checkFirst);
167     
168     public void createNewClosure(StaticScope scope, int arity, ClosureCallback body);
169     
170     public void defineNewMethod(String   name, int arity, int localVarCount, ClosureCallback body);
171     
172     public void defineAlias(String   newName, String   oldName);
173     
174     public void retrieveConstant(String   name);
175     
176     public void loadFalse();
177     
178     public void loadTrue();
179     
180     public void loadNil();
181     
182     public void retrieveInstanceVariable(String   name);
183     
184     public void assignInstanceVariable(String   name);
185     
186     public void assignGlobalVariable(String   name);
187     
188     public void retrieveGlobalVariable(String   name);
189     
190     public void negateCurrentValue();
191     
192     /**
193      * Convert the current value into a "splatted value" suitable for passing as
194      * method arguments or disassembling into multiple variables.
195      */
196     public void splatCurrentValue();
197     
198     /**
199      * Given a splatted value, extract a single value. If no splat or length is
200      * zero, use nil
201      */
202     public void singlifySplattedValue();
203     
204     /**
205      * Given an IRubyObject[] on the stack (or otherwise available as the present object)
206      * call back to the provided ArrayCallback 'callback' for 'count' elements, starting with 'start'.
207      */
208     public void forEachInValueArray(int count, int start, Object   source, ArrayCallback callback);
209     
210     /**
211      * Ensures that the present value is an IRubyObject[] by wrapping it with one if it is not.
212      */
213     public void ensureRubyArray();
214     
215     /**
216      * Load an integer value suitable for numeric comparisons
217      */
218     public void loadInteger(int value);
219     
220     /**
221      * Perform a greater-than-or-equal test and branch, given the provided true and false branches.
222      */
223     public void performGEBranch(BranchCallback trueBranch, BranchCallback falseBranch);
224     
225     /**
226      * Perform a greater-than test and branch, given the provided true and false branches.
227      */
228     public void performGTBranch(BranchCallback trueBranch, BranchCallback falseBranch);
229     
230     /**
231      * Perform a greater-than-or-equal test and branch, given the provided true and false branches.
232      */
233     public void performLEBranch(BranchCallback trueBranch, BranchCallback falseBranch);
234     
235     /**
236      * Perform a greater-than test and branch, given the provided true and false branches.
237      */
238     public void performLTBranch(BranchCallback trueBranch, BranchCallback falseBranch);
239     
240     public void loadRubyArraySize();
241 }
242
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags