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 kGetEnv[];
 125 extern const char kGetEnv_Help[];
 126 Value RunGetEnv(Scope* scope,
 127                 const FunctionCallNode* function,
 128                 const std::vector<Value>& args,
 129                 Err* err);
 130
 131 extern const char kGroup[];
 132 extern const char kGroup_Help[];
 133 Value RunGroup(Scope* scope,
 134                const FunctionCallNode* function,
 135                const std::vector<Value>& args,
 136                BlockNode* block,
 137                Err* err);
 138
 139 extern const char kImport[];
 140 extern const char kImport_Help[];
 141 Value RunImport(Scope* scope,
 142                 const FunctionCallNode* function,
 143                 const std::vector<Value>& args,
 144                 Err* err);
 145
 146 extern const char kPrint[];
 147 extern const char kPrint_Help[];
 148 Value RunPrint(Scope* scope,
 149                const FunctionCallNode* function,
 150                const std::vector<Value>& args,
 151                Err* err);
 152
 153 extern const char kProcessFileTemplate[];
 154 extern const char kProcessFileTemplate_Help[];
 155 Value RunProcessFileTemplate(Scope* scope,
 156                              const FunctionCallNode* function,
 157                              const std::vector<Value>& args,
 158                              Err* err);
 159
 160 extern const char kReadFile[];
 161 extern const char kReadFile_Help[];
 162 Value RunReadFile(Scope* scope,
 163                   const FunctionCallNode* function,
 164                   const std::vector<Value>& args,
 165                   Err* err);
 166
 167 extern const char kRebasePath[];
 168 extern const char kRebasePath_Help[];
 169 Value RunRebasePath(Scope* scope,
 170                     const FunctionCallNode* function,
 171                     const std::vector<Value>& args,
 172                     Err* err);
 173
 174 extern const char kSetDefaults[];
 175 extern const char kSetDefaults_Help[];
 176 Value RunSetDefaults(Scope* scope,
 177                      const FunctionCallNode* function,
 178                      const std::vector<Value>& args,
 179                      BlockNode* block,
 180                      Err* err);
 181
 182 extern const char kSetDefaultToolchain[];
 183 extern const char kSetDefaultToolchain_Help[];
 184 Value RunSetDefaultToolchain(Scope* scope,
 185                              const FunctionCallNode* function,
 186                              const std::vector<Value>& args,
 187                              Err* err);
 188
 189 extern const char kSetSourcesAssignmentFilter[];
 190 extern const char kSetSourcesAssignmentFilter_Help[];
 191 Value RunSetSourcesAssignmentFilter(Scope* scope,
 192                                     const FunctionCallNode* function,
 193                                     const std::vector<Value>& args,
 194                                     Err* err);
 195
 196 extern const char kSharedLibrary[];
 197 extern const char kSharedLibrary_Help[];
 198 Value RunSharedLibrary(Scope* scope,
 199                        const FunctionCallNode* function,
 200                        const std::vector<Value>& args,
 201                        BlockNode* block,
 202                        Err* err);
 203
 204 extern const char kSourceSet[];
 205 extern const char kSourceSet_Help[];
 206 Value RunSourceSet(Scope* scope,
 207                    const FunctionCallNode* function,
 208                    const std::vector<Value>& args,
 209                    BlockNode* block,
 210                    Err* err);
 211
 212 extern const char kStaticLibrary[];
 213 extern const char kStaticLibrary_Help[];
 214 Value RunStaticLibrary(Scope* scope,
 215                        const FunctionCallNode* function,
 216                        const std::vector<Value>& args,
 217                        BlockNode* block,
 218                        Err* err);
 219
 220 extern const char kTemplate[];
 221 extern const char kTemplate_Help[];
 222 Value RunTemplate(Scope* scope,
 223                   const FunctionCallNode* function,
 224                   const std::vector<Value>& args,
 225                   BlockNode* block,
 226                   Err* err);
 227
 228 extern const char kTest[];
 229 extern const char kTest_Help[];
 230 Value RunTest(Scope* scope,
 231               const FunctionCallNode* function,
 232               const std::vector<Value>& args,
 233               BlockNode* block,
 234               Err* err);
 235
 236 extern const char kTool[];
 237 extern const char kTool_Help[];
 238 Value RunTool(Scope* scope,
 239               const FunctionCallNode* function,
 240               const std::vector<Value>& args,
 241               BlockNode* block,
 242               Err* err);
 243
 244 extern const char kToolchain[];
 245 extern const char kToolchain_Help[];
 246 Value RunToolchain(Scope* scope,
 247                    const FunctionCallNode* function,
 248                    const std::vector<Value>& args,
 249                    BlockNode* block,
 250                    Err* err);
 251
 252 extern const char kToolchainArgs[];
 253 extern const char kToolchainArgs_Help[];
 254 Value RunToolchainArgs(Scope* scope,
 255                        const FunctionCallNode* function,
 256                        const std::vector<Value>& args,
 257                        BlockNode* block,
 258                        Err* err);
 259
 260 extern const char kWriteFile[];
 261 extern const char kWriteFile_Help[];
 262 Value RunWriteFile(Scope* scope,
 263                    const FunctionCallNode* function,
 264                    const std::vector<Value>& args,
 265                    Err* err);
 266
 267 // -----------------------------------------------------------------------------
 268
 269 // One function record. Only one of the given runner types will be non-null
 270 // which indicates the type of function it is.
 271 struct FunctionInfo {
 272   FunctionInfo();
 273   FunctionInfo(SelfEvaluatingArgsFunction seaf, const char* in_help);
 274   FunctionInfo(GenericBlockFunction gbf, const char* in_help);
 275   FunctionInfo(ExecutedBlockFunction ebf, const char* in_help);
 276   FunctionInfo(NoBlockFunction nbf, const char* in_help);
 277
 278   SelfEvaluatingArgsFunction self_evaluating_args_runner;
 279   GenericBlockFunction generic_block_runner;
 280   ExecutedBlockFunction executed_block_runner;
 281   NoBlockFunction no_block_runner;
 282
 283   const char* help;
 284 };
 285
 286 typedef base::hash_map<base::StringPiece, FunctionInfo> FunctionInfoMap;
 287
 288 // Returns the mapping of all built-in functions.
 289 const FunctionInfoMap& GetFunctions();
 290
 291 // Runs the given function.
 292 Value RunFunction(Scope* scope,
 293                   const FunctionCallNode* function,
 294                   const ListNode* args_list,
 295                   BlockNode* block,  // Optional.
 296                   Err* err);
 297
 298 }  // namespace functions
 299
 300 // Helper functions -----------------------------------------------------------
 301
 302 // Verifies that the current scope is not processing an import. If it is, it
 303 // will set the error, blame the given parse node for it, and return false.
 304 bool EnsureNotProcessingImport(const ParseNode* node,
 305                                const Scope* scope,
 306                                Err* err);
 307
 308 // Like EnsureNotProcessingImport but checks for running the build config.
 309 bool EnsureNotProcessingBuildConfig(const ParseNode* node,
 310                                     const Scope* scope,
 311                                     Err* err);
 312
 313 // Sets up the |block_scope| for executing a target (or something like it).
 314 // The |scope| is the containing scope. It should have been already set as the
 315 // parent for the |block_scope| when the |block_scope| was created.
 316 //
 317 // This will set up the target defaults and set the |target_name| variable in
 318 // the block scope to the current target name, which is assumed to be the first
 319 // argument to the function.
 320 //
 321 // On success, returns true. On failure, sets the error and returns false.
 322 bool FillTargetBlockScope(const Scope* scope,
 323                           const FunctionCallNode* function,
 324                           const std::string& target_type,
 325                           const BlockNode* block,
 326                           const std::vector<Value>& args,
 327                           Scope* block_scope,
 328                           Err* err);
 329
 330 // Sets the given error to a message explaining that the function call requires
 331 // a block.
 332 void FillNeedsBlockError(const FunctionCallNode* function, Err* err);
 333
 334 // Validates that the given function call has one string argument. This is
 335 // the most common function signature, so it saves space to have this helper.
 336 // Returns false and sets the error on failure.
 337 bool EnsureSingleStringArg(const FunctionCallNode* function,
 338                            const std::vector<Value>& args,
 339                            Err* err);
 340
 341 // Returns the name of the toolchain for the given scope.
 342 const Label& ToolchainLabelForScope(const Scope* scope);
 343
 344 // Generates a label for the given scope, using the current directory and
 345 // toolchain, and the given name.
 346 Label MakeLabelForScope(const Scope* scope,
 347                         const FunctionCallNode* function,
 348                         const std::string& name);
 349
 350 #endif  // TOOLS_GN_FUNCTIONS_H_