MBDataModel Class Reference

Inherits from MBFormattedDescriptionObject
Conforms to NSCoding
NSCopying
NSMutableCopying
Declared in MBDataModel.h

Overview

An implementation of a generic class representing a node in a data model. Each data model instance contains attributes and related objects that are typically populated from XML.

When populated from an XML element, an MBDataModel instance’s attributes are populated from the XML element’s attributes. Related objects may also be added based on whether the element contains any child XML elements.

Data models support validation, wherein their attributes and related objects are inspected to see whether they contain the expected values. Subclasses may implement any of the following methods to participate in validation:

Mockingbird uses instances of this class to represent data loaded from MBML (the XML-based Mockingbird Markup Language), and validation is performed to notify MBML developers of any errors in their code.

Factory & initializer methods

+ dataModelFromXML:

Creates and returns a new data model populated with the contents of the passed-in XML element. Attribute values will be set from the attributes of the XML element, and further object relationships may be established by processing the children of the element.

+ (nonnull instancetype)dataModelFromXML:(nonnull RXMLElement *)xml

Parameters

xml

The XML to use for populating the data model

Declared In

MBDataModel.h

– init

Default initializer; returns an empty data model instance.

- (nonnull instancetype)init

Declared In

MBDataModel.h

– initWithXML:

Populates the receiver with the data model inherent in the provided XML element. Attribute values will be set from the attributes of the XML element, and further object relationships may be established by processing the children of the element.

- (nonnull instancetype)initWithXML:(nonnull RXMLElement *)xml

Parameters

xml

The XML to use for populating the data model

Declared In

MBDataModel.h

– initWithAttributes:

For each key/value pair contained in the passed-in dictionary, a corresponding attribute name and value will be set on the receiver.

- (nonnull instancetype)initWithAttributes:(nonnull NSDictionary *)attrs

Parameters

attrs

A dictionary containing the attribute names and values to use for initializing the data model object.

Declared In

MBDataModel.h

NSCopying support

– copyWithZone:

Returns a copy of the receiver. Since all MBDataModel instances are mutable, this method simply calls mutableCopyWithZone:.

- (nonnull id)copyWithZone:(nullable NSZone *)zone

Parameters

zone

Identifies a memory zone to use for allocating any new object instances. If nil, the default zone returned by NSDefaultMallocZone() is used.

Declared In

MBDataModel.h

– mutableCopyWithZone:

Returns a copy of the receiver.

- (nonnull id)mutableCopyWithZone:(nullable NSZone *)zone

Parameters

zone

Identifies a memory zone to use for allocating any new object instances. If nil, the default zone returned by NSDefaultMallocZone() is used.

Declared In

MBDataModel.h

– cloneDataModel:

Turns the receiver into a clone of the passed-in data model. Any attributes and relatives held by the receiver are thrown away, and then the receiver is configured to contain all the same attributes and relatives as cloneFrom.

- (void)cloneDataModel:(nonnull MBDataModel *)cloneFrom

Parameters

cloneFrom

The data model to clone.

Declared In

MBDataModel.h

– cloneDataModel:withZone:

Turns the receiver into a clone of the passed-in data model. Any attributes and relatives held by the receiver are thrown away, and then the receiver is configured to contain all the same attributes and relatives as cloneFrom.

- (void)cloneDataModel:(nonnull MBDataModel *)cloneFrom withZone:(nullable NSZone *)zone

Parameters

cloneFrom

The data model to clone.
zone

The NSZone to use for any objects that need to be copied as a result of the cloning process. If nil, the default zone returned by NSDefaultMallocZone() is used.

Declared In

MBDataModel.h

Class posing

– poseAsClass:

Returns a new data model instance of the specified class that contains the exact same attributes and relatives as the receiver.

- (nullable id)poseAsClass:(nonnull Class)cls

Parameters

cls

The class to pose as.

Return Value

A new data model instance of type cls containing the same data model attributes and related objects as the receiver, or nil if cls is not a type of MBDataModel class.

Discussion

This is useful in cases where you might want to instantiate generic data models from XML before doing the work of deciding what Class each node should be. Allows for faster loading of data models from XML.

Declared In

MBDataModel.h

XML parsing convenience

+ xmlFromFile:error:

A convenience method for parsing an XML document from a file.

+ (nonnull RXMLElement *)xmlFromFile:(nonnull NSString *)filePath error:(NSErrorPtrPtr)errPtr

Parameters

filePath

The path of the XML file to be processed.
errPtr

If non-nil and an error occurs, *errPtr will be set to an NSError instance indicating the error.

Return Value

An object representing the top-level element of the XML, or nil if an error occurred.

Declared In

MBDataModel.h

+ xmlFromData:error:

A convenience method for parsing an XML document from an NSData instance.

+ (nonnull RXMLElement *)xmlFromData:(nonnull NSData *)xmlData error:(NSErrorPtrPtr)errPtr

Parameters

xmlData

The XML data to be processed.
errPtr

If non-nil and an error occurs, *errPtr will be set to an NSError instance indicating the error.

Return Value

An object representing the top-level element of the XML, or nil if an error occurred.

Declared In

MBDataModel.h

Populating the data model

– amendDataModelWithXML:

Amends the data model by overlaying attributes and potentially adding relatives to the receiver based on the contents of the passed-in XML.

- (void)amendDataModelWithXML:(nonnull RXMLElement *)xml

Parameters

xml

The XML element to use for amending the data model.

Discussion

