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