Interface CodingConvention
-
- All Superinterfaces:
java.io.Serializable
- All Known Implementing Classes:
ChromeCodingConvention
,ClosureCodingConvention
,CodingConventions.Proxy
,GoogleCodingConvention
@Immutable public interface CodingConvention extends java.io.Serializable
CodingConvention defines a set of hooks to customize the behavior of the Compiler for a specific team/company.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
CodingConvention.AssertionFunctionLookup
This stores a relation from either name or Closure Primitive to assertion functionstatic class
CodingConvention.AssertionFunctionSpec
A description of a JavaScript function that will throw an exception when either: One of its parameters does not match the return type of the function One of its parameters is falsy.static class
CodingConvention.Bind
Bind classstatic class
CodingConvention.Cache
Cache classstatic class
CodingConvention.DelegateRelationship
Delegates provides a mechanism and structure for identifying where classes can call out to optional code to augment their functionality.static class
CodingConvention.ObjectLiteralCast
An object literal cast provides a mechanism to cast object literals to other types without a warning.static class
CodingConvention.SubclassRelationship
Record subclass relationsstatic class
CodingConvention.SubclassType
Specify the kind of inheritance
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description void
applyDelegateRelationship(NominalTypeBuilder delegateSuperclass, NominalTypeBuilder delegateBase, NominalTypeBuilder delegator, ObjectType delegateProxy, FunctionType findDelegate)
In many JS libraries, the function that creates a delegate relationship also adds properties to the delegator and delegate base.void
applySingletonGetter(NominalTypeBuilder classType, FunctionType getterType)
In many JS libraries, the function that adds a singleton getter to a class adds properties to the class.void
applySubclassRelationship(NominalTypeBuilder parent, NominalTypeBuilder child, CodingConvention.SubclassType type)
In many JS libraries, the function that produces inheritance also adds properties to the superclass and/or subclass.boolean
blockRenamingForProperty(java.lang.String name)
Check whether the property name is eligible for renaming.void
checkForCallingConventionDefinitions(Node getPropNode, java.util.Map<java.lang.String,java.lang.String> delegateCallingConventions)
Checks for getprops that set the calling conventions on delegate methods.void
defineDelegateProxyPrototypeProperties(JSTypeRegistry registry, java.util.List<NominalTypeBuilder> delegateProxies, java.util.Map<java.lang.String,java.lang.String> delegateCallingConventions)
Defines the delegate proxy prototype properties.CodingConvention.Cache
describeCachingCall(Node node)
Builds aCodingConvention.Cache
instance from the given call node and returns that instance, or null if theNode
does not resemble a cache utility call.CodingConvention.Bind
describeFunctionBind(Node n)
A Bind instance or null.CodingConvention.Bind
describeFunctionBind(Node n, boolean callerChecksTypes, boolean iCheckTypes)
A Bind instance or null.java.lang.String
extractClassNameIfProvide(Node node, Node parent)
Convenience method for determining provided dependencies amongst different JS scripts.java.lang.String
extractClassNameIfRequire(Node node, Node parent)
Convenience method for determining required dependencies amongst different JS scripts.boolean
extractIsModuleFile(Node node, Node parent)
Convenience method for determining if the node indicates the file is a "module" file (a file whose top level symbols are not in global scope).java.lang.String
getAbstractMethodName()
Function name for abstract methods.java.util.Collection<CodingConvention.AssertionFunctionSpec>
getAssertionFunctions()
Returns the set of AssertionFunction.CodingConvention.SubclassRelationship
getClassesDefinedByCall(Node callNode)
Checks if the given method defines a subclass relationship, and if it does, returns information on that relationship.CodingConvention.DelegateRelationship
getDelegateRelationship(Node callNode)
java.lang.String
getDelegateSuperclassName()
java.lang.String
getExportPropertyFunction()
Function name used when exporting properties.java.lang.String
getExportSymbolFunction()
Function name used when exporting symbols.java.lang.String
getGlobalObject()
Gets the name of the global object.java.util.Collection<java.lang.String>
getIndirectlyDeclaredProperties()
Gets a collection of all properties that are defined indirectly on global objects.CodingConvention.ObjectLiteralCast
getObjectLiteralCast(Node callNode)
Checks if the given method performs a object literal cast, and if it does, returns information on the cast.java.lang.String
getPackageName(StaticSourceFile source)
java.lang.String
getSingletonGetterClassName(Node callNode)
Checks if the given method defines a singleton getter, and if it does, returns the name of the class with the singleton getter.boolean
hasPrivacyConvention()
Whether this CodingConvention includes a convention for what private names should look like.java.util.List<java.lang.String>
identifyTypeDeclarationCall(Node n)
Checks if the given CALL node is forward-declaring any types, and returns the name of the types if it is.boolean
isClassFactoryCall(Node callNode)
Checks if the given method is a call to a class factory, such a factory returns a unique class.boolean
isConstant(java.lang.String variableName)
This checks whether a given variable name, such as a name in all-caps should be treated as if it had the @const annotation.boolean
isConstantKey(java.lang.String keyName)
This checks whether a given key of an object literal, such as a name in all-caps should be treated as if it had the @const annotation.default boolean
isExported(java.lang.String name)
Equivalent to `isExported(name, true) || isExported(name, false);`boolean
isExported(java.lang.String name, boolean local)
Checks whether a global variable or function name should be treated as exported, or externally referenceable.boolean
isFunctionCallThatAlwaysThrows(Node n)
Used by CheckMissingReturn.boolean
isInlinableFunction(Node n)
boolean
isOptionalParameter(Node parameter)
This checks whether a given parameter name should be treated as an optional parameter as far as type checking or function call arg count checking is concerned.boolean
isPrivate(java.lang.String name)
Checks whether a name should be considered private.boolean
isPropertyRenameFunction(java.lang.String name)
Whether this CALL function is returning the string name for a property, but allows renaming.boolean
isPropertyTestFunction(Node call)
Whether this CALL function is testing for the existence of a property.boolean
isPrototypeAlias(Node getProp)
Whether this GETPROP node is an alias for an object prototype.boolean
isSuperClassReference(java.lang.String propertyName)
Returns true if passed a string referring to the superclass.boolean
isValidEnumKey(java.lang.String key)
This checks that a givenkey
may be used as a key for an enum.boolean
isVarArgsParameter(Node parameter)
This checks whether a given parameter should be treated as a marker for a variable argument list function.
-
-
-
Method Detail
-
isConstant
boolean isConstant(java.lang.String variableName)
This checks whether a given variable name, such as a name in all-caps should be treated as if it had the @const annotation.- Parameters:
variableName
- potentially constant variable name- Returns:
true
if the name should be treated as a constant.
-
isConstantKey
boolean isConstantKey(java.lang.String keyName)
This checks whether a given key of an object literal, such as a name in all-caps should be treated as if it had the @const annotation.
-
isValidEnumKey
boolean isValidEnumKey(java.lang.String key)
This checks that a givenkey
may be used as a key for an enum.- Parameters:
key
- the potential key to an enum- Returns:
true
if thekey
may be used as an enum key,false
otherwise
-
isOptionalParameter
boolean isOptionalParameter(Node parameter)
This checks whether a given parameter name should be treated as an optional parameter as far as type checking or function call arg count checking is concerned. Note that an optional function parameter may be declared as a simple type and is automatically converted to a union of the declared type and Undefined.- Parameters:
parameter
- The parameter's node.- Returns:
true
if the parameter should be treated as an optional parameter.
-
isVarArgsParameter
boolean isVarArgsParameter(Node parameter)
This checks whether a given parameter should be treated as a marker for a variable argument list function. A VarArgs parameter must be the last parameter in a function declaration.- Parameters:
parameter
- The parameter's node.- Returns:
true
if the parameter should be treated as a variable length parameter.
-
isFunctionCallThatAlwaysThrows
boolean isFunctionCallThatAlwaysThrows(Node n)
Used by CheckMissingReturn. When a function call always throws an error, it can be the last stm of a block and we don't warn about missing return.
-
isExported
boolean isExported(java.lang.String name, boolean local)
Checks whether a global variable or function name should be treated as exported, or externally referenceable.- Parameters:
name
- A global variable or function name.local
-true
if the name is a local variable.- Returns:
true
if the name should be considered exported.
-
isExported
default boolean isExported(java.lang.String name)
Equivalent to `isExported(name, true) || isExported(name, false);`Should only be used to check if a property is exported. Variables should always use
isExported(String, boolean)
, as in most cases local variables should not be treated as exported.Do not override! Unfortunately, that cannot be enforced without making this an abstract class.
-
blockRenamingForProperty
boolean blockRenamingForProperty(java.lang.String name)
Check whether the property name is eligible for renaming. This method will not block removal or collapsing of the property; it will just block renaming if the property is not optimized away.- Parameters:
name
- A property name.- Returns:
true
if the name can not be renamed.
-
getPackageName
java.lang.String getPackageName(StaticSourceFile source)
- Returns:
- the package name for the given source file, or null if no package name is known.
-
isPrivate
boolean isPrivate(java.lang.String name)
Checks whether a name should be considered private. Private global variables and functions can only be referenced within the source file in which they are declared. Private properties and methods should only be accessed by the class that defines them.- Parameters:
name
- The name of a global variable or function, or a method or property.- Returns:
true
if the name should be considered private.
-
hasPrivacyConvention
boolean hasPrivacyConvention()
Whether this CodingConvention includes a convention for what private names should look like.
-
getClassesDefinedByCall
CodingConvention.SubclassRelationship getClassesDefinedByCall(Node callNode)
Checks if the given method defines a subclass relationship, and if it does, returns information on that relationship. By default, always returns null. Meant to be overridden by subclasses.- Parameters:
callNode
- A CALL node.
-
isClassFactoryCall
boolean isClassFactoryCall(Node callNode)
Checks if the given method is a call to a class factory, such a factory returns a unique class.- Parameters:
callNode
- A CALL node.
-
isSuperClassReference
boolean isSuperClassReference(java.lang.String propertyName)
Returns true if passed a string referring to the superclass. The string will usually be from the string node at the right of a GETPROP, e.g. this.superClass_.
-
extractIsModuleFile
boolean extractIsModuleFile(Node node, Node parent)
Convenience method for determining if the node indicates the file is a "module" file (a file whose top level symbols are not in global scope).
-
extractClassNameIfProvide
java.lang.String extractClassNameIfProvide(Node node, Node parent)
Convenience method for determining provided dependencies amongst different JS scripts.
-
extractClassNameIfRequire
java.lang.String extractClassNameIfRequire(Node node, Node parent)
Convenience method for determining required dependencies amongst different JS scripts.
-
getExportPropertyFunction
java.lang.String getExportPropertyFunction()
Function name used when exporting properties. Signature: fn(object, publicName, symbol).- Returns:
- function name.
-
getExportSymbolFunction
java.lang.String getExportSymbolFunction()
Function name used when exporting symbols. Signature: fn(publicPath, object).- Returns:
- function name.
-
identifyTypeDeclarationCall
java.util.List<java.lang.String> identifyTypeDeclarationCall(Node n)
Checks if the given CALL node is forward-declaring any types, and returns the name of the types if it is.
-
applySubclassRelationship
void applySubclassRelationship(NominalTypeBuilder parent, NominalTypeBuilder child, CodingConvention.SubclassType type)
In many JS libraries, the function that produces inheritance also adds properties to the superclass and/or subclass.
-
getAbstractMethodName
java.lang.String getAbstractMethodName()
Function name for abstract methods. An abstract method can be assigned to an interface method instead of an function expression in order to avoid linter warnings produced by assigning a function without a return value where a return value is expected.- Returns:
- function name.
-
getSingletonGetterClassName
java.lang.String getSingletonGetterClassName(Node callNode)
Checks if the given method defines a singleton getter, and if it does, returns the name of the class with the singleton getter. By default, always returns null. Meant to be overridden by subclasses. addSingletonGetter needs a coding convention because in the general case, it can't be inlined. The function inliner sees that it creates an alias to the given class in an inner closure, and bails out.- Parameters:
callNode
- A CALL node.
-
applySingletonGetter
void applySingletonGetter(NominalTypeBuilder classType, FunctionType getterType)
In many JS libraries, the function that adds a singleton getter to a class adds properties to the class.
-
isInlinableFunction
boolean isInlinableFunction(Node n)
- Returns:
- Whether the function is inlinable by convention.
-
getDelegateRelationship
CodingConvention.DelegateRelationship getDelegateRelationship(Node callNode)
- Returns:
- the delegate relationship created by the call or null.
-
applyDelegateRelationship
void applyDelegateRelationship(NominalTypeBuilder delegateSuperclass, NominalTypeBuilder delegateBase, NominalTypeBuilder delegator, ObjectType delegateProxy, FunctionType findDelegate)
In many JS libraries, the function that creates a delegate relationship also adds properties to the delegator and delegate base.
-
getDelegateSuperclassName
java.lang.String getDelegateSuperclassName()
- Returns:
- the name of the delegate superclass.
-
checkForCallingConventionDefinitions
void checkForCallingConventionDefinitions(Node getPropNode, java.util.Map<java.lang.String,java.lang.String> delegateCallingConventions)
Checks for getprops that set the calling conventions on delegate methods.
-
defineDelegateProxyPrototypeProperties
void defineDelegateProxyPrototypeProperties(JSTypeRegistry registry, java.util.List<NominalTypeBuilder> delegateProxies, java.util.Map<java.lang.String,java.lang.String> delegateCallingConventions)
Defines the delegate proxy prototype properties. Their types depend on properties of the delegate base methods.- Parameters:
delegateProxies
- List of delegate proxy types.
-
getGlobalObject
java.lang.String getGlobalObject()
Gets the name of the global object.
-
describeFunctionBind
CodingConvention.Bind describeFunctionBind(Node n)
A Bind instance or null.
-
describeFunctionBind
CodingConvention.Bind describeFunctionBind(Node n, boolean callerChecksTypes, boolean iCheckTypes)
A Bind instance or null.When seeing an expression exp1.bind(recv, arg1, ...); we only know that it's a function bind if exp1 has type function. W/out type info, exp1 has certainly a function type only if it's a function literal.
If type checking has already happened, exp1's type is attached to the AST node. When iCheckTypes is true, describeFunctionBind looks for that type.
- Parameters:
callerChecksTypes
- Trust that the caller of this method has verified that the bound node has a function type.iCheckTypes
- Check that the bound node has a function type.
-
describeCachingCall
CodingConvention.Cache describeCachingCall(Node node)
Builds aCodingConvention.Cache
instance from the given call node and returns that instance, or null if theNode
does not resemble a cache utility call.This should match calls to a cache utility method. This type of node is specially considered for side-effects since conventionally storing something on a cache object would be seen as a side-effect.
-
isPropertyTestFunction
boolean isPropertyTestFunction(Node call)
Whether this CALL function is testing for the existence of a property.
-
isPrototypeAlias
boolean isPrototypeAlias(Node getProp)
Whether this GETPROP node is an alias for an object prototype.
-
isPropertyRenameFunction
boolean isPropertyRenameFunction(java.lang.String name)
Whether this CALL function is returning the string name for a property, but allows renaming.
-
getObjectLiteralCast
CodingConvention.ObjectLiteralCast getObjectLiteralCast(Node callNode)
Checks if the given method performs a object literal cast, and if it does, returns information on the cast. By default, always returns null. Meant to be overridden by subclasses.- Parameters:
callNode
- A CALL node.
-
getIndirectlyDeclaredProperties
java.util.Collection<java.lang.String> getIndirectlyDeclaredProperties()
Gets a collection of all properties that are defined indirectly on global objects. (For example, Closure defines superClass_ in the goog.inherits call).
-
getAssertionFunctions
java.util.Collection<CodingConvention.AssertionFunctionSpec> getAssertionFunctions()
Returns the set of AssertionFunction.
-
-