If the receiver contains attributes also present on the XML element, the receiver’s attributes are replaced, while new attributes are added. If the XML element contains child elements, they may be added to the receiver as related objects.

Declared In

MBDataModel.h

– amendDataModelWithXMLFromFile:

Amends the data model by overlaying attributes and potentially adding relatives to the receiver based on the contents of the passed-in XML.

- (BOOL)amendDataModelWithXMLFromFile:(nonnull NSString *)filePath

Parameters

filePath

The path of the file containing the XML to process.

Return Value

YES if the XML file was processed successfully; NO otherwise.

Discussion

If the receiver contains attributes also present on the XML element, the receiver’s attributes are replaced, while new attributes are added. If the XML element contains child elements, they may be added to the receiver as related objects.

Declared In

MBDataModel.h

– amendDataModelWithXMLFromFile:error:

Amends the data model by overlaying attributes and potentially adding relatives to the receiver based on the contents of the passed-in XML.

- (BOOL)amendDataModelWithXMLFromFile:(nonnull NSString *)filePath error:(NSErrorPtrPtr)errPtr

Parameters

filePath

The path of the file containing the XML to process.
errPtr

If non-nil and an error occurs, *errPtr will be set to an NSError instance indicating the error.

Return Value

YES if the XML file was processed successfully; NO otherwise.

Discussion

If the receiver contains attributes also present on the XML element, the receiver’s attributes are replaced, while new attributes are added. If the XML element contains child elements, they may be added to the receiver as related objects.

Declared In

MBDataModel.h

– amendDataModelWithXMLFromData:

Amends the data model by overlaying attributes and potentially adding relatives to the receiver based on the contents of the passed-in XML.

- (BOOL)amendDataModelWithXMLFromData:(nonnull NSData *)xmlData

Parameters

xmlData

An NSData instance containing the XML to process.

Return Value

YES if the XML data was processed successfully; NO otherwise.

Discussion

If the receiver contains attributes also present on the XML element, the receiver’s attributes are replaced, while new attributes are added. If the XML element contains child elements, they may be added to the receiver as related objects.

Declared In

MBDataModel.h

– amendDataModelWithXMLFromData:error:

Amends the data model by overlaying attributes and potentially adding relatives to the receiver based on the contents of the passed-in XML.

- (BOOL)amendDataModelWithXMLFromData:(nonnull NSData *)xmlData error:(NSErrorPtrPtr)errPtr

Parameters

xmlData

An NSData instance containing the XML to process.
errPtr

If non-nil and an error occurs, *errPtr will be set to an NSError instance indicating the error.

Return Value

YES if the XML data was processed successfully; NO otherwise.

Discussion

If the receiver contains attributes also present on the XML element, the receiver’s attributes are replaced, while new attributes are added. If the XML element contains child elements, they may be added to the receiver as related objects.

Declared In

MBDataModel.h

– addAttributesFromXML:

For each attribute value of the passed-in XML element, a corresponding attribute will be set on the receiver.

- (void)addAttributesFromXML:(nonnull RXMLElement *)xml

Parameters

xml

The XML element to process.

Discussion

If the receiver contains attributes also present on the XML element, the receiver’s attributes are replaced, while new attributes are added.

Declared In

MBDataModel.h

– addAttributesFromDictionary:

For each key/value pair contained in the passed-in dictionary, a corresponding attribute will be set on the receiver.

- (void)addAttributesFromDictionary:(nonnull NSDictionary *)dict

Parameters

dict

The dictionary containing the attributes values to be set.

Discussion

If the receiver contains attributes also present on the XML element, the receiver’s attributes are replaced, while new attributes are added.

Declared In

MBDataModel.h

– overlayAttributesFromDictionary:

For each attribute key contained in the passed-in dictionary, the receiver will be checked for an attribute having the same name. If the receiver has no attribute with that name, the corresponding key/value pair in the dictionary will be set on the receiver. Existing attributes will not be overwritten.

- (void)overlayAttributesFromDictionary:(nonnull NSDictionary *)dict

Parameters

dict

The dictionary containing the attributes values to overlay.

Declared In

MBDataModel.h

– populateDataModelFromXML:

Adds related objects, if appropriate, for each XML element contained in the passed-in element. The default implementation creates MBDataModel objects to represent the structure of the contained XML elements, and adds them as related objects to the receiver using the default relation type.

- (void)populateDataModelFromXML:(nonnull RXMLElement *)container

Parameters

container

The XML element whose child elements will be used to populate the receiver.

Declared In

MBDataModel.h

– dataModelDidLoad

Called to notify the data model that it has been loaded or instantiated.

- (void)dataModelDidLoad

Discussion

Note: Subclasses overriding this method must always call super.

Declared In

MBDataModel.h

– didAmendDataModelWithXMLFromFile:

Called to notify the data model that it has been amended using the contents of the given file.

- (void)didAmendDataModelWithXMLFromFile:(nonnull NSString *)filePath

Parameters

filePath

The path of the file whose XML was loaded.

Discussion

Note: Subclasses overriding this method must always call super.

Declared In

MBDataModel.h

XML representation

+ dataEntityName

The entity name used to represent instances of the receiver’s class. Used for the XML tag in simulated XML output when the xmlTagName method would return nil.

+ (nonnull NSString *)dataEntityName

Declared In

MBDataModel.h

  xmlTagName

If the receiver was created from an XML element, this method returns the name of the XML tag from which it originated.

@property (nullable, nonatomic, readonly) NSString *xmlTagName

