com.facebook.buck.core.starlark.compatible

Class BuckSkylarkTypes

java.lang.Object

com.facebook.buck.core.starlark.compatible.BuckSkylarkTypes

public class BuckSkylarkTypes
extends Object

Container class for helper methods having to deal with Skylark types. e.g. list or map conversion utilities that supplement the built in helpers.

Method Summary

Modifier and Type	Method and Description
static Object	asDeepImmutable(Object arg) Attempt to get a deeply immutable instance of a value passed in from Skylark
static boolean	isImmutable(Object o) Checks if a given value is 'Immutable'.
static Object	skylarkValueFromNullable(Object object)
static <NonWildcardType,DestType extends NonWildcardType> com.google.common.collect.ImmutableList<DestType>	toJavaList(com.google.devtools.build.lib.syntax.SkylarkList<?> list, Class<NonWildcardType> elementClass, String description) Validate that all objects are of a given type and return an ImmutableList containing those objects.
static void	validateKwargName(com.google.devtools.build.lib.events.Location location, String kwarg) Ensure that a name is a valid kwarg/field identifier
static Object	validateNoneOrType(com.google.devtools.build.lib.events.Location location, Class<?> clazz, Object object) Check that a value is either Runtime.NONE or an instance of clazz

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

toJavaList

public static <NonWildcardType,DestType extends NonWildcardType> com.google.common.collect.ImmutableList<DestType> toJavaList(com.google.devtools.build.lib.syntax.SkylarkList<?> list,
                                                                                                                              Class<NonWildcardType> elementClass,
                                                                                                                              @Nullable
                                                                                                                              String description)
                                                                                                                       throws com.google.devtools.build.lib.syntax.EvalException

Validate that all objects are of a given type and return an ImmutableList containing those objects.

This is a workaround for SkylarkList.getContents(Class, String) being unable to handle generic types correctly. e.g. it is currently impossible to do:

 SkylarkList<?> skyList = // Provided by user
 // Works, but compiler complains because Provider is not specialized
 ImmutableList<Provider> providers = skyList.getContents(Provider.class, null));
 // Does not work because Provider.class != the class of Provider<?>
 ImmutableList<Provider<?>> providers = skyList.getContents(Provider.class, null));
 

This function makes the following usage possible

 SkylarkList<?> skyList = // Provided by user
 ImmutableList<Provider<?>> providers = BuckSkylarkTypes.toJavaList(skyList, Provider.class, null));
 

This function wraps a dirty type cast up and tries to apply some basic type boundaries to reduce the likelihood of creating a foot gun.

Type Parameters:

NonWildcardType - The non-wildcard type. e.g. Provider.class

DestType - The type of the elements in the resulting container. This can be either the same as NonWildcardType, or a generic type like Provider<?>

Parameters:

list - The list of objects to validate

elementClass - The non-wildcard version of the desired final class

description - a description of the argument being converted, or null, for debugging

Returns:

A list of DestType. This is immutable because we do some type casting under the hood, and do not want any assumptions to be made about the backing store of the container, nor do we want users to assume they can safely insert into that list.

Throws:

com.google.devtools.build.lib.syntax.EvalException - If one of the elements was not of the type specified in elementClass

asDeepImmutable

public static Object asDeepImmutable(Object arg)
                              throws MutableObjectException

Attempt to get a deeply immutable instance of a value passed in from Skylark

Note that if mutable objects are passed in (namely SkylarkList or SkylarkDict, a copy may be made to get an immutable instance. This may happen in very deeply nested structures, so the runtime is variable based on how mutable the objects are. For the best performance, only immutable structures should be passed in, as that turns into a simple identity function.

Parameters:

arg - A value from the skylark interpreter. This should only be primitive objects, or SkylarkValue instances

Returns:

The original object if it was already an immutable SkylarkValue or a primitive value

an immutable SkylarkList if the original object is a SkylarkList and all values were immutable or could be made immutable. As above, this may be a copy, or inner elements may have had to be copied if they were mutable

An immutable SkylarkDict if the original object is a SkylarkDict and all keys and values were immutable, or could be made so. Again, note that copies may be made in order to make mutable objects immutable

Throws:

MutableObjectException - If a nested or top level object was mutable, and could not be made immutable. This generally only applies to incorrectly implemented native data types that are exported to Skylark.

validateKwargName

public static void validateKwargName(com.google.devtools.build.lib.events.Location location,
                                     String kwarg)
                              throws com.google.devtools.build.lib.syntax.EvalException

Ensure that a name is a valid kwarg/field identifier

This is useful as Skylark does not validate these by default when creating a signature

Parameters:

location - location of the kwarg currently being evaluated

kwarg - the name of a kwarg / field

Throws:

com.google.devtools.build.lib.syntax.EvalException

skylarkValueFromNullable

public static Object skylarkValueFromNullable(@Nullable
                                              Object object)

Returns:

None if object is null, else return object. This is just a central place ot make sure things we return from internal implementations into Skylark are properly turned into None

validateNoneOrType

public static Object validateNoneOrType(com.google.devtools.build.lib.events.Location location,
                                        Class<?> clazz,
                                        Object object)
                                 throws com.google.devtools.build.lib.syntax.EvalException

Check that a value is either Runtime.NONE or an instance of clazz

Parameters:

location - location of evaluation

clazz - the class that the object should be an instance of if not Runtime.NONE

object - the object to check

Returns:

the original value if it is of a correct type

Throws:

com.google.devtools.build.lib.syntax.EvalException - if the object is not of the correct type

isImmutable

public static boolean isImmutable(Object o)

Checks if a given value is 'Immutable'. This mostly works like EvalUtils.isImmutable(java.lang.Object), but it can also handle ImmutableCollection and ImmutableMap