tools/gn/functions.h

   1 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef TOOLS_GN_FUNCTIONS_H_
   6 #define TOOLS_GN_FUNCTIONS_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "base/containers/hash_tables.h"
  12 #include "base/strings/string_piece.h"
  13
  14 class Err;
  15 class BlockNode;
  16 class FunctionCallNode;
  17 class Label;
  18 class ListNode;
  19 class ParseNode;
  20 class Scope;
  21 class Token;
  22 class Value;
  23
  24 // -----------------------------------------------------------------------------
  25
  26 namespace functions {
  27
  28 // This type of function invocation has no block and evaluates its arguments
  29 // itself rather than taking a pre-executed list. This allows us to implement
  30 // certain built-in functions.
  31 typedef Value (*SelfEvaluatingArgsFunction)(Scope* scope,
  32                                             const FunctionCallNode* function,
  33                                             const ListNode* args_list,
  34                                             Err* err);
  35
  36 // This type of function invocation takes a block node that it will execute.
  37 typedef Value (*GenericBlockFunction)(Scope* scope,
  38                                       const FunctionCallNode* function,
  39                                       const std::vector<Value>& args,
  40                                       BlockNode* block,
  41                                       Err* err);
  42
  43 // This type of function takes a block, but does not need to control execution
  44 // of it. The dispatch function will pre-execute the block and pass the
  45 // resulting block_scope to the function.
  46 typedef Value(*ExecutedBlockFunction)(const FunctionCallNode* function,
  47                                       const std::vector<Value>& args,
  48                                       Scope* block_scope,
  49                                       Err* err);
  50
  51 // This type of function does not take a block. It just has arguments.
  52 typedef Value (*NoBlockFunction)(Scope* scope,
  53                                  const FunctionCallNode* function,
  54                                  const std::vector<Value>& args,
  55                                  Err* err);
  56
  57 extern const char kAssert[];
  58 extern const char kAssert_Help[];
  59 Value RunAssert(Scope* scope,
  60                 const FunctionCallNode* function,
  61                 const std::vector<Value>& args,
  62                 Err* err);
  63
  64 extern const char kComponent[];
  65 extern const char kComponent_Help[];
  66 Value RunComponent(Scope* scope,
  67                    const FunctionCallNode* function,
  68                    const std::vector<Value>& args,
  69                    BlockNode* block,
  70                    Err* err);
  71
  72 extern const char kConfig[];
  73 extern const char kConfig_Help[];
  74 Value RunConfig(const FunctionCallNode* function,
  75                 const std::vector<Value>& args,
  76                 Scope* block_scope,
  77                 Err* err);
  78
  79 extern const char kCopy[];
  80 extern const char kCopy_Help[];
  81 Value RunCopy(const FunctionCallNode* function,
  82               const std::vector<Value>& args,
  83               Scope* block_scope,
  84               Err* err);
  85
  86 extern const char kCustom[];
  87 extern const char kCustom_Help[];
  88 Value RunCustom(Scope* scope,
  89                 const FunctionCallNode* function,
  90                 const std::vector<Value>& args,
  91                 BlockNode* block,
  92                 Err* err);
  93
  94 extern const char kDeclareArgs[];
  95 extern const char kDeclareArgs_Help[];
  96 Value RunDeclareArgs(Scope* scope,
  97                      const FunctionCallNode* function,
  98                      const std::vector<Value>& args,
  99                      BlockNode* block,
 100                      Err* err);
 101
 102 extern const char kDefined[];
 103 extern const char kDefined_Help[];
 104 Value RunDefined(Scope* scope,
 105                  const FunctionCallNode* function,
 106                  const ListNode* args_list,
 107                  Err* err);
 108
 109 extern const char kExecScript[];
 110 extern const char kExecScript_Help[];
 111 Value RunExecScript(Scope* scope,
 112                     const FunctionCallNode* function,
 113                     const std::vector<Value>& args,
 114                     Err* err);
 115
 116 extern const char kExecutable[];
 117 extern const char kExecutable_Help[];
 118 Value RunExecutable(Scope* scope,
 119                     const FunctionCallNode* function,
 120                     const std::vector<Value>& args,
 121                     BlockNode* block,
 122                     Err* err);
 123
 124 extern const char kGroup[];
 125 extern const char kGroup_Help[];
 126 Value RunGroup(Scope* scope,
 127                const FunctionCallNode* function,
 128                const std::vector<Value>& args,
 129                BlockNode* block,
 130                Err* err);
 131
 132 extern const char kImport[];
 133 extern const char kImport_Help[];
 134 Value RunImport(Scope* scope,
 135                 const FunctionCallNode* function,
 136                 const std::vector<Value>& args,
 137                 Err* err);
 138
 139 extern const char kPrint[];
 140 extern const char kPrint_Help[];
 141 Value RunPrint(Scope* scope,
 142                const FunctionCallNode* function,
 143                const std::vector<Value>& args,
 144                Err* err);
 145
 146 extern const char kProcessFileTemplate[];
 147 extern const char kProcessFileTemplate_Help[];
 148 Value RunProcessFileTemplate(Scope* scope,
 149                              const FunctionCallNode* function,
 150                              const std::vector<Value>& args,
 151                              Err* err);
 152
 153 extern const char kReadFile[];
 154 extern const char kReadFile_Help[];
 155 Value RunReadFile(Scope* scope,
 156                   const FunctionCallNode* function,
 157                   const std::vector<Value>& args,
 158                   Err* err);
 159
 160 extern const char kRebasePath[];
 161 extern const char kRebasePath_Help[];
 162 Value RunRebasePath(Scope* scope,
 163                     const FunctionCallNode* function,
 164                     const std::vector<Value>& args,
 165                     Err* err);
 166
 167 extern const char kSetDefaults[];
 168 extern const char kSetDefaults_Help[];
 169 Value RunSetDefaults(Scope* scope,
 170                      const FunctionCallNode* function,
 171                      const std::vector<Value>& args,
 172                      BlockNode* block,
 173                      Err* err);
 174
 175 extern const char kSetDefaultToolchain[];
 176 extern const char kSetDefaultToolchain_Help[];
 177 Value RunSetDefaultToolchain(Scope* scope,
 178                              const FunctionCallNode* function,
 179                              const std::vector<Value>& args,
 180                              Err* err);
 181
 182 extern const char kSetSourcesAssignmentFilter[];
 183 extern const char kSetSourcesAssignmentFilter_Help[];
 184 Value RunSetSourcesAssignmentFilter(Scope* scope,
 185                                     const FunctionCallNode* function,
 186                                     const std::vector<Value>& args,
 187                                     Err* err);
 188
 189 extern const char kSharedLibrary[];
 190 extern const char kSharedLibrary_Help[];
 191 Value RunSharedLibrary(Scope* scope,
 192                        const FunctionCallNode* function,
 193                        const std::vector<Value>& args,
 194                        BlockNode* block,
 195                        Err* err);
 196
 197 extern const char kSourceSet[];
 198 extern const char kSourceSet_Help[];
 199 Value RunSourceSet(Scope* scope,
 200                    const FunctionCallNode* function,
 201                    const std::vector<Value>& args,
 202                    BlockNode* block,
 203                    Err* err);
 204
 205 extern const char kStaticLibrary[];
 206 extern const char kStaticLibrary_Help[];
 207 Value RunStaticLibrary(Scope* scope,
 208                        const FunctionCallNode* function,
 209                        const std::vector<Value>& args,
 210                        BlockNode* block,
 211                        Err* err);
 212
 213 extern const char kTemplate[];
 214 extern const char kTemplate_Help[];
 215 Value RunTemplate(Scope* scope,
 216                   const FunctionCallNode* function,
 217                   const std::vector<Value>& args,
 218                   BlockNode* block,
 219                   Err* err);
 220
 221 extern const char kTest[];
 222 extern const char kTest_Help[];
 223 Value RunTest(Scope* scope,
 224               const FunctionCallNode* function,
 225               const std::vector<Value>& args,
 226               BlockNode* block,
 227               Err* err);
 228
 229 extern const char kTool[];
 230 extern const char kTool_Help[];
 231 Value RunTool(Scope* scope,
 232               const FunctionCallNode* function,
 233               const std::vector<Value>& args,
 234               BlockNode* block,
 235               Err* err);
 236
 237 extern const char kToolchain[];
 238 extern const char kToolchain_Help[];
 239 Value RunToolchain(Scope* scope,
 240                    const FunctionCallNode* function,
 241                    const std::vector<Value>& args,
 242                    BlockNode* block,
 243                    Err* err);
 244
 245 extern const char kToolchainArgs[];
 246 extern const char kToolchainArgs_Help[];
 247 Value RunToolchainArgs(Scope* scope,
 248                        const FunctionCallNode* function,
 249                        const std::vector<Value>& args,
 250                        BlockNode* block,
 251                        Err* err);
 252
 253 extern const char kWriteFile[];
 254 extern const char kWriteFile_Help[];
 255 Value RunWriteFile(Scope* scope,
 256                    const FunctionCallNode* function,
 257                    const std::vector<Value>& args,
 258                    Err* err);
 259
 260 // -----------------------------------------------------------------------------
 261
 262 // One function record. Only one of the given runner types will be non-null
 263 // which indicates the type of function it is.
 264 struct FunctionInfo {
 265   FunctionInfo();
 266   FunctionInfo(SelfEvaluatingArgsFunction seaf, const char* in_help);
 267   FunctionInfo(GenericBlockFunction gbf, const char* in_help);
 268   FunctionInfo(ExecutedBlockFunction ebf, const char* in_help);
 269   FunctionInfo(NoBlockFunction nbf, const char* in_help);
 270
 271   SelfEvaluatingArgsFunction self_evaluating_args_runner;
 272   GenericBlockFunction generic_block_runner;
 273   ExecutedBlockFunction executed_block_runner;
 274   NoBlockFunction no_block_runner;
 275
 276   const char* help;
 277 };
 278
 279 typedef base::hash_map<base::StringPiece, FunctionInfo> FunctionInfoMap;
 280
 281 // Returns the mapping of all built-in functions.
 282 const FunctionInfoMap& GetFunctions();
 283
 284 // Runs the given function.
 285 Value RunFunction(Scope* scope,
 286                   const FunctionCallNode* function,
 287                   const ListNode* args_list,
 288                   BlockNode* block,  // Optional.
 289                   Err* err);
 290
 291 }  // namespace functions
 292
 293 // Helper functions -----------------------------------------------------------
 294
 295 // Verifies that the current scope is not processing an import. If it is, it
 296 // will set the error, blame the given parse node for it, and return false.
 297 bool EnsureNotProcessingImport(const ParseNode* node,
 298                                const Scope* scope,
 299                                Err* err);
 300
 301 // Like EnsureNotProcessingImport but checks for running the build config.
 302 bool EnsureNotProcessingBuildConfig(const ParseNode* node,
 303                                     const Scope* scope,
 304                                     Err* err);
 305
 306 // Sets up the |block_scope| for executing a target (or something like it).
 307 // The |scope| is the containing scope. It should have been already set as the
 308 // parent for the |block_scope| when the |block_scope| was created.
 309 //
 310 // This will set up the target defaults and set the |target_name| variable in
 311 // the block scope to the current target name, which is assumed to be the first
 312 // argument to the function.
 313 //
 314 // On success, returns true. On failure, sets the error and returns false.
 315 bool FillTargetBlockScope(const Scope* scope,
 316                           const FunctionCallNode* function,
 317                           const std::string& target_type,
 318                           const BlockNode* block,
 319                           const std::vector<Value>& args,
 320                           Scope* block_scope,
 321                           Err* err);
 322
 323 // Sets the given error to a message explaining that the function call requires
 324 // a block.
 325 void FillNeedsBlockError(const FunctionCallNode* function, Err* err);
 326
 327 // Validates that the given function call has one string argument. This is
 328 // the most common function signature, so it saves space to have this helper.
 329 // Returns false and sets the error on failure.
 330 bool EnsureSingleStringArg(const FunctionCallNode* function,
 331                            const std::vector<Value>& args,
 332                            Err* err);
 333
 334 // Returns the name of the toolchain for the given scope.
 335 const Label& ToolchainLabelForScope(const Scope* scope);
 336
 337 // Generates a label for the given scope, using the current directory and
 338 // toolchain, and the given name.
 339 Label MakeLabelForScope(const Scope* scope,
 340                         const FunctionCallNode* function,
 341                         const std::string& name);
 342
 343 #endif  // TOOLS_GN_FUNCTIONS_H_