Return Value

The XML tag name used to create the receiver, or nil if the receiver was not created from XML.

Declared In

MBDataModel.h

  simulatedXML

Returns a string containing a simulated XML representation of the receiver’s attributes and related objects. This method works even if the receiver was not populated from XML in the first place.

@property (nonnull, nonatomic, readonly) NSString *simulatedXML

Discussion

Note: The XML output is simulated and may not be a byte-for-byte representation of the originating XML (if any). Non-significant whitespace and attribute order may differ, and if any attributes were applied from an MBStyledDataModel, they will be represented in the simulated XML as well.

Declared In

MBDataModel.h

  debuggingXML

Provides simulated XML output similar to that of the simulatedXML property, but with XML comments added that describe the relation type of any related objects.

@property (nonnull, nonatomic, readonly) NSString *debuggingXML

Declared In

MBDataModel.h

Data model enforcement

+ requiredAttributes

Returns the set of attributes required by the receiving class (and not any superclass or subclass).

+ (nullable NSSet *)requiredAttributes

Return Value

The default implementation returns nil, indicating that no attributes are explicitly required.

Discussion

Implementing this method allows a class to declare that it requires one or more attributes.

During validation, an error will be logged to the console for each required MBDataModel attribute that is not present in the receiver. Further, validation will fail if any required attribute is missing.

Warning: Subclasses overriding this method must never call super.

Declared In

MBDataModel.h

+ supportedAttributes

Returns the set of attributes supported by the receiving class (and not any superclass or subclass).

+ (nullable NSSet *)supportedAttributes

Return Value

The default implementation returns nil, indicating that no attributes are explicitly supported.

Discussion

Implementing this method allows a class to declare that it supports one or more attributes.

During validation, a warning will be logged to the console for each MBDataModel attribute present in the receiver that does not appear in the set of supported attributes. However, the presence of unsupported attributes will not cause validation to fail.

Note: Implementations do not need to report an attribute as supported if it is also reported as required.

Warning: Subclasses overriding this method must never call super.

Declared In

MBDataModel.h

+ unsupportedAttributes

Returns the set of attributes that are supported by one of the receiving class’s superclasses but are unsupported by the receiving class.

+ (nullable NSSet *)unsupportedAttributes

Return Value

The default implementation returns nil, indicating that no attributes are explicitly unsupported.

Discussion

Implementing this method allows a class to declare that it does not support one or more attributes supported by a superclass.

During validation, a warning will be logged to the console for each MBDataModel attribute present in the receiver that is declared as unsupported. However, the presence of unsupported attributes will not cause validation to fail.

Warning: Subclasses overriding this method must never call super.

Declared In

MBDataModel.h

– implementingClassAttributeName

Returns the name of an attribute that specifies an alternate implementing class for the data model object, allowing external classes to participate in attribute validation.

- (nullable NSString *)implementingClassAttributeName

Return Value

The default implementation returns nil, indicating that the receiver will not consult an external class for determining which data model attributes are valid.

Declared In

MBDataModel.h

– requiredAttributes

Returns the names of the attributes that are required by the receiver in order to pass validation.

- (nullable NSSet *)requiredAttributes

Declared In

MBDataModel.h

– ignoredAttributes

Returns the names of the attributes that will ignored by the receiver.

- (nullable NSSet *)ignoredAttributes

Declared In

MBDataModel.h

– deprecateAttribute:inFavorOf:

Marks an attribute as being deprecated in favor of another attribute. This mechanism is used to rename an attribute while still maintaining backwards compatibility with existing code.

- (void)deprecateAttribute:(nonnull NSString *)deprecatedAttribute inFavorOf:(nonnull NSString *)newAttribute

Parameters

deprecatedAttribute

The name of the deprecated attribute.
newAttribute

The name of the attribute to use instead of deprecatedAttribute.

Discussion

Whenever a deprecated attribute is encountered during validation, a warning is issued and the value of the deprecated attribute is copied to the new attribute (assuming the new attribute doesn’t already exist, in which case the value of the deprecated attribute is ignored altogether).

Note: This method must be called prior to invoking the superclass implementation of the validateAttributes method.

Declared In

MBDataModel.h

Data model validation

– validateDataModel

Attempts to validate the data model using the receiver as the root node.

- (BOOL)validateDataModel

Return Value

YES if the receiver’s data model is valid; NO otherwise.

Discussion

Validation will occur even if the receiver is not marked as needing validation. Use validateDataModelIfNeeded to ensure validation occurs only when necessary.

Warning: Subclasses shouldn’t override this method. Instead, to hook into the validation process, subclasses should override validateAttributes or validateAsRelativeOf:relatedBy:dataModelRoot:.

Declared In

MBDataModel.h

– validateDataModelIfNeeded

If the data model is marked as needing validation, this method returns the result of calling validateDataModel; otherwise, this method returns the result of calling isDataModelValid.

- (BOOL)validateDataModelIfNeeded

Return Value

YES if the receiver’s data model is valid; NO otherwise.

Discussion

Warning: Subclasses shouldn’t override this method. Instead, to hook into the validation process, subclasses should override validateAttributes or validateAsRelativeOf:relatedBy:dataModelRoot:.

Declared In

MBDataModel.h

– validateAttributes

Asks the receiver to validate its data model attributes (but not any related objects).

- (BOOL)validateAttributes

Return Value

YES if the receiver’s attributes are valid; NO otherwise.

Discussion

A data model object’s attributes are considered valid if all required attributes are present.

