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 `nil`.

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`.
`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 `variableName`.

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

`– variableIsStack:`

Determines if the variable with the given name is a stack variable.

- (BOOL)variableIsStack:(nonnull NSString *)varName

Parameters

`varName`	The name of the variable.

Return Value

YES if varName represents a stack variable; NO otherwise.

Discussion

A stack variable is one for which you can successfully issue a popVariable: request. Such a variable has had its value populated by pushVariable:value: at least one more time than a corresponding popVariable: has been issued.

Declared In

MBVariableSpace.h

`– variableStackDepth:`

Returns the stack depth of the given variable.

- (NSUInteger)variableStackDepth:(nonnull NSString *)varName

Parameters

`varName`	The name of the variable whose stack depth is sought.

Return Value

The stack depth of the variable varName. A depth of 0 (zero) indicates that the variable is not a stack variable (i.e., variableIsStack: would return NO and popVariable: would fail).

Discussion

The stack depth indicates the number of distinct values that are “hidden below” the variable’s current value. The stack depth therefore also represents the number of times popVariable: can be successfully called for the variable.

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 `nil`, the value for `key` will be removed.

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 `idx` is greater than the last index of the list, the list array will be expanded to include the new index, and any empty index slots will be filled with `NSNull`.
`val`	The new value to set at the given index. If `nil`, the value will be set as `NSNull`.

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 `nil`, this method returns `nil`.
`suffix`	The optional suffix to apply to `name`. If `nil`, this method returns `name`.

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.

MBConcreteVariableDeclarations 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 `MBVariableDeclaration` representing the variable. Note that this method ignores the `shouldDeclare` property of the variable declaration.

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 `MBMLFunction` representing the function and its implementation.

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 `MBMLFunction` is sought.

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 `userDefaultsName` of the variable to observe. Note that this is not necessarily the same as the variable name.
`observer`	The object to notify.
`action`	The method selector of `observer` to call when notifying.

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 `userDefaultsName` of the variable to stop observing.

Declared In

MBVariableSpace.h