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