Subclasses that need to hook into the attribute validation process may override this method, but should be sure to call the superclass implementation.

Note: For each unsupported attribute encountered during attribute validation, a warning will be logged to the console. However, the presence of unsupported attributes will not cause the data model to be considered invalid.

Declared In

MBDataModel.h

– validateAsRelativeOf:relatedBy:dataModelRoot:

Called by validateDataModel to attempt to validate a member of a larger data model.

- (BOOL)validateAsRelativeOf:(nullable MBDataModel *)relative relatedBy:(nullable NSString *)relationType dataModelRoot:(nonnull MBDataModel *)root

Parameters

relative

If the receiver is being validated as a relative of another data model object, this parameter will contain the relative. This parameter will be nil if the receiver is the root node of the data model.
relationType

If the receiver is being validated as a relative of another data model object, this parameter will contain the name of the relation type by which the receiver is related to relative. This parameter will be nil if the receiver is the root node of the data model.
root

If the receiver is being validated as a relative of another data model object, this parameter will contain the root node of the data model (in other words, the original receiver of the call to validateDataModel). If the receiver is the root node of the data model being validated, this parameter will equal self.

Return Value

YES if the receiver’s data model is valid; NO otherwise.

Discussion

Subclasses that need to hook into the data model validation process may override this method. However, if subclasses only need to perform attribute validation, they should override the simpler validateAttributes method.

If a subclass implementation detects no problem with the data model, it should return the value returned by calling the superclass’s validateAsRelativeOf:relatedBy:dataModelRoot: method.

At the first sign of an invalid data model, subclass implementations should return NO.

Warning: This method should not be called directly, except by subclasses calling the superclass implementation.

Declared In

MBDataModel.h

– markDataModelNeedsValidation

This method is called to mark the receiver as needing validation.

- (void)markDataModelNeedsValidation

Declared In

MBDataModel.h

– doesDataModelNeedValidation

Returns YES if the receiver needs data model validation, NO otherwise.

- (BOOL)doesDataModelNeedValidation

Discussion

Whenever the data model changes, it will be marked as needing validation.

Note: At instantiation time, a data model is considered invalid and is marked as needing validation. After a call to validateDataModel returns, the receiver is marked as no longer needing validation, even if validation fails.

Declared In

MBDataModel.h

– markDataModelInvalid

This method is called to mark the receiver’s data model as invalid.

- (void)markDataModelInvalid

Declared In

MBDataModel.h

– isDataModelValid

Returns YES if the receiver’s most recent validation attempt succeeded and if the receiver is not marked as needing validation.

- (BOOL)isDataModelValid

Declared In

MBDataModel.h

Copying data model attributes

– objectAttributes

Returns a copy of the receiver’s attribute values.

- (nullable NSDictionary *)objectAttributes

Declared In

MBDataModel.h

– addAttributesToDictionary:

Adds the receiver’s attributes to the passed-in NSMutableDictionary.

- (void)addAttributesToDictionary:(nonnull NSMutableDictionary *)dict

Parameters

dict

The dictionary to which the receiver’s attribute names and values will be added.

Declared In

MBDataModel.h

Accessing data model values

  content

Represents the content of this data model object. When the data model is populated from an XML element containing text content, this property will contain an NSString with that text.

@property (nullable, nonatomic, strong) id content

Declared In

MBDataModel.h

  hasStringContent

Returns YES if the value of the content property is an NSString, and if that string contains at least one non-whitespace character.

@property (nonatomic, assign) BOOL hasStringContent

Declared In

MBDataModel.h

– countAttributes

Returns the number of attributes that currently have values set on the receiver.

- (NSUInteger)countAttributes

Declared In

MBDataModel.h

– attributeNames

Returns an array of NSStrings containing the names of the attributes that currently have values set on the receiver.

- (nullable NSArray *)attributeNames

Declared In

MBDataModel.h

– hasAttribute:

Returns YES if the receiver has an attribute with the specified name, NO otherwise.

- (BOOL)hasAttribute:(nonnull NSString *)attrName

Parameters

attrName

The name of the attribute to check.

Declared In

MBDataModel.h

– valueOfAttribute:

Returns the value of the attribute with the specified name.

- (nullable id)valueOfAttribute:(nonnull NSString *)attrName

Parameters

attrName

The name of the attribute whose value is to be retrieved.

Return Value

The value of the attribute attrName. May be nil.

Declared In

MBDataModel.h

– stringValueOfAttribute:

Returns the string value of the attribute with the specified name.

- (nullable NSString *)stringValueOfAttribute:(nonnull NSString *)attrName

Parameters

attrName

The name of the attribute whose value is to be retrieved.

Return Value

The value of the attribute attrName as an NSString. May be nil.

Discussion

If the value’s underlying type is not NSString, the value will be coerced into a string using the NSObject’s description method.

Declared In

MBDataModel.h

– numberValueOfAttribute:

Returns the numeric value of the attribute with the specified name.

- (nullable NSDecimalNumber *)numberValueOfAttribute:(nonnull NSString *)attrName

Parameters

attrName

The name of the attribute whose value is to be retrieved.

Return Value

The value of the attribute attrName as an NSNumber. May be nil.

Discussion

If the value’s underlying type is not NSNumber, the value will be coerced into a number using [MBExpression numberFromValue:].

Declared In

MBDataModel.h

– booleanValueOfAttribute:

Returns the boolean value of the attribute with the specified name.

- (BOOL)booleanValueOfAttribute:(nonnull NSString *)attrName

