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 MBEnvironment to set as the active environment.

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 MBEnvironment to set as the active environment.

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 dirPath, the resourceSearchBundles will then be searched.

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 dirPath, the resourceSearchBundles will then be searched.

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 dirPaths) when MBML files are referenced. If a given file can’t be found in the any of the directories specified by dirPaths, the resourceSearchBundles will then be searched.

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 dirPaths) when MBML files are referenced. If a given file can’t be found in the any of the directories specified by dirPaths, the resourceSearchBundles will then be searched.

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

Search directory management

– addSearchDirectory:

Adds the specified directory path to the list of search directories.

- (void)addSearchDirectory:(nonnull NSString *)dirPath

Parameters

dirPath

The path of a directory that to be searched when trying to locate MBML files.

Discussion

When attempting to locate an MBML file, the receiver first consults the search directories, in order, for a file with the given name. If the file isn’t found in any of the search directories, the resourceSearchBundles will then be searched.

Declared In

MBEnvironment.h

– addSearchDirectories:

Adds the specified directory paths to the list of search directories.

- (void)addSearchDirectories:(nonnull NSArray *)dirPaths

Parameters

dirPaths

An array containing the paths of directories to be searched when trying to locate MBML files.

Discussion

When attempting to locate an MBML file, the receiver first consults the search directories, in order, for a file with the given name. If the file isn’t found in any of the search directories, the resourceSearchBundles will then be searched.

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 NSBundle instance that should be searched when attempting to find resources.

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 NSBundles. 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 Class is sought.

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 MBModule to enable.

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 Classes representing the MBModules 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 MBEnvironmentLoader instance is sought.

Return Value

The first MBEnvironmentLoader representing an instance of cls. Will be nil if no such environment loader was found.

Declared In

MBEnvironment.h