001 
002 /*
003  *  JScripter Standard 1.0 - To Script In Java
004  *  Copyright (C) 2008-2011  J.J.Liu<jianjunliu@126.com> <http://www.jscripter.org>
005  *  
006  *  This program is free software: you can redistribute it and/or modify
007  *  it under the terms of the GNU Affero General Public License as published by
008  *  the Free Software Foundation, either version 3 of the License, or
009  *  (at your option) any later version.
010  *  
011  *  This program is distributed in the hope that it will be useful,
012  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
013  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014  *  GNU Affero General Public License for more details.
015  *  
016  *  You should have received a copy of the GNU Affero General Public License
017  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
018  */
019 
020 package js;
021 
022 /**
023  * <p>An <b>opaque</b> class resembling JavaScript array literals (also known as 
024  * array literals) and variable arguments.</p>
025  * <p>This class can only be used to construct a variable-length argument at the last 
026  * parameter position of the invocation on a method of <b>opaque</b> interfaces or classes. 
027  * Otherwise, JS re-compilers shall report errors.</P>
028  * <p>JavaScript defines a literal syntax for creating and initializing arrays. An 
029  * array literal (or array initializer) is a comma-separated list of values contained 
030  * within square brackets. The values within the brackets are assigned sequentially 
031  * to array indexes starting with zero.</p>
032  * <p>Like object literals, array literals can be nested.</p>
033  * <p>Also, as with object literals, the elements in array literals can be arbitrary 
034  * expressions and need not be restricted to constants.</p>
035  * <p>Undefined elements can be included in an array literal by simply omitting a 
036  * value between commas.</p>
037  *
038  * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
039  * @see Js#array()
040  * @see Js#array(boolean[])
041  * @see Js#array(byte[])
042  * @see Js#array(char[])
043  * @see Js#array(short[])
044  * @see Js#array(int[])
045  * @see Js#array(long[])
046  * @see Js#array(float[])
047  * @see Js#array(double[])
048  * @see Js#array(Object[])
049  * @see js.core.JsArray#JsArray()
050  * @see js.core.JsArray#JsArray(js.core.JsObject)
051  * @see js.core.JsArray#JsArray(boolean[])
052  * @see js.core.JsArray#JsArray(byte[])
053  * @see js.core.JsArray#JsArray(char[])
054  * @see js.core.JsArray#JsArray(short[])
055  * @see js.core.JsArray#JsArray(int[])
056  * @see js.core.JsArray#JsArray(long[])
057  * @see js.core.JsArray#JsArray(double[])
058  * @see js.core.JsArray#JsArray(float[])
059  * @see js.core.JsArray#JsArray(Object[])
060  * @see js.core.JsGlobal.Array#create(Object)
061  * @see jsx.core.ArrayLikes
062  * 
063  * @javascript <b>Opaque</b> types can be resolved but no class objects for them can be 
064  * generated into the target codes. Re-compilers must exit with error on the operations of 
065  * accessing that kind of class objects.
066  * Re-compilers should convert Java expressions like:
067  * <pre>new Vars().add(v1).add(v2).add(null).add(v3).var()</pre>
068  * into JavaScript expressions as:
069  * <pre>[v1,v2,,v3]</pre>
070  * and convert Java invocations on the methods of <tt>opaque</tt> interfaces or classes 
071  * like:
072  * <pre>a.concat(new Vars().add(arg1).add(arg2).add(arg3))</pre>
073  * into JavaScript expressions as:
074  * <pre>a.concat(arg1, arg2, arg3)</pre>
075  * and report error if <tt>a</tt> is not an instance of an <tt>opaque</tt> interface and 
076  * class.
077  */
078 
079 public final class Vars<T> extends Var<ArrayLike<T>>
080 {
081     private final ArrayLike<T> a;
082 
083     /**
084      * <p>Creates an <tt>Vars</tt> list.</p>
085      * @since 1.0
086      * @javascript Re-compilers must create a re-compile time <tt>Vars</tt> list without 
087      * generating any JavaScript statements or expressions for this constructor.
088      */
089     public Vars() {
090         a = Js.array();
091     }
092 
093     /**
094      * <p>Converts the current <tt>Vars</tt> list instance to an array.</p>
095      * @return The array represented by the current <tt>Vars</tt> list itself.
096      * @since 1.0
097      * @javascript Re-compilers must replace the instance invocation of this method with the 
098      * JavaScript array literal represented by the current <tt>Vars</tt> list instance 
099      * they have kept.
100      */
101     @Override
102     public final ArrayLike<T> var() {
103         return a;
104     }
105 
106     /**
107      * <p>Appends a value to the current <tt>Vars</tt> list instance.</p>
108      * @param arg The value to be append to the current <tt>Vars</tt> list instance.
109      * @return The current <tt>Vars</tt> list instance itself.
110      * @since 1.0
111      * @javascript Re-compilers must append <tt>arg</tt> to the current re-compile time 
112      * <tt>Vars</tt> list they have kept without generating any JavaScript statements 
113      * or expressions for the instance invocation of this method.
114      */
115     public final Vars<T> add(T arg) {
116         a.push(arg);
117         return this;
118     }
119 
120     /**
121      * <p>Appends all values of <tt>other</tt> <tt>Vars</tt> list to the current 
122      * <tt>Vars</tt> list instance.</p>
123      * @param other Any other <tt>Vars</tt> list.
124      * @return The current <tt>Vars</tt> list instance itself.
125      * @since 1.0
126      * @javascript Re-compilers must append all values of <tt>other</tt> <tt>Vars</tt> 
127      * list to the current re-compile time <tt>Vars</tt> list they have kept without 
128      * generating any JavaScript statements or expressions for the instance invocation of 
129      * this method.
130      */
131     public final Vars<T> addAll(Vars<? extends T> other) {
132         a.push(other);
133         return this;
134     }
135 }