Parameters

attrName

The name of the attribute whose value is to be retrieved.

Return Value

The value of the attribute attrName as a BOOL.

Discussion

If the value’s underlying type is not boolean, the value will be coerced into a boolean using [MBExpression booleanFromValue:].

Declared In

MBDataModel.h

– integerValueOfAttribute:

Returns the NSInteger value of the attribute with the specified name.

- (NSInteger)integerValueOfAttribute:(nonnull NSString *)attrName

Parameters

attrName

The name of the attribute whose value is to be retrieved.

Return Value

The value of the attribute attrName as an NSInteger.

Discussion

If the value’s underlying type is not NSNumber, the value will be coerced into a number using [MBExpression numberFromValue:] and the resulting instance’s integerValue will be returned.

Declared In

MBDataModel.h

– doubleValueOfAttribute:

Returns the double value of the attribute with the specified name.

- (double)doubleValueOfAttribute:(nonnull NSString *)attrName

Parameters

attrName

The name of the attribute whose value is to be retrieved.

Return Value

The value of the attribute attrName as a double.

Discussion

If the value’s underlying type is not NSNumber, the value will be coerced into a number using [MBExpression numberFromValue:] and the resulting instance’s doubleValue will be returned.

Declared In

MBDataModel.h

Keyed subscripting support

– objectForKeyedSubscript:

Provides access to data model attribute values using the Objective-C keyed subscripting notation.

- (nullable id)objectForKeyedSubscript:(nonnull NSString *)attrName

Parameters

attrName

The name of the attribute whose value is to be retrieved.

Return Value

The value of the attribute with the name attrName. May be nil.

Discussion

In the following Objective-C code:

MBDataModel* node = // declared elsewhere

id nodeTitle = node[@"title"];

The nodeTitle variable would contain the value of node’s attribute named “title”.

Declared In

MBDataModel.h

– setObject:forKeyedSubscript:

Allows setting data model attribute values using the Objective-C keyed subscripting notation.

- (void)setObject:(nonnull id)obj forKeyedSubscript:(nonnull NSString *)attrName

Parameters

obj

The new value for the attribute.
attrName

The name of the attribute whose value is to be set.

Discussion

In the following Objective-C code:

MBDataModel* node = // declared elsewhere

node[@"title"] = @"Mockingbird";

node’s attribute named “title” is set to the string “Mockingbird”.

Declared In

MBDataModel.h

Performing expression evaluation on attribute values

– evaluateAsObject:

Interprets the value of the given attribute as an NSString containing an expression, and returns the result of evaluating that expression in the object context.

- (nullable id)evaluateAsObject:(nonnull NSString *)attrName

Parameters

attrName

The name of the attribute whose value will be evaluated as an expression.

Return Value

The result of evaluating the value of attrName as an expression. May be nil.

Discussion

If the value’s underlying type is not NSString, the value will be coerced into a string using the NSObject’s description method before being evaluated as an expression.

Declared In

MBDataModel.h

– evaluateAsObject:defaultValue:

Interprets the value of the given attribute as an NSString containing an expression, and returns the result of evaluating that expression in the object context.

- (nullable id)evaluateAsObject:(nonnull NSString *)attrName defaultValue:(nullable id)def

Parameters

attrName

The name of the attribute whose value will be evaluated as an expression.
def

The value to return if the receiver has no attribute named attrName, or if expression evaluation failed for some reason.

Return Value

The result of evaluating the value of attrName as an expression, or def if evaluation failed.

Discussion

If the value’s underlying type is not NSString, the value will be coerced into a string using the NSObject’s description method before being evaluated as an expression.

Declared In

MBDataModel.h

– evaluateAsString:

Interprets the value of the given attribute as an NSString containing an expression, and returns the result of evaluating that expression in the string context.

- (nullable NSString *)evaluateAsString:(nonnull NSString *)attrName

Parameters

attrName

The name of the attribute whose value will be evaluated as an expression.

Return Value

The result of evaluating the value of attrName as an expression. May be nil.

Discussion

If the value’s underlying type is not NSString, the value will be coerced into a string using the NSObject’s description method before being evaluated as an expression.

Declared In

MBDataModel.h

– evaluateAsString:defaultValue:

Interprets the value of the given attribute as an NSString containing an expression, and returns the result of evaluating that expression in the string context.

- (nullable NSString *)evaluateAsString:(nonnull NSString *)attrName defaultValue:(nullable NSString *)def

Parameters

attrName

The name of the attribute whose value will be evaluated as an expression.
def

The value to return if the receiver has no attribute named attrName, or if expression evaluation failed for some reason.

Return Value

The result of evaluating the value of attrName as an expression, or def if evaluation failed.

Discussion

If the value’s underlying type is not NSString, the value will be coerced into a string using the NSObject’s description method before being evaluated as an expression.

Declared In

MBDataModel.h

– evaluateAsNumber:

Interprets the value of the given attribute as an NSString containing an expression, and returns the result of evaluating that expression in the numeric context.

- (nullable NSDecimalNumber *)evaluateAsNumber:(nonnull NSString *)attrName

Parameters

attrName

The name of the attribute whose value will be evaluated as an expression.

Return Value

The result of evaluating the value of attrName as an expression.

Discussion

If the value’s underlying type is not NSString, the value will be coerced into a string using the NSObject’s description method before being evaluated as an expression.

Declared In

MBDataModel.h

– evaluateAsNumber:defaultValue:

