hphp/runtime/vm/trait-method-import-data.h

   1 /*
   2    +----------------------------------------------------------------------+
   3    | HipHop for PHP                                                       |
   4    +----------------------------------------------------------------------+
   5    | Copyright (c) 2010-present Facebook, Inc. (http://www.facebook.com)  |
   6    +----------------------------------------------------------------------+
   7    | This source file is subject to version 3.01 of the PHP license,      |
   8    | that is bundled with this package in the file LICENSE, and is        |
   9    | available through the world-wide-web at the following url:           |
  10    | http://www.php.net/license/3_01.txt                                  |
  11    | If you did not receive a copy of the PHP license and are unable to   |
  12    | obtain it through the world-wide-web, please send a note to          |
  13    | license@php.net so we can mail you a copy immediately.               |
  14    +----------------------------------------------------------------------+
  15 */
  16
  17 #ifndef incl_HPHP_TRAIT_METHOD_IMPORT_DATA_H_
  18 #define incl_HPHP_TRAIT_METHOD_IMPORT_DATA_H_
  19
  20 #include <hphp/runtime/base/string-data.h>
  21 #include <hphp/runtime/vm/preclass.h>
  22
  23 #include <hphp/util/hash-map.h>
  24
  25 #include <functional>
  26 #include <list>
  27 #include <string>
  28 #include <unordered_set>
  29 #include <vector>
  30
  31 namespace HPHP {
  32 ///////////////////////////////////////////////////////////////////////////////
  33
  34 /*
  35  * Data used for trait method importing.
  36  *
  37  * Handles method order as well as trait alias and precedence resolution.
  38  *
  39  * The TraitMethod parameter class is expected to expose the following types
  40  * and members:
  41  *
  42  * TraitMethod {
  43  *    typename class_type;
  44  *    typename method_type;
  45  *
  46  *    class_type trait;
  47  *    method_type method;
  48  *    Attr modifiers;
  49  * }
  50  *
  51  * The Ops parameter class is expected to expose a number of static member
  52  * functions:
  53  *
  54  * Ops {
  55  *    // Return the name for a trait class/method.
  56  *    String clsName(TraitMethod::class_type traitCls);
  57  *    String methName(TraitMethod::method_type meth);
  58  *
  59  *    // Is-a methods.
  60  *    bool isTrait(TraitMethod::class_type traitCls);
  61  *    bool isAbstract(Attr modifiers);
  62  *
  63  *    // Whether to exclude methods with name `methName' when adding.
  64  *    bool exclude(const String& methName);
  65  *
  66  *    // TraitMethod constructor.
  67  *    TraitMethod traitMethod(TraitMethod::class_type traitCls,
  68  *                            TraitMethod::method_type traitMeth,
  69  *                            alias_rule rule);
  70  *
  71  *    // Register a trait alias once the trait class is found.
  72  *    void addTraitAlias(Context ctx, const PreClass::TraitAliasRule& rule,
  73  *                       TraitMethod::class_type traitCls);
  74  *
  75  *    // Trait class/method finders.
  76  *    TraitMethod::class_type
  77  *      findSingleTraitWithMethod(Context ctx, const String& origMethName);
  78  *    TraitMethod::class_type
  79  *      findTraitClass(Context ctx, const String& traitName);
  80  *    TraitMethod::method_type
  81  *      findTraitMethod(TraitMethod::class_type traitCls,
  82  *                      const String& origMethName);
  83  *
  84  *    // Errors.
  85  *    void errorUnknownMethod(const String& methName);
  86  *    void errorUnknownTrait(const String& traitName);
  87  *    void errorDuplicateMethod(Context ctx, const String& methName,
  88  *                              const std::list<TraitMethod>& methods);
  89  *    void errorInconsistentInsteadOf(Context ctx, const String& methName);
  90  *    void errorMultiplyExcluded(const String& traitName,
  91  *                               const String& methName);
  92  * }
  93  */
  94 template <class TraitMethod, class Ops>
  95 struct TraitMethodImportData {
  96   /////////////////////////////////////////////////////////////////////////////
  97   // Types.
  98
  99   using String = const StringData*;
 100
 101   /*
 102    * Data associated with a given trait name.
 103    */
 104   struct NameData {
 105     // List of all declared trait methods with the name.
 106     std::list<TraitMethod> methods;
 107     // In-order aliases of the name.
 108     std::vector<String> aliases;
 109   };
 110
 111   /*
 112    * Information associated with an imported method---essentially a (name,
 113    * method) pair.
 114    */
 115   struct MethodData {
 116     const String name;
 117     const TraitMethod tm;
 118   };
 119
 120
 121   /////////////////////////////////////////////////////////////////////////////
 122   // Public API.
 123
 124   /*
 125    * Get a reference to the list of trait method names.
 126    */
 127   const std::vector<String>& methodNames() { return m_orderedNames; }
 128
 129   /*
 130    * Add a trait method to the import data set.
 131    *
 132    * The add() methods should be called in the order in which the trait methods
 133    * were included in the importing class.
 134    */
 135   void add(const TraitMethod& tm, const String& name);
 136   void add(const TraitMethod& tm,
 137            const String& aliasedName,
 138            const String& origName);
 139
 140   /*
 141    * Erase all records of a trait method called `name'.
 142    */
 143   void erase(const String& name);
 144
 145   /*
 146    * Set rule modifiers on the trait declared on `trait' called `name' if it
 147    * exists.
 148    */
 149   void setModifiers(const String& name,
 150                     typename TraitMethod::class_type trait,
 151                     Attr mods);
 152
 153   /*
 154    * Apply a precedence ("insteadof") rule to the import data set.
 155    */
 156   void applyPrecRule(const PreClass::TraitPrecRule& rule,
 157                      typename TraitMethod::class_type ctx);
 158
 159   /*
 160    * Apply an alias ("as") rule to the import data set.
 161    */
 162   void applyAliasRule(const PreClass::TraitAliasRule& rule,
 163                       typename TraitMethod::class_type ctx);
 164
 165   /*
 166    * Declare that all imports have been added---and that all rules have been
 167    * applied---and return an ordered vector of all imported (name, TraitMethod)
 168    * pairs.
 169    *
 170    * Continued use of `this' after calling finish() is undefined.
 171    */
 172   auto finish(typename TraitMethod::class_type ctx);
 173
 174
 175   /////////////////////////////////////////////////////////////////////////////
 176   // Internals.
 177
 178 private:
 179   void removeSpareTraitAbstractMethods();
 180
 181
 182   /////////////////////////////////////////////////////////////////////////////
 183   // Data members.
 184
 185 private:
 186   // Map from trait method name to NameData.
 187   hphp_fast_map<String, NameData,
 188                 string_data_hash, string_data_isame> m_dataForName;
 189
 190   // Method names in order of first declaration.
 191   std::vector<String> m_orderedNames;
 192 };
 193
 194 ///////////////////////////////////////////////////////////////////////////////
 195 }
 196
 197 #include "hphp/runtime/vm/trait-method-import-data-inl.h"
 198
 199 #endif