MBEnvironment Class Reference
Inherits from | MBDataModel : MBFormattedDescriptionObject |
---|---|
Conforms to | MBInstanceVendor |
Declared in | MBEnvironment.h |
Overview
The MBEnvironment
class contains the state of the Mockingbird Data
Environment.
Typically, when an application starts, you would load an MBEnvironment
using the loadDefaultEnvironment
class method or one of the
loadFromManifest
variants.
Once an environment has been loaded, you can store data in the
MBVariableSpace
associated with the environment and reference that
data with Mockingbird expressions using the MBExpression
class.
Getting the current environment
+ instance
Retrieves the MBEnvironment
instance representing the currently-active
environment.
+ (nullable instancetype)instance
Return Value
The currently-active environment.
Declared In
MBEnvironment.h
Managing the current environment
+ setEnvironment:
Sets the active MBEnvironment
instance. The active environment supplies
the MBVariableSpace
instance used to evaluate expressions by default.
+ (nullable instancetype)setEnvironment:(nullable MBEnvironment *)env
Parameters
env |
The |
---|
Return Value
The previously-active MBEnvironment
instance, if any.
Declared In
MBEnvironment.h
+ pushEnvironment:
Sets the active MBEnvironment
instance by pushing a new environment
onto the environment stack.
+ (void)pushEnvironment:(nonnull MBEnvironment *)env
Parameters
env |
The |
---|
Declared In
MBEnvironment.h
+ popEnvironment
Sets the active MBEnvironment
instance by popping it from the environment
stack.
+ (nonnull instancetype)popEnvironment
Return Value
The newly-active environment.
Discussion
An NSException
will be raised if the environment stack is empty.
Declared In
MBEnvironment.h
+ peekEnvironment
Returns (but does not remove) the MBEnvironment
instance at the top of the
environment stack. This is the environment that would become active if
popEnvironment
were called.
+ (nullable instancetype)peekEnvironment
Return Value
The environment at the top of the environment stack, or nil
if
there is nothing in the stack.
Declared In
MBEnvironment.h
Loading the Mockingbird environment
+ loadDefaultEnvironment
Loads a new default environment, bypassing any manifest.xml
file that might
exist in the application’s resources. The default environment is the
environment that exists before any manifest file is processed.
+ (nullable instancetype)loadDefaultEnvironment
Return Value
The newly-loaded, now-active MBEnvironment
instance, or nil
if the environment could not be loaded.
Discussion
If loading is successful, the newly-loaded environment will become the active environment.
Declared In
MBEnvironment.h
+ loadFromManifest
Loads a new environment by processing the manifest.xml
file found in the
application’s resources.
+ (nullable instancetype)loadFromManifest
Return Value
The newly-loaded, now-active MBEnvironment
instance, or nil
if the environment could not be loaded.
Discussion
If loading is successful, the newly-loaded environment will become the active environment.
Declared In
MBEnvironment.h
+ loadFromManifestWithSearchDirectory:
Loads a new environment by processing the manifest.xml
file found in the
specified search directory or in the application’s resources.
+ (nullable instancetype)loadFromManifestWithSearchDirectory:(nonnull NSString *)dirPath
Parameters
dirPath |
The path of a directory that will be searched when
trying to locate the manifest and other MBML files. This directory
will be the first one searched when MBML files are referenced. If
a given file doesn’t exist in |
---|
Return Value
The newly-loaded, now-active MBEnvironment
instance, or nil
if the environment could not be loaded.
Discussion
If loading is successful, the newly-loaded environment will become the active environment.
Declared In
MBEnvironment.h
+ loadFromManifestFile:
Loads a new environment by processing the manifest file with the given name found in the application’s resources.
+ (nullable instancetype)loadFromManifestFile:(nonnull NSString *)manifestName
Parameters
manifestName |
The name of the manifest file. |
---|
Return Value
The newly-loaded, now-active MBEnvironment
instance, or nil
if the environment could not be loaded.
Discussion
If loading is successful, the newly-loaded environment will become the active environment.
Declared In
MBEnvironment.h
+ loadFromManifestFile:withSearchDirectory:
Loads a new environment by processing the manifest file with the given name found in the specified search directory or in the application’s resources.
+ (nonnull instancetype)loadFromManifestFile:(nonnull NSString *)manifestName withSearchDirectory:(nullable NSString *)dirPath
Parameters
manifestName |
The name of the manifest file. |
---|---|
dirPath |
The path of a directory that will be searched when
trying to locate the manifest and other MBML files. This directory
will be the first one searched when MBML files are referenced. If
a given file doesn’t exist in |
Return Value
The newly-loaded, now-active MBEnvironment
instance, or nil
if the environment could not be loaded.
Discussion
If loading is successful, the newly-loaded environment will become the active environment.
Declared In
MBEnvironment.h
+ loadFromManifestWithSearchDirectories:
Loads a new environment by processing the manifest.xml
file found in the
specified search directories or in the application’s resources.
+ (nullable instancetype)loadFromManifestWithSearchDirectories:(nullable NSArray *)dirPaths
Parameters
dirPaths |
An array containing the paths of directories that will be
searched when trying to locate the manifest and other MBML files.
These directories will be searched first (and in the order specified
by |
---|
Return Value
The newly-loaded, now-active MBEnvironment
instance, or nil
if the environment could not be loaded.
Discussion
If loading is successful, the newly-loaded environment will become the active environment.
Declared In
MBEnvironment.h
+ loadFromManifestFile:withSearchDirectories:
Loads a new environment by processing the manifest file with the given name found in the specified search directories or in the application’s resources.
+ (nullable instancetype)loadFromManifestFile:(nullable NSString *)manifestName withSearchDirectories:(nullable NSArray *)dirPaths
Parameters
manifestName |
The name of the manifest file. |
---|---|
dirPaths |
An array containing the paths of directories that will be
searched when trying to locate the manifest and other MBML files.
These directories will be searched first (and in the order specified
by |
Return Value
The newly-loaded, now-active MBEnvironment
instance, or nil
if the environment could not be loaded.
Discussion
If loading is successful, the newly-loaded environment will become the active environment.
Declared In
MBEnvironment.h
MBML loading
– loadMBMLFile:
Attempts to load the specified MBML file.
- (BOOL)loadMBMLFile:(nonnull NSString *)fileName
Parameters
fileName |
The name of the MBML file to load. Note that this is not a path name. MBML file loading follows a specific search order that allows files to reference each other by name without knowing precisely where they’re located. |
---|
Return Value
YES
if fileName
was loaded successfully; NO
otherwise.
Declared In
MBEnvironment.h
Controlling where resources are found
+ addResourceSearchBundle:
Adds the specified bundle as one that will be consulted whenever an environment attempts to find a resource such as an MBML file.
+ (void)addResourceSearchBundle:(nonnull NSBundle *)bundle
Parameters
bundle |
An |
---|
Declared In
MBEnvironment.h
+ resourceSearchBundles
Returns the NSBundle
instances that will be consulted whenever an
environment attempts to find a resource such as an MBML file.
+ (nonnull NSArray *)resourceSearchBundles
Return Value
An array of NSBundle
s. Will never be nil
.
Declared In
MBEnvironment.h
Determining the state of the environment
isLoaded
Returns YES
if the environment is loaded; NO
otherwise.
@property (nonatomic, assign, readonly) BOOL isLoaded
Declared In
MBEnvironment.h
manifestFilePath
If the environment was loaded using a manifest file, this property will
return the path of the manifest file. If the environment isn’t loaded
or if the environment was loaded without using a manifest file (such as
through the loadDefaultEnvironment
method), this value will be nil
.
@property (nullable, nonatomic, strong, readonly) NSString *manifestFilePath
Declared In
MBEnvironment.h
mbmlPathsLoaded
This property contains the paths of the MBML files that have been loaded by the environment thusfar.
@property (nonnull, nonatomic, copy, readonly) NSArray *mbmlPathsLoaded
Declared In
MBEnvironment.h
– mbmlPathIsLoaded:
Determines if an MBML file with a specific path has been loaded by the receiver.
- (BOOL)mbmlPathIsLoaded:(nonnull NSString *)filePath
Parameters
filePath |
The path of the file. |
---|
Return Value
YES
if the environment has loaded an MBML file at the path
filePath
; NO
otherwise.
Declared In
MBEnvironment.h
– mbmlFileIsLoaded:
Determines if an MBML file with a specific name has been loaded by the receiver.
- (BOOL)mbmlFileIsLoaded:(nonnull NSString *)fileName
Parameters
fileName |
The filename, also known as the last path component. |
---|
Return Value
YES
if the environment has loaded an MBML file with the given
name; NO
otherwise.
Discussion
Because MBML is designed to be path-agnostic, the system does not support multiple files with the same name, even if their paths are different. Therefore, all MBML filenames are guaranteed to be unique.
Declared In
MBEnvironment.h
Working with external libraries
+ addSupportedLibraryClassPrefix:
Allows the loading of environment classes from libraries whose class names begin with the specified prefix.
+ (void)addSupportedLibraryClassPrefix:(nonnull NSString *)prefix
Parameters
prefix |
The class prefix Mockingbird should support for dynamic class loading. |
---|
Declared In
MBEnvironment.h
+ supportedLibraryClassPrefixes
Returns an array containing the class prefixes that will be searched when attempting to load environment classes.
+ (nonnull NSArray *)supportedLibraryClassPrefixes
Return Value
An array of strings containing the supported class prefixes.
Will never be nil
and will always contain at least one value,
the string “MB
”.
Declared In
MBEnvironment.h
+ libraryClassForName:
Uses the supportedClassPrefixes
to find an available Class
that implements
the class with the specified name.
+ (nullable Class)libraryClassForName:(nonnull NSString *)className
Parameters
className |
The class name for which a |
---|
Return Value
A Class
for className
, if a class exists among the supported
class prefixes, or without any prefix. Returns nil
if no class
could be found.
Discussion
Mockingbird uses this method to find classes that are dynamically loaded by name.
First, a class with a name matching the className
parameter is sought. If
no such class exists, the system will then iterate over the
supportedClassPrefixes
and, for each prefix, will attempt to find a class
whose name is className
with the given prefix. The first one found (if any)
is returned.
Declared In
MBEnvironment.h
Adding functionality through modules
+ enableModuleClass:
Enables the MBModule
represented by the specified class. When new
MBEnvironment
instances are created, they will gain support for the
features added by the module implementation.
+ (BOOL)enableModuleClass:(nonnull Class)cls
Parameters
cls |
The implementing class of the |
---|
Return Value
YES
if cls
represents an MBModule
that is now enabled. Will
be NO
if cls
does not conform to MBModule
.
Declared In
MBEnvironment.h
+ enabledModuleClasses
Returns an array containing the MBModule
classes that will be enabled for all
newly-created environments. Note when a given environment instance is loaded,
additional modules not included in this array may be enabled through the
manifest file.
+ (nonnull NSArray *)enabledModuleClasses
Return Value
The currently-enabled modules. Will always contain at least one
item, because MBDataEnvironmentModule
is always enabled.
Declared In
MBEnvironment.h
– enabledModuleClasses
Returns an array of Class
es representing the MBModule
s enabled in the
receiver.
- (nonnull NSArray *)enabledModuleClasses
Return Value
The modules enabled in the receiving environment. Will always
contain at least one item, because MBDataEnvironmentModule
is
always enabled. Additional modules may also be enabled through the
manifest file.
Declared In
MBEnvironment.h
Accessing environment loaders
– environmentLoaders
Returns an array of MBEnvironmentLoader
instances representing the
environment loaders consulted when the receiving environment is loaded.
- (nonnull NSArray *)environmentLoaders
Return Value
The environment loaders used by the receiver. Will never be nil
.
Declared In
MBEnvironment.h
– environmentLoaderOfClass:
Returns the first MBEnvironmentLoader
instance known to the receiver that
is an instance of the given class.
- (nullable MBEnvironmentLoader *)environmentLoaderOfClass:(nonnull Class)cls
Parameters
cls |
The class for which an implementing |
---|
Return Value
The first MBEnvironmentLoader
representing an instance of cls
.
Will be nil
if no such environment loader was found.
Declared In
MBEnvironment.h