Interprets the value of the given attribute as an NSString containing an expression, and returns the result of evaluating that expression in the numeric context.

- (nullable NSDecimalNumber *)evaluateAsNumber:(nonnull NSString *)attrName defaultValue:(nullable NSDecimalNumber *)def

Parameters

attrName

The name of the attribute whose value will be evaluated as an expression.
def

The value to return if the receiver has no attribute named attrName, or if expression evaluation failed for some reason.

Return Value

The result of evaluating the value of attrName as an expression, or def if evaluation failed.

Discussion

If the value’s underlying type is not NSString, the value will be coerced into a string using the NSObject’s description method before being evaluated as an expression.

Declared In

MBDataModel.h

– evaluateAsBoolean:

Interprets the value of the given attribute as an NSString containing an expression, and returns the result of evaluating that expression in the boolean context.

- (BOOL)evaluateAsBoolean:(nonnull NSString *)attrName

Parameters

attrName

The name of the attribute whose value will be evaluated as an expression.

Return Value

The result of evaluating the value of attrName as an expression.

Discussion

If the value’s underlying type is not NSString, the value will be coerced into a string using the NSObject’s description method before being evaluated as an expression.

Declared In

MBDataModel.h

– evaluateAsBoolean:defaultValue:

Interprets the value of the given attribute as an NSString containing an expression, and returns the result of evaluating that expression in the boolean context.

- (BOOL)evaluateAsBoolean:(nonnull NSString *)attrName defaultValue:(BOOL)def

Parameters

attrName

The name of the attribute whose value will be evaluated as an expression.
def

The value to return if the receiver has no attribute named attrName, or if expression evaluation failed for some reason.

Return Value

The result of evaluating the value of attrName as an expression, or def if evaluation failed.

Discussion

If the value’s underlying type is not NSString, the value will be coerced into a string using the NSObject’s description method before being evaluated as an expression.

Declared In

MBDataModel.h

Setting data model attribute values

– setAttribute:forName:

Sets a data model attribute value.

- (void)setAttribute:(nullable id)attrVal forName:(nonnull NSString *)attrName

Parameters

attrVal

The new value of the attribute. If nil, any existing value for attrName will be removed from the receiver.
attrName

The name of the attribute whose value is being set.

Declared In

MBDataModel.h

– setBooleanAttribute:forName:

Sets a boolean data model attribute value.

- (void)setBooleanAttribute:(BOOL)attrVal forName:(nonnull NSString *)attrName

Parameters

attrVal

The new value of the attribute.
attrName

The name of the attribute whose value is being set.

Declared In

MBDataModel.h

– setIntegerAttribute:forName:

Sets a boolean data model attribute value.

- (void)setIntegerAttribute:(NSInteger)attrVal forName:(nonnull NSString *)attrName

Parameters

attrVal

The new value of the attribute.
attrName

The name of the attribute whose value is being set.

Declared In

MBDataModel.h

– setDoubleAttribute:forName:

Sets a double data model attribute value.

- (void)setDoubleAttribute:(double)attrVal forName:(nonnull NSString *)attrName

Parameters

attrVal

The new value of the attribute.
attrName

The name of the attribute whose value is being set.

Declared In

MBDataModel.h

Renaming and removing attributes

– renameAttribute:to:

Renames an attribute, moving the value from the old attribute name to the new name.

- (void)renameAttribute:(nonnull NSString *)oldName to:(nonnull NSString *)newName

Parameters

oldName

The name of the attribute to rename to newName.
newName

The new name for the attribute currently known as oldName.

Declared In

MBDataModel.h

– removeAttribute:

Removes the specified attribute from the receiver.

- (void)removeAttribute:(nonnull NSString *)attrName

Parameters

attrName

The name of the attribute to remove from the receiver.

Declared In

MBDataModel.h

Determining relation types

+ defaultRelationType

Returns the name of the default relation used by the class.

+ (nonnull NSString *)defaultRelationType

Declared In

MBDataModel.h

– currentRelationTypes

Returns an array of NSStrings containing the names of each relation type for which there is currently at least one related object.

- (nonnull NSArray *)currentRelationTypes

Discussion

The order of the elements in the returned array is nondeterministic and has no significance.

Declared In

MBDataModel.h

Counting related objects

– countRelatives

Returns the count of all related objects in the data model.

- (NSUInteger)countRelatives

Declared In

MBDataModel.h

– countRelativesWithRelationType:

Returns the count of the related objects in the data model that have the specified relation type.

- (NSUInteger)countRelativesWithRelationType:(nonnull NSString *)relation

Parameters

relation

The relation type whose relatives are to be counted.

Declared In

MBDataModel.h

– countRelativesWithDefaultRelation

Returns the count of the related objects in the data model that have the default relation type.

- (NSUInteger)countRelativesWithDefaultRelation

Declared In

MBDataModel.h

Accessing related objects

  containingRelative

The containing data model relative (if any) of the receiver. Will be set if the receiver was added as a relative to another data model instance.

@property (nullable, nonatomic, weak) MBDataModel *containingRelative

Declared In

MBDataModel.h

– allRelatives

Returns all MBDataModel objects related to the receiver regardless of relation type.

- (nonnull NSArray *)allRelatives

Return Value

An NSArray containing the relatives. If there are no relatives, an empty array—not nil—will be returned.

Declared In

MBDataModel.h

– relativesWithRelationType:

Returns all MBDataModel objects related to the receiver by the specified relation type.

