ObjFW  Diff

/**
 * @class OFXMLElement OFXMLElement.h ObjFW/OFXMLElement.h
 *
 * @brief A class which stores an XML element.
 */
@interface OFXMLElement: OFXMLNode
{
	OFString *_name, *_Nullable _namespace;
	OFMutableArray OF_GENERIC(OFXMLAttribute *) *_Nullable _attributes;
	OFMutableDictionary OF_GENERIC(OFString *, OFString *) *_Nullable
	    _namespaces;
	OFMutableArray OF_GENERIC(OFXMLNode *) *_Nullable _children;
	OF_RESERVE_IVARS(OFXMLElement, 4)
}

#ifndef __cplusplus
@property OF_NULLABLE_PROPERTY (copy, nonatomic) OFString *namespace;
#else
@property OF_NULLABLE_PROPERTY (copy, nonatomic,
    getter=namespace, setter=setNamespace:) OFString *nameSpace;
#endif







/**
 * @brief An array with the attributes of the element.
 */
@property OF_NULLABLE_PROPERTY (readonly, nonatomic)
    OFArray OF_GENERIC(OFXMLAttribute *) *attributes;

/**

 * @return A new autoreleased OFXMLElement with the specified element name,
 *	   namespace and value
 */
+ (instancetype)elementWithName: (OFString *)name
		      namespace: (nullable OFString *)nameSpace
		    stringValue: (nullable OFString *)stringValue;










/**
 * @brief Parses the string and returns an OFXMLElement for it.
 *
 * @param string The string to parse
 * @return A new autoreleased OFXMLElement with the contents of the string
 * @throw OFMalformedXMLException The XML was malformed
 * @throw OFUnboundPrefixException A prefix was used that was not bound to any
 *				   namespace
 * @throw OFInvalidEncodingException The XML is not in the encoding it specified
 */
+ (instancetype)elementWithXMLString: (OFString *)string;

/**
 * @brief Parses the specified stream and returns an OFXMLElement for it.
 *
 * @param stream The stream to parse
 * @return A new autoreleased OFXMLElement with the contents of the specified
 *	   stream
 * @throw OFMalformedXMLException The XML was malformed
 * @throw OFUnboundPrefixException A prefix was used that was not bound to any
 *				   namespace
 * @throw OFInvalidEncodingException The XML is not in the encoding it specified
 */
+ (instancetype)elementWithStream: (OFStream *)stream;

- (instancetype)init OF_UNAVAILABLE;

/**
 * @brief Initializes an already allocated OFXMLElement with the specified name.

 *
 * @param name The name for the element
 * @param nameSpace The namespace for the element
 * @return An initialized OFXMLElement with the specified element name and
 *	   namespace
 */
- (instancetype)initWithName: (OFString *)name
		   namespace: (nullable OFString *)nameSpace
    OF_DESIGNATED_INITIALIZER;

/**
 * @brief Initializes an already allocated OFXMLElement with the specified name,
 *	  namespace and value.
 *
 * @param name The name for the element
 * @param nameSpace The namespace for the element
 * @param stringValue The value for the element
 * @return An initialized OFXMLElement with the specified element name,
 *	   namespace and value
 */
- (instancetype)initWithName: (OFString *)name
		   namespace: (nullable OFString *)nameSpace
		 stringValue: (nullable OFString *)stringValue;











/**
 * @brief Parses the string and initializes an already allocated OFXMLElement
 *	  with it.
 *
 * @param string The string to parse
 * @return An initialized OFXMLElement with the contents of the string
 * @throw OFMalformedXMLException The XML was malformed
 * @throw OFUnboundPrefixException A prefix was used that was not bound to any
 *				   namespace
 * @throw OFInvalidEncodingException The XML is not in the encoding it specified
 */
- (instancetype)initWithXMLString: (OFString *)string;

/**
 * @brief Parses the specified stream and initializes an already allocated
 *	  OFXMLElement with it.
 *
 * @param stream The stream to parse
 * @return An initialized OFXMLElement with the contents of the specified stream
 * @throw OFMalformedXMLException The XML was malformed
 * @throw OFUnboundPrefixException A prefix was used that was not bound to any
 *				   namespace
 * @throw OFInvalidEncodingException The XML is not in the encoding it specified
 */
- (instancetype)initWithStream: (OFStream *)stream;



/**
 * @brief Sets a prefix for a namespace.
 *
 * @param prefix The prefix for the namespace
 * @param nameSpace The namespace for which the prefix is set
 */
- (void)setPrefix: (OFString *)prefix forNamespace: (OFString *)nameSpace;

- (void)removeChild: (OFXMLNode *)child;

/**
 * @brief Removes the child at the specified index.
 *
 * @param index The index of the child to remove
 */

- (void)removeChildAtIndex: (size_t)index;

/**
 * @brief Replaces the first child that is equal to the specified OFXMLNode
 *	  with the specified node.
 *
 * @param child The child to replace
 * @param node The node to replace the child with
 */

- (void)replaceChildAtIndex: (size_t)index withNode: (OFXMLNode *)node;

/**
 * @brief Returns all children that have the specified namespace.
 *
 * @return All children that have the specified namespace
 */
- (OFArray OF_GENERIC(OFXMLElement *) *)
    elementsForNamespace: (nullable OFString *)elementNS;

/**
 * @brief Returns the first child element with the specified name.
 *
 * @param elementName The name of the element
 * @return The first child element with the specified name
 */
- (nullable OFXMLElement *)elementForName: (OFString *)elementName;

/**
 * @brief Returns the child elements with the specified name.
 *
 * @param elementName The name of the elements
 * @return The child elements with the specified name
 */
- (OFArray OF_GENERIC(OFXMLElement *) *)
    elementsForName: (OFString *)elementName;

/**
 * @brief Returns the first child element with the specified name and namespace.
 *
 * @param elementName The name of the element
 * @param elementNS The namespace of the element
 * @return The first child element with the specified name and namespace

 * @param elementName The name of the elements
 * @param elementNS The namespace of the elements
 * @return The child elements with the specified name and namespace
 */
- (OFArray OF_GENERIC(OFXMLElement *) *)
    elementsForName: (OFString *)elementName
	  namespace: (nullable OFString *)elementNS;

/**
 * @brief Returns an OFString representing the OFXMLElement as an XML string
 *	  with the specified indentation per level.
 *
 * @param indentation The indentation per level
 * @return An OFString representing the OFXMLNode as an XML string with
 *	   indentation
 * @throw OFUnboundNamespaceException The node uses a namespace that was not
 *				      bound to a prefix in a context where it
 *				      needs a prefix
 */
- (OFString *)XMLStringWithIndentation: (unsigned int)indentation;

/**
 * @brief Returns an OFString representing the OFXMLElement as an XML string
 *	  with the specified default namespace and indentation per level.
 *
 * @param defaultNS The default namespace
 * @param indentation The indentation per level
 * @return An OFString representing the OFXMLNode as an XML string with
 *	   indentation
 * @throw OFUnboundNamespaceException The node uses a namespace that was not
 *				      bound to a prefix in a context where it
 *				      needs a prefix
 */
- (OFString *)XMLStringWithDefaultNamespace: (OFString *)defaultNS
				indentation: (unsigned int)indentation;
@end

OF_ASSUME_NONNULL_END

#import "OFXMLElement+Serialization.h"