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:
- requiredAttributes
- supportedAttributes
- unsupportedAttributes
- validateAttributes
- validateAsRelativeOf:relatedBy:dataModelRoot:
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 |
---|
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 |
---|
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 |
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- |
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- |
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- |
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 |
---|
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 |
---|---|
errPtr |
If non- |
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
|
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 |
---|---|
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 |
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
|
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 NSString
s 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
|
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
|
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
|
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
|
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 |
---|---|
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 |
The new name for the attribute currently known as |
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 NSString
s 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 |
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 |
---|
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 |
---|---|
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 |
---|---|
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 |
---|---|
relation |
The relation type to use for adding the newly-created
data model object to the receiver. If |
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 |
---|---|
container |
The XML element whose first child element having
the tag name |
tagName |
The tag name of the first child element of |
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 |
---|---|
relation |
The relation type to use for adding the newly-created
data model object as a relative to the receiver. If |
container |
The XML element whose first child element having
the tag name |
tagName |
The tag name of the first child element of |
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 |
---|---|
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 |
---|---|
relation |
The relation type to use for adding the newly-created
data model object as a relative to the receiver. If |
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 |
---|---|
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 |
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 |
---|---|
relation |
The relation type to use for adding the newly-created
data model object as a relative to the receiver. If |
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 |
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 |
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