Allow creation and modification of scopes in GN.

tools/gn/scope.h

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef TOOLS_GN_SCOPE_H_
 #define TOOLS_GN_SCOPE_H_
 
 #include <map>
 #include <memory>
 #include <set>
@@ skipping 27 matching lines @@
 // many invocations. A const containing scope, however, prevents us from
 // marking variables "used" which prevents us from issuing errors on unused
 // variables. So you should use a non-const containing scope whenever possible.
 class Scope {
  public:
   typedef base::hash_map<base::StringPiece, Value, base::StringPieceHash>
       KeyValueMap;
   // Holds an owning list of Items.
   typedef ScopedVector<Item> ItemVector;
 
+  // A flag to indicate whether a function should recurse into nested scopes,
+  // or only operate on the current scope.
+  enum SearchNested {
+    SEARCH_NESTED,
+    SEARCH_CURRENT
+  };
+
   // Allows code to provide values for built-in variables. This class will
   // automatically register itself on construction and deregister itself on
   // destruction.
   class ProgrammaticProvider {
    public:
     explicit ProgrammaticProvider(Scope* scope) : scope_(scope) {
       scope_->AddProvider(this);
     }
     virtual ~ProgrammaticProvider();
 
@@ skipping 49 matching lines @@
 
   // See the const_/mutable_containing_ var declaraions below. Yes, it's a
   // bit weird that we can have a const pointer to the "mutable" one.
   Scope* mutable_containing() { return mutable_containing_; }
   const Scope* mutable_containing() const { return mutable_containing_; }
   const Scope* const_containing() const { return const_containing_; }
   const Scope* containing() const {
     return mutable_containing_ ? mutable_containing_ : const_containing_;
   }
 
+  // Clears any references to containing scopes. This scope will now be
+  // self-sufficient.
+  void DetachFromContaining();
+
   // Returns NULL if there's no such value.
   //
   // counts_as_used should be set if the variable is being read in a way that
   // should count for unused variable checking.
   const Value* GetValue(const base::StringPiece& ident,
                         bool counts_as_used);
   const Value* GetValue(const base::StringPiece& ident) const;
 
+  // If the value exists in the current scope, destrictively moves it into the
+  // return value. If it exists in a containing scope, copies it.
+  //
+  // This is for implementing modify-write operations where we want to read
+  // the existing value and plan to immediately overwrite it. If the value is
+  // in a containing scope, we never want to touch it (all writes go to the
+  // current scope), but if it's in the current scope, avoid the copy since it
+  // will be overwritten anyway.
+  //Value DestructiveMoveOut(const base::StringPiece& ident);
+
   // Returns the requested value as a mutable one if possible. If the value
   // is not found in a mutable scope, then returns null. Note that the value
   // could still exist in a const scope, so GetValue() could still return
   // non-null in this case.
   //
   // Say you have a local scope that then refers to the const root scope from
   // the master build config. You can't change the values from the master
   // build config (it's read-only so it can be read from multiple threads
   // without locking). Read-only operations would work on values from the root
   // scope, but write operations would only work on values in the derived
   // scope(s).
   //
   // Be careful when calling this. It's not normally correct to modify values,
   // but you should instead do a new Set each time.
   //
   // Consider this code:
   //   a = 5
   //    {
   //       a = 6
   //    }
   // The 6 should get set on the nested scope rather than modify the value
   // in the outer one.
-  Value* GetMutableValue(const base::StringPiece& ident, bool counts_as_used);
-
-  // Same as GetValue, but if the value exists in a parent scope, we'll copy
-  // it to the current scope. If the return value is non-null, the value is
-  // guaranteed to be set in the current scope. Generatlly this will be used
-  // if the calling code is planning on modifying the value in-place.
-  //
-  // Since this is used when doing read-modifies, we never count this access
-  // as reading the variable, since we assume it will be written to.
-  Value* GetValueForcedToCurrentScope(const base::StringPiece& ident,
-                                      const ParseNode* set_node);
+  Value* GetMutableValue(const base::StringPiece& ident,
+                         SearchNested search_mode,
+                         bool counts_as_used);
 
   // Returns the StringPiece used to identify the value. This string piece
   // will have the same contents as "ident" passed in, but may point to a
   // different underlying buffer. This is useful because this StringPiece is
   // static and won't be deleted for the life of the program, so it can be used
   // as keys in places that may outlive a temporary. It will return an empty
   // string for programmatic and nonexistant values.
   base::StringPiece GetStorageKey(const base::StringPiece& ident) const;
 
   // The set_node indicates the statement that caused the set, for displaying
   // errors later. Returns a pointer to the value in the current scope (a copy
   // is made for storage).
   Value* SetValue(const base::StringPiece& ident,
-                  const Value& v,
+                  Value v,
                   const ParseNode* set_node);
 
   // Removes the value with the given identifier if it exists on the current
   // scope. This does not search recursive scopes. Does nothing if not found.
   void RemoveIdentifier(const base::StringPiece& ident);
 
   // Removes from this scope all identifiers and templates that are considered
   // private.
   void RemovePrivateIdentifiers();
 
@@ skipping 176 matching lines @@
 
   typedef std::set<ProgrammaticProvider*> ProviderSet;
   ProviderSet programmatic_providers_;
 
   SourceDir source_dir_;
 
   DISALLOW_COPY_AND_ASSIGN(Scope);
 };
 
 #endif  // TOOLS_GN_SCOPE_H_