- (nonnull NSArray *)relativesWithRelationType:(nonnull NSString *)relation

Parameters

relation

The name of the relation type for which the related objects will be returned.

Return Value

An NSArray containing the relatives. If there are no relatives, an empty array—not nil—will be returned.

Declared In

MBDataModel.h

– relativesWithDefaultRelation

Returns all MBDataModel objects related to the receiver by the default relation type.

- (nonnull NSArray *)relativesWithDefaultRelation

Return Value

An NSArray containing the relatives. If there are no relatives, an empty array—not nil—will be returned.

Declared In

MBDataModel.h

– firstRelativeWithDefaultRelation

Returns the first MBDataModel related to the receiver by the default relation type.

- (nullable MBDataModel *)firstRelativeWithDefaultRelation

Return Value

The first relative, or nil if there isn’t one.

Declared In

MBDataModel.h

– firstRelativeWithRelationType:

Returns the first MBDataModel related to the receiver by the specified relation type.

- (nullable MBDataModel *)firstRelativeWithRelationType:(nonnull NSString *)relation

Parameters

relation

The name of the relation type for which the first related object will be returned.

Return Value

The first relative, or nil if there isn’t one.

Declared In

MBDataModel.h

Adding related objects to the data model

– addRelative:

Relates the passed-in data model object to the receiver using the default relation type.

- (void)addRelative:(nonnull MBDataModel *)relative

Parameters

relative

The data model object to add as a relative to the receiver.

Declared In

MBDataModel.h

– addRelative:withRelationType:

Relates the passed-in data model object to the receiver using the specified relation type.

- (void)addRelative:(nonnull MBDataModel *)relative withRelationType:(nonnull NSString *)relation

Parameters

relative

The data model object to add as a relative to the receiver.
relation

The name of the relation type by which relative will be added to the receiver.

Declared In

MBDataModel.h

– addRelatives:

Each MBDataModel returned by the enumeration is added to the receiver as a relative using the default relation type.

- (void)addRelatives:(nonnull NSObject<NSFastEnumeration> *)relatives

Parameters

relatives

An enumeration of MBDataModel instances to add as relatives to the receiver.

Declared In

MBDataModel.h

– addRelatives:withRelationType:

Each MBDataModel returned by the enumeration is added to the receiver as a relative using the specified relation type.

- (void)addRelatives:(nonnull NSObject<NSFastEnumeration> *)relatives withRelationType:(nonnull NSString *)relation

Parameters

relatives

An enumeration of MBDataModel instances to add as relatives to the receiver.
relation

The name of the relation type by which the relatives will be added to the receiver.

Declared In

MBDataModel.h

Building out the data model from an XML structure

– addRelativeOfClass:forElement:

Creates a data model object of the given class from the specified XML element, and adds it to the receiver as a relative using the XML tag name of the element as the relation type.

- (void)addRelativeOfClass:(nonnull Class)relCls forElement:(nonnull RXMLElement *)element

Parameters

relCls

The class of MBDataModel to create.
element

The XML element that will be used to populate the newly-created data model object.

Declared In

MBDataModel.h

– addRelativeOfClass:withRelationType:forElement:

Creates a data model object of the given class from the specified XML element, and adds it to the receiver as a relative using the specified relation type.

- (void)addRelativeOfClass:(nonnull Class)relCls withRelationType:(nullable NSString *)relation forElement:(nonnull RXMLElement *)element

Parameters

relCls

The class of MBDataModel to create.
relation

The relation type to use for adding the newly-created data model object to the receiver. If nil, the receiver’s default relation type is used.
element

The XML element that will be used to populate the newly-created data model object.

Declared In

MBDataModel.h

– addRelativeOfClass:forFirstChildOf:havingTag:

Creates a data model object of the given class from the first child element of the passed-in XML having the given XML tag, and adds it to the receiver as a relative using tagName as the relation type.

- (void)addRelativeOfClass:(nonnull Class)relCls forFirstChildOf:(nonnull RXMLElement *)container havingTag:(nonnull NSString *)tagName

Parameters

relCls

The class of MBDataModel to create.
container

The XML element whose first child element having the tag name tagName will be used to populate the newly-created data model object.
tagName

The tag name of the first child element of container to use for populating the newly-created data model object.

Discussion

If container has no child element with the tag tagName, no action is taken.

Declared In

MBDataModel.h

– addRelativeOfClass:withRelationType:forFirstChildOf:havingTag:

Creates a data model object of the given class from the first child element of the passed-in XML having the given XML tag, and adds it to the receiver as a relative using relation as the relation type.

- (void)addRelativeOfClass:(nonnull Class)relCls withRelationType:(nullable NSString *)relation forFirstChildOf:(nonnull RXMLElement *)container havingTag:(nonnull NSString *)tagName

Parameters

relCls

The class of MBDataModel to create.
relation

The relation type to use for adding the newly-created data model object as a relative to the receiver. If nil, the receiver’s default relation type is used.
container

The XML element whose first child element having the tag name tagName will be used to populate the newly-created data model object.
tagName

The tag name of the first child element of container to use for populating the newly-created data model object.

Discussion

If container has no child element with the tag tagName, no action is taken.

Declared In

MBDataModel.h

– addRelativeOfClass:forEachChildOf:

Constructs a data model object of the given class for each child element of the passed-in XML. Each data model object instantiated is added to the receiver as a relative using the default relation type.

- (void)addRelativeOfClass:(nonnull Class)relCls forEachChildOf:(nonnull RXMLElement *)container

