gcc/rust/expand/rust-macro-builtins.h

   1 // Copyright (C) 2020-2023 Free Software Foundation, Inc.
   2
   3 // This file is part of GCC.
   4
   5 // GCC is free software; you can redistribute it and/or modify it under
   6 // the terms of the GNU General Public License as published by the Free
   7 // Software Foundation; either version 3, or (at your option) any later
   8 // version.
   9
  10 // GCC is distributed in the hope that it will be useful, but WITHOUT ANY
  11 // WARRANTY; without even the implied warranty of MERCHANTABILITY or
  12 // FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  13 // for more details.
  14
  15 // You should have received a copy of the GNU General Public License
  16 // along with GCC; see the file COPYING3.  If not see
  17 // <http://www.gnu.org/licenses/>.
  18
  19 #ifndef RUST_MACRO_BUILTINS_H
  20 #define RUST_MACRO_BUILTINS_H
  21
  22 #include "rust-ast.h"
  23 #include "rust-ast-fragment.h"
  24 #include "rust-location.h"
  25
  26 /**
  27  * This class provides a list of builtin macros implemented by the compiler.
  28  * The functions defined are called "builtin transcribers" in that they replace
  29  * the transcribing part of a macro definition.
  30  *
  31  * Like regular macro transcribers, they are responsible for building and
  32  * returning an AST fragment: basically a vector of AST nodes put together.
  33  *
  34  * Unlike regular declarative macros where each match arm has its own associated
  35  * transcriber, builtin transcribers are responsible for handling all match arms
  36  * of the macro. This means that you should take extra care when implementing a
  37  * builtin containing multiple match arms: You will probably need to do some
  38  * lookahead in order to determine which match arm the user intended to use.
  39  *
  40  * An example of this is the `assert!()` macro:
  41  *
  42  * ```
  43  *  macro_rules! assert {
  44  *      ($cond:expr $(,)?) => {{ ... }};
  45  *      ($cond : expr, $ ($arg : tt) +) = > {{ ... }};
  46  * }
  47  * ```
  48  *
  49  * If more tokens exist beyond the optional comma, they need to be handled as
  50  * a token-tree for a custom panic message.
  51  *
  52  * These builtin macros with empty transcribers are defined in the standard
  53  * library. They are marked with a special attribute, `#[rustc_builtin_macro]`.
  54  * When this attribute is present on a macro definition, the compiler should
  55  * look for an associated transcriber in the mappings. Meaning that you must
  56  * remember to insert your transcriber in the `builtin_macros` map of the
  57  *`Mappings`.
  58  *
  59  * This map is built as a static variable in the `insert_macro_def()` method
  60  * of the `Mappings` class.
  61  */
  62
  63 namespace Rust {
  64 class MacroBuiltin
  65 {
  66 public:
  67   static AST::Fragment assert_handler (Location invoc_locus,
  68                                        AST::MacroInvocData &invoc);
  69
  70   static AST::Fragment file_handler (Location invoc_locus,
  71                                      AST::MacroInvocData &invoc);
  72
  73   static AST::Fragment column_handler (Location invoc_locus,
  74                                        AST::MacroInvocData &invoc);
  75
  76   static AST::Fragment include_bytes_handler (Location invoc_locus,
  77                                               AST::MacroInvocData &invoc);
  78
  79   static AST::Fragment include_str_handler (Location invoc_locus,
  80                                             AST::MacroInvocData &invoc);
  81
  82   static AST::Fragment compile_error_handler (Location invoc_locus,
  83                                               AST::MacroInvocData &invoc);
  84
  85   static AST::Fragment concat_handler (Location invoc_locus,
  86                                        AST::MacroInvocData &invoc);
  87
  88   static AST::Fragment env_handler (Location invoc_locus,
  89                                     AST::MacroInvocData &invoc);
  90
  91   static AST::Fragment cfg_handler (Location invoc_locus,
  92                                     AST::MacroInvocData &invoc);
  93
  94   static AST::Fragment include_handler (Location invoc_locus,
  95                                         AST::MacroInvocData &invoc);
  96
  97   static AST::Fragment line_handler (Location invoc_locus,
  98                                      AST::MacroInvocData &invoc);
  99 };
 100 } // namespace Rust
 101
 102 #endif // RUST_MACRO_BUILTINS_H