jsweet.util.Lang Maven / Gradle / Ivy
/*
* JSweet - http://www.jsweet.org
* Copyright (C) 2015 CINCHEO SAS
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package jsweet.util;
import java.util.Map;
import java.util.function.BiConsumer;
import java.util.function.BiFunction;
import java.util.function.Consumer;
import java.util.function.Function;
import java.util.function.Supplier;
import def.js.Promise;
import jsweet.util.function.Consumer4;
import jsweet.util.function.Consumer5;
import jsweet.util.function.Consumer6;
import jsweet.util.function.Function4;
import jsweet.util.function.Function5;
import jsweet.util.function.Function6;
import jsweet.util.function.TriConsumer;
import jsweet.util.function.TriFunction;
import jsweet.util.union.Union;
import jsweet.util.union.Union3;
import jsweet.util.union.Union4;
/**
* A set of helper methods for manipulating JavaScript core lang features and
* relate them to the Java lang.
*
*
* Be aware that these functions have no corresponding implementation. They are
* used mainly for typing and syntax purpose. By convention, most functions
* starting with $ are syntax macros to support JavaScript syntactic constructs.
* Most other functions are cast functions to switch from Java to JavaScript
* objects. The later are erased during the generation process or are translated
* to TypeScript casts (in any case they have no runtime counterparts).
*
*
* To work with JSweet, programmers may import these helpers most of the time,
* as well as JavaScript's {@link def.js.Globals} (and DOM's
* {@link def.dom.Globals}).
*
* @author Renaud Pawlak
* @see def.js.Globals
* @see def.dom.Globals
*/
public final class Lang {
private static final ThreadLocal> EXPORTED_VARS = new ThreadLocal<>();
private Lang() {
}
/**
* An accessor to the module id, only when using modules.
*/
public static final class module {
public final static String id = null;
}
/**
* Casts a JavaScript array object to a native Java array.
*
* @param array
* a JavaScript array
* @return a Java array
*/
native public static T[] array(def.js.Array array);
/**
* Casts a native Java array to a JavaScript array object.
*
* @param array
* a Java array
* @return a JavaScript array
*/
native public static def.js.Array array(T[] array);
/**
* Casts a native Java array of primitive booleans to a JavaScript array
* object.
*
* @param array
* a Java array
* @return a JavaScript array
*/
native public static def.js.Array array(boolean[] array);
/**
* Casts a native Java array of primitive ints to a JavaScript array object.
*
* @param array
* a Java array
* @return a JavaScript array
*/
native public static def.js.Array array(int[] array);
/**
* Casts a native Java array of primitive doubles to a JavaScript array
* object.
*
* @param array
* a Java array
* @return a JavaScript array
*/
native public static def.js.Array array(double[] array);
/**
* Casts a native Java array of primitive shorts to a JavaScript array
* object.
*
* @param array
* a Java array
* @return a JavaScript array
*/
native public static def.js.Array array(short[] array);
/**
* Casts a native Java array of primitive bytes to a JavaScript array
* object.
*
* @param array
* a Java array
* @return a JavaScript array
*/
native public static def.js.Array array(byte[] array);
/**
* Casts a native Java array of primitive longs to a JavaScript array
* object.
*
* @param array
* a Java array
* @return a JavaScript array
*/
native public static def.js.Array array(long[] array);
/**
* Casts a native Java array of primitive floats to a JavaScript array
* object.
*
* @param array
* a Java array
* @return a JavaScript array
*/
native public static def.js.Array array(float[] array);
/**
* Forces JSweet to create a plain JavaScript function rather than an
* "arrow" function.
*
*
* Hence, function((a) -> { return a * a; }) transpiles to
* (a) => { return a * a; }. But
* $noarrow(function((a) -> { return a * a; })) transpiles to
* function(a) { return a * a; }
*/
native public static def.js.Function $noarrow(def.js.Function function);
/**
* Casts a functional interface to a JavaScript function object.
*
*
* Note that this casts allows for a reflective access to the function as a
* plain object, but it looses the actual function type. Various APIs take
* function objects as arguments, and this function can be useful in such
* circumstances.
*
* @see jsweet.util.function
*/
native public static def.js.Function function(Runnable function);
/**
* Casts a type to a JavaScript function object.
*
*
* Indeed, type references are functions in javascript.
*
* @see jsweet.util.function
*/
native public static def.js.Function function(Class type);
/**
* Casts a functional interface to a JavaScript function object.
*
*
* Note that this casts allows for a reflective access to the function as a
* plain object, but it looses the actual function type. Various APIs take
* function objects as arguments, and this function can be useful in such
* circumstances.
*
* @see jsweet.util.function
*/
native public static def.js.Function function(Consumer function);
/**
* Casts a functional interface to a JavaScript function object.
*
*
* Note that this casts allows for a reflective access to the function as a
* plain object, but it looses the actual function type. Various APIs take
* function objects as arguments, and this function can be useful in such
* circumstances.
*
* @see jsweet.util.function
*/
native public static def.js.Function function(Supplier function);
/**
* Casts a functional interface to a JavaScript function object.
*
*
* Note that this casts allows for a reflective access to the function as a
* plain object, but it looses the actual function type. Various APIs take
* function objects as arguments, and this function can be useful in such
* circumstances.
*
* @see jsweet.util.function
*/
native public static def.js.Function function(BiConsumer function);
/**
* Casts a functional interface to a JavaScript function object.
*
*
* Note that this casts allows for a reflective access to the function as a
* plain object, but it looses the actual function type. Various APIs take
* function objects as arguments, and this function can be useful in such
* circumstances.
*
* @see jsweet.util.function
*/
native public static def.js.Function function(TriConsumer function);
/**
* Casts a functional interface to a JavaScript function object.
*
*
* Note that this casts allows for a reflective access to the function as a
* plain object, but it looses the actual function type. Various APIs take
* function objects as arguments, and this function can be useful in such
* circumstances.
*
* @see jsweet.util.function
*/
native public static def.js.Function function(Consumer4 function);
/**
* Casts a functional interface to a JavaScript function object.
*
*
* Note that this casts allows for a reflective access to the function as a
* plain object, but it looses the actual function type. Various APIs take
* function objects as arguments, and this function can be useful in such
* circumstances.
*
* @see jsweet.util.function
*/
native public static def.js.Function function(Consumer5 function);
/**
* Casts a functional interface to a JavaScript function object.
*
*
* Note that this casts allows for a reflective access to the function as a
* plain object, but it looses the actual function type. Various APIs take
* function objects as arguments, and this function can be useful in such
* circumstances.
*
* @see jsweet.util.function
*/
native public static def.js.Function function(Consumer6 function);
/**
* Casts a functional interface to a JavaScript function object.
*
*
* Note that this casts allows for a reflective access to the function as a
* plain object, but it looses the actual function type. Various APIs take
* function objects as arguments, and this function can be useful in such
* circumstances.
*
* @see jsweet.util.function
*/
native public static def.js.Function function(Function function);
/**
* Casts a functional interface to a JavaScript function object.
*
*
* Note that this casts allows for a reflective access to the function as a
* plain object, but it looses the actual function type. Various APIs take
* function objects as arguments, and this function can be useful in such
* circumstances.
*
* @see jsweet.util.function
*/
native public static def.js.Function function(BiFunction function);
/**
* Casts a functional interface to a JavaScript function object.
*
*
* Note that this casts allows for a reflective access to the function as a
* plain object, but it looses the actual function type. Various APIs take
* function objects as arguments, and this function can be useful in such
* circumstances.
*
* @see jsweet.util.function
*/
native public static def.js.Function function(TriFunction function);
/**
* Casts a functional interface to a JavaScript function object.
*
*
* Note that this casts allows for a reflective access to the function as a
* plain object, but it looses the actual function type. Various APIs take
* function objects as arguments, and this function can be useful in such
* circumstances.
*
* @see jsweet.util.function
*/
native public static def.js.Function function(Function4 function);
/**
* Casts a functional interface to a JavaScript function object.
*
*
* Note that this casts allows for a reflective access to the function as a
* plain object, but it looses the actual function type. Various APIs take
* function objects as arguments, and this function can be useful in such
* circumstances.
*
* @see jsweet.util.function
*/
native public static def.js.Function function(Function5 function);
/**
* Casts a functional interface to a JavaScript function object.
*
*
* Note that this casts allows for a reflective access to the function as a
* plain object, but it looses the actual function type. Various APIs take
* function objects as arguments, and this function can be useful in such
* circumstances.
*
* @see jsweet.util.function
*/
native public static def.js.Function function(Function6 function);
/**
* Casts a native Java Boolean to a JavaScript Boolean.
*/
native public static def.js.Boolean bool(Boolean bool);
/**
* Casts back a JavaScript boolean to a Java boolean.
*/
native public static Boolean bool(def.js.Boolean bool);
/**
* Casts a native Java number to a JavaScript Number.
*/
native public static def.js.Number number(Number number);
/**
* Casts back a JavaScript number to a Java integer.
*/
native public static Integer integer(def.js.Number number);
/**
* Casts a JavaScript number to a Java double.
*/
native public static Double number(def.js.Number number);
/**
* Casts a native Java string to a JavaScript string.
*
*
* By default, JSweet API use plain Java strings so that the program can
* easily use string literals. However, when the programmer needs to access
* to runtime string manipulation functions, then need to cast to a
* JavaScript string, which allows the access to the standard Web API.
*/
native public static def.js.String string(String string);
/**
* Casts a native Java char to a JavaScript string.
*/
native public static def.js.String string(char c);
/**
* Casts back a JavaScript string to a Java string.
*
*
* By default, JSweet API use plain Java strings so that the program can
* easily use string literals. However, when the programmer needs to access
* to runtime string manipulation functions, then need to cast to a
* JavaScript string, which allows the access to the standard Web API.
*/
native public static String string(def.js.String string);
/**
* Casts a native Java object to a JavaScript object.
*
*
* By default, JSweet API use plain Java objects. However, when the
* programmer needs to access to the standard Web API, they need to cast
* through this function.
*/
native public static def.js.Object object(Object object);
/**
* This syntax macro should be used to create untyped JavaScript
* objects/maps. It takes a list of key/value pairs, where the keys must be
* string literals and values are objects.
*
*
* For instance, the expression:
*
*
* $map("responsive", true, "defaultSize", "100px")
*
*
*
* Will be transpiled to:
*
*
* {responsive:true, defaultSize:"100px"}
*
*
* @param keyValues
* the key values pairs that initialize the object (keys must be
* string literals)
* @return an untyped object containing the given key/value pairs
*/
native public static def.js.Object $map(Object... keyValues);
/**
* A syntax macro to construct an array with the given elements.
*
*
* For instance, the expression:
*
*
* $array("a", "b", "c")
*
*
*
* Will be transpiled to:
*
*
* ["a", "b", "c"]
*
*
*
* @param elements
* the elements initializing the array
* @return a new array
*/
@SafeVarargs
native public static def.js.Array $array(E... elements);
/**
* Uses the target object as a function and call it. This is not typesafe
* and should be avoided.
*
* @param target
* the functional object
* @param arguments
* the call arguments
* @return the function result
*/
native public static T $apply(Object target, Object... arguments);
/**
* Uses the target object as a constructor and call it. This is not typesafe
* and should be avoided.
*
* @param target
* the constructor object
* @param arguments
* the call arguments
* @return the constructor result
*/
native public static T $new(Object target, Object... arguments);
/**
* This helper casts an object to one of the types in a given union type.
*
*
* The JSweet transpiler will ensure that T is one of T1 and T2. If not, it
* will raise an error.
*
* @param union
* the object typed after a union type
* @return the same object, but typed after one of the types of the union
* type
*/
native public static T union(Union union);
/**
* This helper casts an object to an union type.
*
*
* The JSweet transpiler will ensure that T is one of actual type elements
* of U. If not, it will raise an error.
*
* @param union
* the object typed after one of the types of the union type
* @return the same object, but typed after a union type
*/
native public static , T> U union(T object);
/**
* This helper casts an object to an union type.
*
*
* The JSweet transpiler will ensure that T is one of actual type elements
* of U. If not, it will raise an error.
*
* @param union
* the object typed after one of the types of the union type
* @return the same object, but typed after a union type
*/
native public static Union3 union3(T object);
/**
* This helper casts an object to an union type.
*
*
* The JSweet transpiler will ensure that T is one of actual type elements
* of U. If not, it will raise an error.
*
* @param union
* the object typed after one of the types of the union type
* @return the same object, but typed after a union type
*/
native public static Union4 union4(T object);
/**
* This utility function allows using the typeof JavaScript
* operator.
*
* The expression typeof(o) transpiles to typeof o
* . See the JavaScript documentation for more details.
*/
native public static String typeof(Object o);
/**
* This syntax macro allows using the == or !=
* JavaScript operators. Note that this macro will have no effect on other
* operators than == or !=, but will recursively
* apply to all operators contained in the macro.
*
*
* Since JSweet version 1.1, the Java expression o1!=o2
* transpiles to o1!==o2 to remain close to the Java strict
* inequality (except when diffing with the null literal where
* the == operator is used).
*
*
* Examples:
*
*
* if(a == b) { ... }
* if(a != b) { ... }
* if($loose(a == b)) { ... }
* if($loose(a != b)) { ... }
* if($strict(a == b)) { ... }
* if(a == undefined) { ... }
* if(a != null) { ... }
* if($strict(a != null)) { ... }
* if($loose(a == f(b != a))) { ... }
*
*
* Transpile to:
*
*
* if(a === b) { ... }
* if(a !== b) { ... }
* if(a == b) { ... }
* if(a != b) { ... }
* if(a === b) { ... }
* if(a === undefined) { ... }
* if(a != null) { ... }
* if(a !== null) { ... }
* if(a == f(b != a)) { ... }
*
*
* @param expression
* can be any expression returning a boolean, but only
* (in)equalities operators will be impacted
* @return the expression modified to use loose JavaScript (in)equalities
* operators
* @since 2.0
*/
native public static boolean $loose(boolean expression);
/**
* This syntax macro is the reverse of {@link #$loose(boolean)}, and
* enforces strict (in)equalities when it makes sense.
*
* @param expression
* can be any expression returning a boolean, but only
* (in)equalities operators will be impacted
* @return the expression modified to use strict JavaScript (in)equalities
* operators
*/
native public static boolean $strict(boolean expression);
/**
* Disable type checking on the target object (cast to any). This helper is
* valid in Java.
*/
@SuppressWarnings("unchecked")
public static T any(Object object) {
return (T) object;
}
/**
* This helper function allows the programmer to reflectively set a global
* variable named "_exportedVar_"+name.
*
*
* This function must only be used in specifically cases, typically to
* define results when testing from Java.
*
* @param name
* the base name of the exported global variable, necessarily as
* a string literal
* @param value
* the value to set to the variable
*/
public static void $export(String name, Object value) {
// default Java implementation when running in Java (usually for testing
// purposes)
EXPORTED_VARS.get().put("_exportedVar_" + name, value);
}
/**
* Accesses the current JavaScript this. Within an object
* scope, $this corresponds to a regular object oriented
* this. Outside on an object (i.e. within a global function),
* $this has the JavaScript meaning, representing the current
* function object.
*/
public static final def.js.Object $this = null;
/**
* Defines a template string.
*
*
* For example:
*
*
* console.info($template("Get: ${key} => ${_val}"));
*
*
*
* gets transpiled to:
*
*
*
* console.info(`Get: ${key} => ${_val}`));
*
*
* @param templateString
* the regular Java string to be turned into a template string
* @return a JavaScript template string
*/
public static native String $template(String templateString);
/**
* Defines a template string with a tag.
*
* @see #$template(String)
*/
public static native String $template(Object tag, String templateString);
/**
* Inserts a TypeScript string as is in the generated program (not
* recommended). This can be seen as a compile-time eval.
*
*
* Although the TypeScript compiler will check the inserted code by
* compiling it, it is obviously a dangerous macro that should be used only
* in last resort.
*
* @see def.js.Globals#eval(String)
*/
public static native T $insert(String typescriptString);
public static native R await(Promise promise);
public static native R await(R promise);
public static native def.js.Function async(def.js.Function function);
public static native Promise asyncReturn(T result);
}