Parameters

relCls

The class of MBDataModel to create.
container

The XML element whose child elements will be used to populate any newly-created data model objects.

Discussion

If container has no children, no action is taken.

Declared In

MBDataModel.h

– addRelativeOfClass:withRelationType:forEachChildOf:

Constructs a data model object of the given class for each child element of the passed-in XML. Each data model object instantiated is added to the receiver as a relative using the specified relation type.

- (void)addRelativeOfClass:(nonnull Class)relCls withRelationType:(nullable NSString *)relation forEachChildOf:(nonnull RXMLElement *)container

Parameters

relCls

The class of MBDataModel to create.
relation

The relation type to use for adding the newly-created data model object as a relative to the receiver. If nil, the receiver’s default relation type is used.
container

The XML element whose child elements will be used to populate any newly-created data model objects.

Discussion

If container has no children, no action is taken.

Declared In

MBDataModel.h

– addRelativeOfClass:forEachChildOf:havingTag:

Constructs a data model object of the given class for each child element of the passed-in XML that has the specified tag name. Each data model object instantiated is added to the receiver as a relative using tagName as the relation type.

- (void)addRelativeOfClass:(nonnull Class)relCls forEachChildOf:(nonnull RXMLElement *)container havingTag:(nonnull NSString *)tagName

Parameters

relCls

The class of MBDataModel to create.
container

The XML element whose child elements will be used to populate any newly-created data model objects.
tagName

The tag name of the child elements of container to use for populating any newly-created data model objects.

Discussion

If container has no child element with the tag tagName, no action is taken.

Declared In

MBDataModel.h

– addRelativeOfClass:withRelationType:forEachChildOf:havingTag:

Constructs a data model object of the given class for each child element of the passed-in XML that has the specified tag name. Each data model object instantiated is added to the receiver as a relative using relation as the relation type.

- (void)addRelativeOfClass:(nonnull Class)relCls withRelationType:(nullable NSString *)relation forEachChildOf:(nonnull RXMLElement *)container havingTag:(nonnull NSString *)tagName

Parameters

relCls

The class of MBDataModel to create.
relation

The relation type to use for adding the newly-created data model object as a relative to the receiver. If nil, the receiver’s default relation type is used.
container

The XML element whose child elements will be used to populate any newly-created data model objects.
tagName

The tag name of the child elements of container to use for populating any newly-created data model objects.

Discussion

If container has no child element with the tag tagName, no action is taken.

Declared In

MBDataModel.h

Building out the data model automatically

– relationTypeForTag:

Returns the relation type to use when automatically creating related data objects from XML.

- (nullable NSString *)relationTypeForTag:(nonnull NSString *)tagName

Parameters

tagName

The XML tag name for which the relation type is desired.

Return Value

The relation type. Implementations may return nil if they do not support the specified tag name.

Discussion

The default implementation returns the default relation type for the receiver’s class.

Note: This method is called from within the base implementation of populateDataModelFromXML:. Subclasses may override that method to perform custom XML handling, in which case this method may not be called.

Declared In

MBDataModel.h

– shouldAutomaticallyAddRelativeOfType:fromTag:

Determines whether the receiver should attempt to add an automatically-created related object for the given relation type.

- (BOOL)shouldAutomaticallyAddRelativeOfType:(nonnull NSString *)relationType fromTag:(nonnull NSString *)tagName

Parameters

relationType

The relation type.
tagName

The XML tag name for which the related object may be created.

Return Value

YES if a relative should be automatically added for the given relation type; NO otherwise. The default implementation returns YES.

Discussion

This mechanism allows MBDataModel implementations to limit the number of related objects of a given type.

Note: This method is called from within the base implementation of populateDataModelFromXML:. Subclasses may override that method to perform custom XML handling, in which case this method may not be called.

Declared In

MBDataModel.h

– implementingClassForRelativeOfType:fromTag:

Called to query the implementation to determine the Class that should be used for instances of related objects that are created automatically from XML by the MBDataModel superclass.

- (nullable Class)implementingClassForRelativeOfType:(nonnull NSString *)relationType fromTag:(nonnull NSString *)tagName

Parameters

relationType

The relation type.
tagName

The XML tag name for which the related object is being created.

Return Value

The Class to create for the related object, or nil if the receiver does not support the specified relation type. If a non-nil value is returned, the class must be a type of MBDataModel. The default implementation returns [MBDataModel class].

Discussion

Note: This method is called from within the base implementation of populateDataModelFromXML:. Subclasses may override that method to perform custom XML handling, in which case this method may not be called.

Declared In

MBDataModel.h

Removing related objects from the data model

– removeRelative:

Removes from the receiver all instances of the given relative from any relation type in which it occurs.

- (void)removeRelative:(nonnull MBDataModel *)relative

Parameters

relative

The data model relative to remove.

Declared In

MBDataModel.h

– removeRelative:withRelationType:

Removes from the receiver any instance of the given relative from the specified relation.

- (void)removeRelative:(nonnull MBDataModel *)relative withRelationType:(nonnull NSString *)relation

Parameters

relative

The data model relative to remove.
relation

The name of the relation type for which relative should be removed.

Declared In

MBDataModel.h

Notification of changes to the set of relatives

– dataModelDidAddOrRemoveRelatives

Notifies the receiver that one or more relatives have been added or removed

- (void)dataModelDidAddOrRemoveRelatives

Discussion

Note: Subclasses overriding this method must always call super.

Declared In

MBDataModel.h