com.google.javascript.rhino.ClosurePrimitive Maven / Gradle / Ivy
/*
*
* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (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.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is Rhino code, released
* May 6, 1999.
*
* The Initial Developer of the Original Code is
* Netscape Communications Corporation.
* Portions created by the Initial Developer are Copyright (C) 1997-1999
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
* Bob Jervis
* Google Inc.
*
* Alternatively, the contents of this file may be used under the terms of
* the GNU General Public License Version 2 or later (the "GPL"), in which
* case the provisions of the GPL are applicable instead of those above. If
* you wish to allow use of your version of this file only under the terms of
* the GPL and not to allow others to use your version of this file under the
* MPL, indicate your decision by deleting the provisions above and replacing
* them with the notice and other provisions required by the GPL. If you do
* not delete the provisions above, a recipient may use your version of this
* file under either the MPL or the GPL.
*
* ***** END LICENSE BLOCK ***** */
package com.google.javascript.rhino;
import com.google.common.collect.ImmutableMap;
import javax.annotation.Nullable;
/**
* Enum of primitive functions that the compiler recognizes
*
* These correspond to the @closurePrimitive tag in code; in order to parse new primitives, add
* any entry to the list in parsing/ParserConfig.properties, then map it to an enum member in the
* idToEnum map.
*
*
After typechecking is done, all calls to one of these primitive types should have their
* FunctionType annotated with the corresponding enum member. This is intended to make identifying
* these calls more accurate than previous methods of finding primitives by qualified name.
*/
public enum ClosurePrimitive {
ASSERTS_FAIL, // A function that always throws an error
ASSERTS_MATCHES_RETURN, // A function that asserts its first parameter matches the return type
ASSERTS_TRUTHY; // A function that asserts its first parameter is truthy and returns the param
/**
* Maps human-readable ids to enum members.
*
*
The expected mapping (although not enforced) of keys -> values is that the enum member maps
* to a lowercase string with "_" replaced with "."
*/
private static final ImmutableMap ID_TO_ENUM =
ImmutableMap.of(
"asserts.fail",
ASSERTS_FAIL,
"asserts.truthy",
ASSERTS_TRUTHY,
"asserts.matchesReturn",
ASSERTS_MATCHES_RETURN);
/**
* Returns the ClosurePrimitive corresponding to the given string id.
*
* This is to make reading {@code @closurePrimitive} easier in code. Using Enum.valueOf to
* parse closure primitive identifiers from JSDoc directly would require code like {@code
* closurePrimitive {ASSERTS_FAIL}}; instead we separate the string ids from the enum names.
*
* @param id a string id that normalized to an enum member, or null
* @throws IllegalArgumentException if the id is non-null but does not match an enum member
* @return null if the argument is null, otherwise the corresponding enum member
*/
@Nullable
public static ClosurePrimitive fromStringId(@Nullable String id) {
if (id == null) {
return null;
}
ClosurePrimitive primitive = ID_TO_ENUM.get(id);
if (primitive == null) {
throw new IllegalArgumentException(
"String id " + id + " does not match any ClosurePrimitive");
}
return primitive;
}
}