hphp/hack/hhi/BuiltinEnum.hhi

   1 <?hh
   2 /**
   3  * Copyright (c) 2014, Facebook, Inc.
   4  * All rights reserved.
   5  *
   6  * This source code is licensed under the MIT license found in the
   7  * LICENSE file in the "hack" directory of this source tree.
   8  *
   9  */
  10
  11 /**
  12  * This file provides type information for some of HHVM's builtin classes.
  13  *
  14  * YOU SHOULD NEVER INCLUDE THIS FILE ANYWHERE!!!
  15  */
  16 namespace HH {
  17
  18 /**
  19  * BuiltinEnum contains the utility methods provided by enums.
  20  * Under the hood, an enum Foo will extend BuiltinEnum<Foo>.
  21  *
  22  * HHVM provides a native implementation for this class. The PHP class
  23  * definition below is not actually used at run time; it is simply
  24  * provided for the typechecker and for developer reference.
  25  */
  26 abstract class BuiltinEnum<+T> {
  27   /**
  28    * Get the values of the public consts defined on this class,
  29    * indexed by the string name of those consts.
  30    *
  31    * @return array ('CONST_NAME' => $value, ....)
  32    */
  33   <<__Pure>>
  34   final public static function getValues(): darray<string, T>;
  35
  36   /**
  37    * Get the names of all the const values, indexed by value. Calls
  38    * invariant_exception if multiple constants have the same value.
  39    *
  40    * @return array($value => 'CONST_NAME', ....)
  41    */
  42   <<__Pure>>
  43   final public static function getNames(): darray<T, string> where T as arraykey;
  44
  45   /**
  46    * Returns whether or not the value is defined as a constant.
  47    */
  48   <<__Pure>>
  49   final public static function isValid(mixed $value): bool;
  50
  51   /**
  52    * Coerce to a valid value or null.
  53    * This is useful for typing deserialized enum values.
  54    */
  55   <<__Pure>>
  56   final public static function coerce(mixed $value): ?T;
  57
  58   /**
  59    * Coerce to valid value or throw UnexpectedValueException
  60    * This is useful for typing deserialized enum values.
  61    */
  62   <<__Pure>>
  63   final public static function assert(mixed $value): T;
  64
  65   /**
  66    * Coerce all the values in a traversable. If the value is not an
  67    * array of valid items, an UnexpectedValueException is thrown
  68    */
  69   <<__Pure, __AtMostRxAsArgs>>
  70   final public static function assertAll(
  71     <<__OnlyRxIfImpl(\HH\Rx\Traversable::class), __MaybeMutable>> Traversable<mixed> $values,
  72   ): Container<T>;
  73 }
  74
  75 type enumname<T> = classname<BuiltinEnum<T>>;
  76
  77 const enumname<arraykey> BUILTIN_ENUM = BuiltinEnum::class;
  78
  79 /* Experimental section for Enum Classes. This is bound to evolve with
  80  * the HIP process.
  81  */
  82
  83 /**
  84  * Base helper class for the enum class feature
  85  */
  86 final class Elt<-TPhantom, +T> {
  87   /* TODO(T77095784) How to make it private ? */
  88   public function __construct(private string $name, private T $data) {}
  89
  90   <<__Pure>>
  91   public function name(): string {
  92     return $this->name;
  93   }
  94
  95   /* TODO(T77095784) ask if this can be inlined/optimized */
  96   <<__Pure>>
  97   public function unwrap(): T {
  98     return $this->data;
  99   }
 100 }
 101
 102 /**
 103  * BuiltinEnumClass contains the utility methods provided by enum classes.
 104  * Under the hood, an enum class Foo : Bar will extend
 105  * BuiltinEnumClass<HH\Elt<this, Bar>>.
 106  *
 107  * HHVM provides a native implementation for this class. The PHP class
 108  * definition below is not actually used at run time; it is simply
 109  * provided for the typechecker and for developer reference.
 110  */
 111 <<__EnumClass>>
 112 abstract class BuiltinEnumClass<+T> {
 113   /**
 114    * Get the values of the public consts defined on this class,
 115    * indexed by the string name of those consts.
 116    *
 117    * @return array ('CONST_NAME' => $value, ....)
 118    */
 119   <<__Pure>>
 120   final public static function getValues(): darray<string, T>;
 121 }
 122
 123 }