MBVariableSpace Class Reference
Inherits from | MBEnvironmentLoader : NSObject |
---|---|
Conforms to | MBInstanceVendor |
Declared in | MBVariableSpace.h |
Overview
The MBVariableSpace
class is responsible for loading variable declarations
from MBML files and for maintaining the current values of named Mockingbird
variables across the lifetime of the application.
Each MBEnvironment
will have an associated MBVariableSpace
that will be
consulted when Mockingbird expressions are evaluated. When a given environment
is active, its MBVariableSpace
will provide the values when variables are
referenced.
Getting the current variable space
+ instance
Retrieves the MBVariableSpace
instance associated with the currently-active
MBEnvironment
.
+ (nullable instancetype)instance
Return Value
The current variable space.
Declared In
MBVariableSpace.h
Accessing variable values
– objectForKeyedSubscript:
Returns the current value for the variable with the given name using the keyed subscripting notation.
- (nullable id)objectForKeyedSubscript:(nonnull NSString *)variableName
Parameters
variableName |
The name of the MBML variable whose value is to be retrieved. |
---|
Return Value
The current variable value. Will return nil
if there is no
variable with the given name or if there was an error retrieving
the variable’s value.
Discussion
For example, the following Objective-C code:
NSString* addr = [MBVariableSpace instance][@"email"];
would set the value of the Objective-C string addr
to the value of the MBML
variable named email
.
Declared In
MBVariableSpace.h
– variableAsString:
Returns the current string value of the variable with the given name.
- (nullable NSString *)variableAsString:(nonnull NSString *)varName
Parameters
varName |
The name of the variable whose string value is being retrieved. |
---|
Return Value
The current string value of the variable. Will return nil
if
there is no variable with the given name or if there was an error
retrieving the variable’s value.
Discussion
If the underlying variable value is not an NSString
, the value’s
description
method will be called to convert the value into a string.
Declared In
MBVariableSpace.h
– variableAsString:defaultValue:
Returns the current string value for the variable with the given name, or a default value if there is no available variable value.
- (nullable NSString *)variableAsString:(nonnull NSString *)varName defaultValue:(nullable NSString *)def
Parameters
varName |
The name of the variable whose string value is being retrieved. |
---|---|
def |
A default value to return in cases where the method would
otherwise return |
Return Value
The current string value of the variable. Will return def
if
there is no variable with the given name or if there was an error
retrieving the variable’s value.
Discussion
If the underlying variable value is not an NSString
, the value’s
description
method will be called to convert the value into a string.
Declared In
MBVariableSpace.h
Modifying variable values
– setObject:forKeyedSubscript:
Sets a variable to the given value using the keyed subscripting notation.
- (void)setObject:(nullable id)value forKeyedSubscript:(nonnull NSString *)variableName
Parameters
value |
The value to set for the variable named |
---|---|
variableName |
The name of the variable whose value is to be set. If the name represents a read-only variable, the call will be ignored and an error will be logged to the console. |
Discussion
For example, the following Objective-C code:
[MBVariableSpace instance][@"title"] = @"MBML";
would set the MBML variable named title
to the string “MBML
”.
Warning: An NSInvalidArgumentException
is raised if variableName
is nil
or is not an NSString
.
Declared In
MBVariableSpace.h
– pushVariable:value:
Pushes a new value onto the stack for the variable with the given name.
- (void)pushVariable:(nonnull NSString *)variableName value:(nullable id)value
Parameters
variableName |
The name of the variable whose value is to be set. If the name represents a read-only variable, the call will be ignored and an error will be logged to the console. |
---|---|
value |
The value to set for the variable named |
Declared In
MBVariableSpace.h
– popVariable:
Pops the current value from the stack for the variable with the given name.
(The value of the variable prior to the previous call to pushVariable:value:
will be restored.)
- (nullable id)popVariable:(nonnull NSString *)varName
Parameters
varName |
The name of the variable whose value is to be set. If the name represents a read-only variable, the call will be ignored and an error will be logged to the console. |
---|
Return Value
The value of the variable varName
that was popped from the stack.
If there were no stack values for the variable, nil
will be
returned.
Discussion
If there are no stack values for the variable, an error will be logged to the console.
Declared In
MBVariableSpace.h
– setMapVariable:mapKey:value:
Sets the value of a given key for the type="map"
variable with the specified
name. (This method will also operate on any variable whose value is of type
NSDictionary
.)
- (void)setMapVariable:(nonnull NSString *)varName mapKey:(nonnull NSString *)key value:(nullable id)val
Parameters
varName |
The name of the map variable whose key-value is being set. If the name represents a read-only variable, the call will be ignored and an error will be logged to the console. |
---|---|
key |
The map key whose value is being set. |
val |
The new value for the given key. If |
Declared In
MBVariableSpace.h
– setListVariable:listIndex:value:
Sets the value of a given key for the type="list"
variable with the specified
name. (This method will also operate on any variable whose value is of type
NSArray
.)
- (void)setListVariable:(nonnull NSString *)varName listIndex:(NSUInteger)idx value:(nullable id)val
Parameters
varName |
The name of the list variable whose index-value is being set. If the name represents a read-only variable, the call will be ignored and an error will be logged to the console. |
---|---|
idx |
The list index whose value is being set. If |
val |
The new value to set at the given index. If |
Declared In
MBVariableSpace.h
– unsetVariable:
Removes the current value of the variable with the specified name. Values on the variable stack will not be affected.
- (void)unsetVariable:(nonnull NSString *)varName
Parameters
varName |
The name of the variable whose value is to be unset. If the name represents a read-only variable, the call will be ignored and an error will be logged to the console. |
---|
Declared In
MBVariableSpace.h
Constructing variable-related names
+ name:withSuffix:
Constructs a string for a variable-related name with the given suffix.
+ (nullable NSString *)name:(nullable NSString *)name withSuffix:(nullable NSString *)suffix
Parameters
name |
The name to use for the root of the returned string. If
|
---|---|
suffix |
The optional suffix to apply to |
Return Value
If name
and suffix
are both non-nil
, the concatenation of
name
, “:
” and suffix
is returned. Otherwise, the value of the
name
parameter is returned.
Discussion
Calling this method with the name “Foo
” and the suffix “willBar
” would
return the string “Foo:willBar
”.
Declared In
MBVariableSpace.h
Accessing variable information
– isReadOnlyVariable:
Determines whether the variable with the given name is a read-only variable.
- (BOOL)isReadOnlyVariable:(nonnull NSString *)varName
Parameters
varName |
The name of the variable. |
---|
Return Value
YES
if the variable named varName
is read-only; NO
otherwise.
Discussion
Read-only variables are marked as such in MBML or when they are declared
programmatically via declareVariable:
.
Certain types of variable declarations—such as those represented by
MBSingletonVariableDeclaration
and MBDynamicVariableDeclaration
—are always
read-only.
MBConcreteVariableDeclaration
s declared in MBML with a mutable="F"
attribute are read-only.
Otherwise, variables are not considered read-only.
Note that the read-only concept only applies to whether or not the
MBVariableSpace
will allow you to change the value through its interface.
In this way, even immutable objects such as NSArray
may be considered
read/write as far as the Mockingbird Data Environment goes.
Conversely, a NSMutableDictionary
, for example, may be declared as a
read-only Mockingbird variable, but the dictionary can still be mutated
directly.
Declared In
MBVariableSpace.h
Accessing variable declarations
– declareVariable:
Programmatically declares a variable.
- (BOOL)declareVariable:(nonnull MBVariableDeclaration *)declaration
Parameters
declaration |
An |
---|
Return Value
YES
if the variable represented by declaration
was successfully
declared; NO
if an error occured.
Declared In
MBVariableSpace.h
– declarationForVariable:
Returns the MBVariableDeclaration
for the variable with the given name.
- (nullable MBVariableDeclaration *)declarationForVariable:(nonnull NSString *)varName
Parameters
varName |
The name of the variable whose declaration is being retrieved. |
---|
Return Value
The declaration for varName
, or nil
if no declaration exists.
Discussion
Note that not all variables will have explicit declarations; only variables
declared in MBML or created programmatically using declareVariable:
will
have an associated MBVariableDeclaration
. Undeclared variables can be
created implicitly by being set directly using keyed subscripting and
other methods.
Declared In
MBVariableSpace.h
Accessing MBML functions
– declareFunction:
Programmatically declares an MBML function.
- (BOOL)declareFunction:(nonnull MBMLFunction *)function
Parameters
function |
An |
---|
Return Value
YES
if function
was successfully declared; NO
if an error
occurred.
Declared In
MBVariableSpace.h
– functionNames
Returns the names of the currently-declared MBML functions.
- (nonnull NSArray *)functionNames
Return Value
An NSArray
containing the names of the declared MBML functions.
Declared In
MBVariableSpace.h
– functionWithName:
Returns the MBMLFunction
associated with the given name.
- (nullable MBMLFunction *)functionWithName:(nonnull NSString *)name
Parameters
name |
The name of the function whose |
---|
Return Value
The MBMLFunction
, or nil
if there is no function declared having
the given name.
Declared In
MBVariableSpace.h
Observing changes to variables bound to `NSUserDefaults`
– addObserverForUserDefault:target:action:
Adds an observer to be notified of changes to the value of the Mockingbird
variable with the given NSUserDefaults
key name.
- (void)addObserverForUserDefault:(nonnull NSString *)userDefaultsName target:(nonnull id)observer action:(nonnull SEL)action
Parameters
userDefaultsName |
The |
---|---|
observer |
The object to notify. |
action |
The method selector of |
Declared In
MBVariableSpace.h
– removeObserver:forUserDefault:
Stops an observer from being notified of changes to the value of the
Mockingbird variable with the given NSUserDefaults
key name.
- (void)removeObserver:(nonnull id)observer forUserDefault:(nonnull NSString *)userDefaultsName
Parameters
observer |
The observer to remove. |
---|---|
userDefaultsName |
The |
Declared In
MBVariableSpace.h