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.
5 #ifndef TOOLS_GN_SCOPE_H_
6 #define TOOLS_GN_SCOPE_H_
11 #include "base/basictypes.h"
12 #include "base/containers/hash_tables.h"
13 #include "base/memory/scoped_ptr.h"
14 #include "tools/gn/err.h"
15 #include "tools/gn/pattern.h"
16 #include "tools/gn/source_dir.h"
17 #include "tools/gn/value.h"
19 class FunctionCallNode;
25 // Scope for the script execution.
27 // Scopes are nested. Writing goes into the toplevel scope, reading checks
28 // values resursively down the stack until a match is found or there are no
29 // more containing scopes.
31 // A containing scope can be const or non-const. The const containing scope is
32 // used primarily to refer to the master build config which is shared across
33 // many invocations. A const containing scope, however, prevents us from
34 // marking variables "used" which prevents us from issuing errors on unused
35 // variables. So you should use a non-const containing scope whenever possible.
38 typedef base::hash_map<base::StringPiece, Value> KeyValueMap;
40 // Allows code to provide values for built-in variables. This class will
41 // automatically register itself on construction and deregister itself on
43 class ProgrammaticProvider {
45 ProgrammaticProvider(Scope* scope) : scope_(scope) {
46 scope_->AddProvider(this);
48 ~ProgrammaticProvider() {
49 scope_->RemoveProvider(this);
52 // Returns a non-null value if the given value can be programmatically
53 // generated, or NULL if there is none.
54 virtual const Value* GetProgrammaticValue(
55 const base::StringPiece& ident) = 0;
61 // Creates an empty toplevel scope.
62 Scope(const Settings* settings);
64 // Creates a dependent scope.
66 Scope(const Scope* parent);
70 const Settings* settings() const { return settings_; }
72 // See the const_/mutable_containing_ var declaraions below. Yes, it's a
73 // bit weird that we can have a const pointer to the "mutable" one.
74 Scope* mutable_containing() { return mutable_containing_; }
75 const Scope* mutable_containing() const { return mutable_containing_; }
76 const Scope* const_containing() const { return const_containing_; }
77 const Scope* containing() const {
78 return mutable_containing_ ? mutable_containing_ : const_containing_;
81 // Returns NULL if there's no such value.
83 // counts_as_used should be set if the variable is being read in a way that
84 // should count for unused variable checking.
85 const Value* GetValue(const base::StringPiece& ident,
87 const Value* GetValue(const base::StringPiece& ident) const;
89 // Same as GetValue, but if the value exists in a parent scope, we'll copy
90 // it to the current scope. If the return value is non-null, the value is
91 // guaranteed to be set in the current scope. Generatlly this will be used
92 // if the calling code is planning on modifying the value in-place.
94 // Since this is used when doing read-modifies, we never count this access
95 // as reading the variable, since we assume it will be written to.
96 Value* GetValueForcedToCurrentScope(const base::StringPiece& ident,
97 const ParseNode* set_node);
99 // The set_node indicates the statement that caused the set, for displaying
100 // errors later. Returns a pointer to the value in the current scope (a copy
101 // is made for storage).
102 Value* SetValue(const base::StringPiece& ident,
104 const ParseNode* set_node);
106 // Templates associated with this scope. A template can only be set once, so
107 // AddTemplate will fail and return NULL if a rule with that name already
108 // exists. GetTemplate returns NULL if the rule doesn't exist, and it will
109 // check all containing scoped rescursively.
110 bool AddTemplate(const std::string& name, const FunctionCallNode* decl);
111 const FunctionCallNode* GetTemplate(const std::string& name) const;
113 // Marks the given identifier as (un)used in the current scope.
114 void MarkUsed(const base::StringPiece& ident);
115 void MarkUnused(const base::StringPiece& ident);
117 // Checks to see if the scope has a var set that hasn't been used. This is
118 // called before replacing the var with a different one. It does not check
119 // containing scopes.
121 // If the identifier is present but hasnn't been used, return true.
122 bool IsSetButUnused(const base::StringPiece& ident) const;
124 // Checks the scope to see if any values were set but not used, and fills in
125 // the error and returns false if they were.
126 bool CheckForUnusedVars(Err* err) const;
128 // Returns all values set in the current scope, without going to the parent
130 void GetCurrentScopeValues(KeyValueMap* output) const;
132 // Copies this scope's values into the destination. Values from the
133 // containing scope(s) (normally shadowed into the current one) will not be
134 // copied, neither will the reference to the containing scope (this is why
135 // it's "non-recursive").
137 // It is an error to merge a variable into a scope that already has something
138 // with that name in scope (meaning in that scope or in any of its containing
139 // scopes). If this happens, the error will be set and the function will
142 // This is used in different contexts. When generating the error, the given
143 // parse node will be blamed, and the given desc will be used to describe
144 // the operation that doesn't support doing this. For example, desc_for_err
145 // would be "import" when doing an import, and the error string would say
146 // something like "The import contains...".
147 bool NonRecursiveMergeTo(Scope* dest,
148 const ParseNode* node_for_err,
149 const char* desc_for_err,
152 // Makes an empty scope with the given name. Returns NULL if the name is
154 Scope* MakeTargetDefaults(const std::string& target_type);
156 // Gets the scope associated with the given target name, or null if it hasn't
158 const Scope* GetTargetDefaults(const std::string& target_type) const;
160 // Filter to apply when the sources variable is assigned. May return NULL.
161 const PatternList* GetSourcesAssignmentFilter() const;
162 void set_sources_assignment_filter(
163 scoped_ptr<PatternList> f) {
164 sources_assignment_filter_ = f.Pass();
167 // Indicates if we're currently processing the build configuration file.
168 // This is true when processing the config file for any toolchain. See also
169 // *ProcessingDefaultBuildConfig() below.
171 // To set or clear the flag, it must currently be in the opposite state in
172 // the current scope. Note that querying the state of the flag recursively
173 // checks all containing scopes until it reaches the top or finds the flag
175 void SetProcessingBuildConfig();
176 void ClearProcessingBuildConfig();
177 bool IsProcessingBuildConfig() const;
179 // Indicates we're currently processing the default toolchain's build
180 // configuration file.
181 void SetProcessingDefaultBuildConfig();
182 void ClearProcessingDefaultBuildConfig();
183 bool IsProcessingDefaultBuildConfig() const;
185 // Indicates if we're currently processing an import file.
187 // See SetProcessingBaseConfig for how flags work.
188 void SetProcessingImport();
189 void ClearProcessingImport();
190 bool IsProcessingImport() const;
192 // The source directory associated with this scope. This will check embedded
193 // scopes until it finds a nonempty source directory. This will default to
194 // an empty dir if no containing scope has a source dir set.
195 const SourceDir& GetSourceDir() const;
196 void set_source_dir(const SourceDir& d) { source_dir_ = d; }
198 // Properties are opaque pointers that code can use to set state on a Scope
199 // that it can retrieve later.
201 // The key should be a pointer to some use-case-specific object (to avoid
202 // collisions, otherwise it doesn't matter). Memory management is up to the
203 // setter. Setting the value to NULL will delete the property.
205 // Getting a property recursively searches all scopes, and the optional
206 // |found_on_scope| variable will be filled with the actual scope containing
207 // the key (if the pointer is non-NULL).
208 void SetProperty(const void* key, void* value);
209 void* GetProperty(const void* key, const Scope** found_on_scope) const;
212 friend class ProgrammaticProvider;
215 Record() : used(false) {}
216 Record(const Value& v) : used(false), value(v) {}
218 bool used; // Set to true when the variable is used.
222 void AddProvider(ProgrammaticProvider* p);
223 void RemoveProvider(ProgrammaticProvider* p);
225 // Scopes can have no containing scope (both null), a mutable containing
226 // scope, or a const containing scope. The reason is that when we're doing
227 // a new target, we want to refer to the base_config scope which will be read
228 // by multiple threads at the same time, so we REALLY want it to be const.
229 // When you jsut do a nested {}, however, we sometimes want to be able to
230 // change things (especially marking unused vars).
231 const Scope* const_containing_;
232 Scope* mutable_containing_;
234 const Settings* settings_;
236 // Bits set for different modes. See the flag definitions in the .cc file
238 unsigned mode_flags_;
240 typedef base::hash_map<base::StringPiece, Record> RecordMap;
243 // Owning pointers. Note that this can't use string pieces since the names
244 // are constructed from Values which might be deallocated before this goes
246 typedef base::hash_map<std::string, Scope*> NamedScopeMap;
247 NamedScopeMap target_defaults_;
249 // Null indicates not set and that we should fallback to the containing
251 scoped_ptr<PatternList> sources_assignment_filter_;
253 // Non-owning pointers, the function calls are owned by the input file which
254 // should be kept around by the input file manager.
255 typedef std::map<std::string, const FunctionCallNode*> TemplateMap;
256 TemplateMap templates_;
258 // Opaque pointers. See SetProperty() above.
259 typedef std::map<const void*, void*> PropertyMap;
260 PropertyMap properties_;
262 typedef std::set<ProgrammaticProvider*> ProviderSet;
263 ProviderSet programmatic_providers_;
265 SourceDir source_dir_;
267 DISALLOW_COPY_AND_ASSIGN(Scope);
270 #endif // TOOLS_GN_SCOPE_H_