MBScopedVariables Class Reference
| Inherits from | MBFormattedDescriptionObject |
|---|---|
| Conforms to | NSCopying |
| Declared in | MBScopedVariables.h |
Overview
Provides a mechanism for maintaining scoped variable values in the
context of a particular MBVariableSpace instance.
About variable scopes
A variable scope allows the creation of a short-lived values for named Mockingbird variables.
The MBScopedVariables class provides an interface for entering and
exiting a variable scope.
When a scope is entered, an MBScopedVariables instance is associated
with the calling thread. That instance can then be used to set values for
scoped variables. When a scoped variable value is set, it is pushed
on top of the existing value (if any) in the associated MBVariableSpace.
When the scope is exited, any scoped variable values that were set are
then popped from the associated MBVariableSpace, restoring it to the
state that existed before the scope was entered.
Setting a scoped variable
To set a scoped variable, you first need an MBScopedVariables instance.
If there’s already a scope associated with the calling thread, you can
retrieve it by calling:
MBScopedVariables* scope = [MBScopedVariables currentVariableScope];
If there’s no pre-existing scope, or if you want to create a new scope that masks any existing scope, you would call:
MBScopedVariables* scope = [MBScopedVariables enterVariableScope];
Once you’ve got a scope instance, you can use the keyed subscripting notation to set a scoped variable:
NSString* userName = ... // a string set elsewhere
scope[@"user"] = userName;
The value userName is then pushed onto the Mockingbird variable stack
for the name “user”. If there is a pre-existing value for the “user”
variable, it is temporarily masked by the new value. When the scope is
exited—or when a scope’s unsetScopedVariables method is called—the “user”
variable will be popped, and the previous value will be restored.
Exiting the current scope
When you no longer need a scope that you’ve previously entered, you must call:
[MBScopedVariables exitVariableScope];
It is considered a coding error if you do not explicitly exit a scope you’ve previously entered.
For performance reasons, you should keep any scopes you create as short-lived as possible.
Threading concerns
Although a given MBScopedVariables instance is specific to the thread that
created it, the underlying MBVariableSpace manipulated by the scope is
a global resource. Therefore, values set within your scope will be visible
to all threads until your scope is exited.
Other Methods
variableSpace
Returns the MBVariableSpace instance in which the scoped variables will
be stored.
@property (nonnull, nonatomic, readonly) MBVariableSpace *variableSpaceDeclared In
MBScopedVariables.h
Thread-local scoped variables
+ currentVariableScope
Returns the MBScopedVariables instance that represents the current
variable scope associated with the calling thread.
+ (nullable instancetype)currentVariableScopeReturn Value
The current scope, or nil if there isn’t one.
Declared In
MBScopedVariables.h
+ enterVariableScope
Enters a new variable scope on the calling thread using the MBVariableSpace
associated with the current MBEnvironment.
+ (nonnull instancetype)enterVariableScopeReturn Value
A newly-created MBScopedVariables instance representing
the new scope. Until the scope is exited, code running on the
calling thread will be able to retrieve this scope through
the currentVariableScope method.
Discussion
Note: Although only the calling thread will see this scope through
the currentVariableScope method, variable values set using this
scope will be visible to all threads through the MBVariableSpace
associated with the scope.
Warning: All calls to enterVariableScope must be balanced by a
corresponding call to exitVariableScope. Failing to do this
is a coding error.
Declared In
MBScopedVariables.h
+ exitVariableScope
Exits the current variable scope–if there is one–associated with the
calling thread. Any variables set within the scope being exited will be
removed from that scope’s variableSpace, and the variable values will
return to what they were prior to entering the scope.
+ (nullable instancetype)exitVariableScopeReturn Value
The MBScopedVariables instance representing the scope that
was exited, or nil if there was no current scope at the time
of calling and therefore there was no scope to exit.
Declared In
MBScopedVariables.h
Getting & setting scoped variable values
– objectForKeyedSubscript:
Allows accessing scoped variable values using the keyed subscripting notation.
- (nullable id)objectForKeyedSubscript:(nonnull NSString *)variableNameParameters
variableName |
The name of the scoped variable whose value is to be retrieved. |
|---|
Return Value
The in-scope value of the MBML variable named variableName.
Discussion
For example, the following Objective-C code:
[MBScopedVariables currentVariableScope][@"tempVar"];
would yield the in-scope value of the Mockingbird variable named tempVar.
Declared In
MBScopedVariables.h
– setObject:forKeyedSubscript:
Allows setting a scoped variable value using the keyed subscripting notation.
- (void)setObject:(nullable id)value forKeyedSubscript:(nonnull NSString *)variableNameParameters
value |
The new value for the MBML variable. |
|---|---|
variableName |
The name of the scoped variable whose value is to be set. |
Discussion
For example, the following Objective-C code:
[MBScopedVariables currentVariableScope][@"tempVar"] = @"will go away";
would set the in-scope value of the MBML variable named tempVar to the
string “will go away”.
Warning: An NSInvalidArgumentException is raised if variableName
is nil or is not an NSString.
Declared In
MBScopedVariables.h
Unsetting & reapplying the variable scope
– unsetScopedVariables
Removes from the receiver’s variableSpace all variables set using the scope.
The values in the variableSpace will return to what they were prior to the
scope becoming active.
- (void)unsetScopedVariablesDeclared In
MBScopedVariables.h
– reapplyScopedVariables
Reapplies any scoped variables that were previously unset using
unsetScopedVariables (and have not been set again since).
- (void)reapplyScopedVariablesDiscussion
The reapplied variable values will be reflected in the receiver’s
variableSpace until the scope is exited or the receiver’s
unsetScopedVariables method is called.
Declared In
MBScopedVariables.h