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 <map>
   9 #include <string>
  10 #include <vector>
  11
  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 kAction[];
  58 extern const char kAction_HelpShort[];
  59 extern const char kAction_Help[];
  60 Value RunAction(Scope* scope,
  61                 const FunctionCallNode* function,
  62                 const std::vector<Value>& args,
  63                 BlockNode* block,
  64                 Err* err);
  65
  66 extern const char kActionForEach[];
  67 extern const char kActionForEach_HelpShort[];
  68 extern const char kActionForEach_Help[];
  69 Value RunActionForEach(Scope* scope,
  70                        const FunctionCallNode* function,
  71                        const std::vector<Value>& args,
  72                        BlockNode* block,
  73                        Err* err);
  74
  75 extern const char kAssert[];
  76 extern const char kAssert_HelpShort[];
  77 extern const char kAssert_Help[];
  78 Value RunAssert(Scope* scope,
  79                 const FunctionCallNode* function,
  80                 const std::vector<Value>& args,
  81                 Err* err);
  82
  83 extern const char kConfig[];
  84 extern const char kConfig_HelpShort[];
  85 extern const char kConfig_Help[];
  86 Value RunConfig(const FunctionCallNode* function,
  87                 const std::vector<Value>& args,
  88                 Scope* block_scope,
  89                 Err* err);
  90
  91 extern const char kCopy[];
  92 extern const char kCopy_HelpShort[];
  93 extern const char kCopy_Help[];
  94 Value RunCopy(const FunctionCallNode* function,
  95               const std::vector<Value>& args,
  96               Scope* block_scope,
  97               Err* err);
  98
  99 extern const char kDeclareArgs[];
 100 extern const char kDeclareArgs_HelpShort[];
 101 extern const char kDeclareArgs_Help[];
 102 Value RunDeclareArgs(Scope* scope,
 103                      const FunctionCallNode* function,
 104                      const std::vector<Value>& args,
 105                      BlockNode* block,
 106                      Err* err);
 107
 108 extern const char kDefined[];
 109 extern const char kDefined_HelpShort[];
 110 extern const char kDefined_Help[];
 111 Value RunDefined(Scope* scope,
 112                  const FunctionCallNode* function,
 113                  const ListNode* args_list,
 114                  Err* err);
 115
 116 extern const char kExecScript[];
 117 extern const char kExecScript_HelpShort[];
 118 extern const char kExecScript_Help[];
 119 Value RunExecScript(Scope* scope,
 120                     const FunctionCallNode* function,
 121                     const std::vector<Value>& args,
 122                     Err* err);
 123
 124 extern const char kExecutable[];
 125 extern const char kExecutable_HelpShort[];
 126 extern const char kExecutable_Help[];
 127 Value RunExecutable(Scope* scope,
 128                     const FunctionCallNode* function,
 129                     const std::vector<Value>& args,
 130                     BlockNode* block,
 131                     Err* err);
 132
 133 extern const char kForEach[];
 134 extern const char kForEach_HelpShort[];
 135 extern const char kForEach_Help[];
 136 Value RunForEach(Scope* scope,
 137                  const FunctionCallNode* function,
 138                  const ListNode* args_list,
 139                  Err* err);
 140
 141 extern const char kGetEnv[];
 142 extern const char kGetEnv_HelpShort[];
 143 extern const char kGetEnv_Help[];
 144 Value RunGetEnv(Scope* scope,
 145                 const FunctionCallNode* function,
 146                 const std::vector<Value>& args,
 147                 Err* err);
 148
 149 extern const char kGetLabelInfo[];
 150 extern const char kGetLabelInfo_HelpShort[];
 151 extern const char kGetLabelInfo_Help[];
 152 Value RunGetLabelInfo(Scope* scope,
 153                       const FunctionCallNode* function,
 154                       const std::vector<Value>& args,
 155                       Err* err);
 156
 157 extern const char kGetPathInfo[];
 158 extern const char kGetPathInfo_HelpShort[];
 159 extern const char kGetPathInfo_Help[];
 160 Value RunGetPathInfo(Scope* scope,
 161                      const FunctionCallNode* function,
 162                      const std::vector<Value>& args,
 163                      Err* err);
 164
 165 extern const char kGetTargetOutputs[];
 166 extern const char kGetTargetOutputs_HelpShort[];
 167 extern const char kGetTargetOutputs_Help[];
 168 Value RunGetTargetOutputs(Scope* scope,
 169                           const FunctionCallNode* function,
 170                           const std::vector<Value>& args,
 171                           Err* err);
 172
 173 extern const char kGroup[];
 174 extern const char kGroup_HelpShort[];
 175 extern const char kGroup_Help[];
 176 Value RunGroup(Scope* scope,
 177                const FunctionCallNode* function,
 178                const std::vector<Value>& args,
 179                BlockNode* block,
 180                Err* err);
 181
 182 extern const char kImport[];
 183 extern const char kImport_HelpShort[];
 184 extern const char kImport_Help[];
 185 Value RunImport(Scope* scope,
 186                 const FunctionCallNode* function,
 187                 const std::vector<Value>& args,
 188                 Err* err);
 189
 190 extern const char kPrint[];
 191 extern const char kPrint_HelpShort[];
 192 extern const char kPrint_Help[];
 193 Value RunPrint(Scope* scope,
 194                const FunctionCallNode* function,
 195                const std::vector<Value>& args,
 196                Err* err);
 197
 198 extern const char kProcessFileTemplate[];
 199 extern const char kProcessFileTemplate_HelpShort[];
 200 extern const char kProcessFileTemplate_Help[];
 201 Value RunProcessFileTemplate(Scope* scope,
 202                              const FunctionCallNode* function,
 203                              const std::vector<Value>& args,
 204                              Err* err);
 205
 206 extern const char kReadFile[];
 207 extern const char kReadFile_HelpShort[];
 208 extern const char kReadFile_Help[];
 209 Value RunReadFile(Scope* scope,
 210                   const FunctionCallNode* function,
 211                   const std::vector<Value>& args,
 212                   Err* err);
 213
 214 extern const char kRebasePath[];
 215 extern const char kRebasePath_HelpShort[];
 216 extern const char kRebasePath_Help[];
 217 Value RunRebasePath(Scope* scope,
 218                     const FunctionCallNode* function,
 219                     const std::vector<Value>& args,
 220                     Err* err);
 221
 222 extern const char kSetDefaults[];
 223 extern const char kSetDefaults_HelpShort[];
 224 extern const char kSetDefaults_Help[];
 225 Value RunSetDefaults(Scope* scope,
 226                      const FunctionCallNode* function,
 227                      const std::vector<Value>& args,
 228                      BlockNode* block,
 229                      Err* err);
 230
 231 extern const char kSetDefaultToolchain[];
 232 extern const char kSetDefaultToolchain_HelpShort[];
 233 extern const char kSetDefaultToolchain_Help[];
 234 Value RunSetDefaultToolchain(Scope* scope,
 235                              const FunctionCallNode* function,
 236                              const std::vector<Value>& args,
 237                              Err* err);
 238
 239 extern const char kSetSourcesAssignmentFilter[];
 240 extern const char kSetSourcesAssignmentFilter_HelpShort[];
 241 extern const char kSetSourcesAssignmentFilter_Help[];
 242 Value RunSetSourcesAssignmentFilter(Scope* scope,
 243                                     const FunctionCallNode* function,
 244                                     const std::vector<Value>& args,
 245                                     Err* err);
 246
 247 extern const char kSharedLibrary[];
 248 extern const char kSharedLibrary_HelpShort[];
 249 extern const char kSharedLibrary_Help[];
 250 Value RunSharedLibrary(Scope* scope,
 251                        const FunctionCallNode* function,
 252                        const std::vector<Value>& args,
 253                        BlockNode* block,
 254                        Err* err);
 255
 256 extern const char kSourceSet[];
 257 extern const char kSourceSet_HelpShort[];
 258 extern const char kSourceSet_Help[];
 259 Value RunSourceSet(Scope* scope,
 260                    const FunctionCallNode* function,
 261                    const std::vector<Value>& args,
 262                    BlockNode* block,
 263                    Err* err);
 264
 265 extern const char kStaticLibrary[];
 266 extern const char kStaticLibrary_HelpShort[];
 267 extern const char kStaticLibrary_Help[];
 268 Value RunStaticLibrary(Scope* scope,
 269                        const FunctionCallNode* function,
 270                        const std::vector<Value>& args,
 271                        BlockNode* block,
 272                        Err* err);
 273
 274 extern const char kTemplate[];
 275 extern const char kTemplate_HelpShort[];
 276 extern const char kTemplate_Help[];
 277 Value RunTemplate(Scope* scope,
 278                   const FunctionCallNode* function,
 279                   const std::vector<Value>& args,
 280                   BlockNode* block,
 281                   Err* err);
 282
 283 extern const char kTool[];
 284 extern const char kTool_HelpShort[];
 285 extern const char kTool_Help[];
 286 Value RunTool(Scope* scope,
 287               const FunctionCallNode* function,
 288               const std::vector<Value>& args,
 289               BlockNode* block,
 290               Err* err);
 291
 292 extern const char kToolchain[];
 293 extern const char kToolchain_HelpShort[];
 294 extern const char kToolchain_Help[];
 295 Value RunToolchain(Scope* scope,
 296                    const FunctionCallNode* function,
 297                    const std::vector<Value>& args,
 298                    BlockNode* block,
 299                    Err* err);
 300
 301 extern const char kToolchainArgs[];
 302 extern const char kToolchainArgs_HelpShort[];
 303 extern const char kToolchainArgs_Help[];
 304 Value RunToolchainArgs(Scope* scope,
 305                        const FunctionCallNode* function,
 306                        const std::vector<Value>& args,
 307                        BlockNode* block,
 308                        Err* err);
 309
 310 extern const char kWriteFile[];
 311 extern const char kWriteFile_HelpShort[];
 312 extern const char kWriteFile_Help[];
 313 Value RunWriteFile(Scope* scope,
 314                    const FunctionCallNode* function,
 315                    const std::vector<Value>& args,
 316                    Err* err);
 317
 318 // -----------------------------------------------------------------------------
 319
 320 // One function record. Only one of the given runner types will be non-null
 321 // which indicates the type of function it is.
 322 struct FunctionInfo {
 323   FunctionInfo();
 324   FunctionInfo(SelfEvaluatingArgsFunction seaf,
 325                const char* in_help_short,
 326                const char* in_help,
 327                bool in_is_target);
 328   FunctionInfo(GenericBlockFunction gbf,
 329                const char* in_help_short,
 330                const char* in_help,
 331                bool in_is_target);
 332   FunctionInfo(ExecutedBlockFunction ebf,
 333                const char* in_help_short,
 334                const char* in_help,
 335                bool in_is_target);
 336   FunctionInfo(NoBlockFunction nbf,
 337                const char* in_help_short,
 338                const char* in_help,
 339                bool in_is_target);
 340
 341   SelfEvaluatingArgsFunction self_evaluating_args_runner;
 342   GenericBlockFunction generic_block_runner;
 343   ExecutedBlockFunction executed_block_runner;
 344   NoBlockFunction no_block_runner;
 345
 346   const char* help_short;
 347   const char* help;
 348
 349   bool is_target;
 350 };
 351
 352 typedef std::map<base::StringPiece, FunctionInfo> FunctionInfoMap;
 353
 354 // Returns the mapping of all built-in functions.
 355 const FunctionInfoMap& GetFunctions();
 356
 357 // Runs the given function.
 358 Value RunFunction(Scope* scope,
 359                   const FunctionCallNode* function,
 360                   const ListNode* args_list,
 361                   BlockNode* block,  // Optional.
 362                   Err* err);
 363
 364 }  // namespace functions
 365
 366 // Helper functions -----------------------------------------------------------
 367
 368 // Verifies that the current scope is not processing an import. If it is, it
 369 // will set the error, blame the given parse node for it, and return false.
 370 bool EnsureNotProcessingImport(const ParseNode* node,
 371                                const Scope* scope,
 372                                Err* err);
 373
 374 // Like EnsureNotProcessingImport but checks for running the build config.
 375 bool EnsureNotProcessingBuildConfig(const ParseNode* node,
 376                                     const Scope* scope,
 377                                     Err* err);
 378
 379 // Sets up the |block_scope| for executing a target (or something like it).
 380 // The |scope| is the containing scope. It should have been already set as the
 381 // parent for the |block_scope| when the |block_scope| was created.
 382 //
 383 // This will set up the target defaults and set the |target_name| variable in
 384 // the block scope to the current target name, which is assumed to be the first
 385 // argument to the function.
 386 //
 387 // On success, returns true. On failure, sets the error and returns false.
 388 bool FillTargetBlockScope(const Scope* scope,
 389                           const FunctionCallNode* function,
 390                           const std::string& target_type,
 391                           const BlockNode* block,
 392                           const std::vector<Value>& args,
 393                           Scope* block_scope,
 394                           Err* err);
 395
 396 // Sets the given error to a message explaining that the function call requires
 397 // a block.
 398 void FillNeedsBlockError(const FunctionCallNode* function, Err* err);
 399
 400 // Validates that the given function call has one string argument. This is
 401 // the most common function signature, so it saves space to have this helper.
 402 // Returns false and sets the error on failure.
 403 bool EnsureSingleStringArg(const FunctionCallNode* function,
 404                            const std::vector<Value>& args,
 405                            Err* err);
 406
 407 // Returns the name of the toolchain for the given scope.
 408 const Label& ToolchainLabelForScope(const Scope* scope);
 409
 410 // Generates a label for the given scope, using the current directory and
 411 // toolchain, and the given name.
 412 Label MakeLabelForScope(const Scope* scope,
 413                         const FunctionCallNode* function,
 414                         const std::string& name);
 415
 416 #endif  // TOOLS_GN_FUNCTIONS_H_