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 *variableSpace
Declared 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)currentVariableScope
Return 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)enterVariableScope
Return 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)exitVariableScope
Return 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 *)variableName
Parameters
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 *)variableName
Parameters
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)unsetScopedVariables
Declared In
MBScopedVariables.h
– reapplyScopedVariables
Reapplies any scoped variables that were previously unset using
unsetScopedVariables
(and have not been set again since).
- (void)reapplyScopedVariables
Discussion
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