XML Support

[GregoryTravis]

Phase 1: very basic interface

Assumptions I am making in this design, but which I am not married to:

• We do not need to match the naming convention / usage patterns of the underlying Java interface (such as sibling accessors)
• We do not want an XML_Node class which can contain both XML elements and basic values like string, integer, and so on
• We do not want classes related to a node class, such as XML_Node_List

type XML_Document
    ## Static methods
    from_file : Text -> XML_Document ! XML_Parse_Error
    from_string : Text -> XML_Document ! XML_Parse_Error
    ## Object methods
    get_root : XML -> XML_Element

type XML_Format
    # Implements the File_Format interface, using XML_Document.from_file

type XML_Element
    ## Object methods

    ## Gets the tag of an xml element.

       Example:
           XML_Document.from_string '<foo>hello</foo>' . at 0 . tag
           # => "foo"
    tag : Text

    ## Gets a list of the attribute names of an xml element.

       Example:
           XML_Document.from_string '<foo bar="one">hello</foo>' . at 0 . attributes
           # => ["bar"]
    attributes : Map Text Text

    ## Gets an attribute of an xml element.

       Example:
           XML_Document.from_string '<foo bar="one">hello</foo>' . at 0 . attribute "bar"
           # => "one"
    attribute : Text -> Text

    ## Gets the children of an xml element.

       Example:
           XML_Document.from_string '<foo><baz>hello</baz></foo>' . at 0 . children
           # => [XML_Document.from_string "<baz>hello</baz>"]
    children : Vector XML_Element

    ## Gets the number children of an xml element.

       Example:
           XML_Document.from_string '<foo><baz>hello</baz></foo>' . at 0 . num_children
           # => 1
    num_children : Integer

    ## Gets a child of an xml element.

       Example:
           XML_Document.from_string '<foo><baz>hello</baz></foo>' . at 0 . at 0
           # => XML_Document.from_string "<baz>hello</baz>"
    at : Text | Integer -> XML_Element

    ## Gets the non-markup contents of the element.

       Example:
           XML_Document.from_string '<foo>hello</foo>' . at 0 . tag
           # => "hello"
    text : Text

    ## Gets elements matching a given tag name

       Example:
           XML_Document.from_string '<foo><baz>hello</baz></foo>' . get_elements_by_tag_name "baz"
           # => [XML_Document.from_string "<baz>hello</baz>"]
    get_elements_by_tag_name : Text -> Vector XML_Element

Table.from_objects
    # Add case for XML_Document

Phases 2 - N

After implementing Phase 1, I will know more about what needs to be done for the following:

• Document construction
• Document transformation
• Schemas + validation
• XPath
• DOMParser (produces parse tree)
• SAXParser (incremental parser)
• Properties files

References

• Module Summary

[radeusgd]

1. I think given the direction started in S3 Read Access, Input Stream based reading #7776, we should prefer a read_stream instead of a from_file.
2. I cannot see a definition for type XML referenced in get_root : XML -> XML_Element, I assume it is a member method on XML_Document? Then it should probably be just root : XML_Element; I'd also avoid the get_ prefix - but that is just my personal preference.

[radeusgd]

3. What is the expected return type of from_string? The signature suggests XML_Document but the example XML_Document.from_string '<foo>hello</foo>' . at 0 . tag suggests it directly returns an XML_Element. Or do we have some shorthand? Like XML_Element.from (that:XML_Document) = that.get_root? would be good to clarify.
4. nitpick: XML_Document.from_string '<foo bar="one">hello</foo>' . at 0 . attributes should yield a Map according to the type signature, but example yields a vector of keys. So what is the desired behaviour here? I think Map seems better.
5. XML_Document and XML_Element seem to be used interchangeably. Maybe indeed we should have just one type instead of 2? What's the purpose of separate XML_Document?
6. get_elements_by_tag_name needs more clarification. What is its purpose? Is it like lxml's find? (Maybe then also the name should start with find instead) Does it search in just the children or all descendants? 'How' recursive is it? If I look for tags a and I have an element <a> containing another <a> as one of its children/descendants, is only the top one returned or both the top one and the inner one?

[jdunkerley]

Check issue of duplicate attributes in XML.

For V1:

• strip comments, but might want to be able to include later.
• What happens with namespaces? Do we need in the element?
• No xml schema validation.
• What is the text of: Some silly ass decided this was legit.

type XML_Document
    ## Static methods
    from_file : Text -> XML_Document ! XML_Parse_Error
    from_string : Text -> XML_Document ! XML_Parse_Error

    ## Object methods
    root_element : XML_Element
    root_element self = ...

type XML_Format
    # Implements the File_Format interface, using XML_Document.from_file
    # Include mime type (with encoding??) and from_stream

type XML_Element
    ## Object methods

    ## Gets the tag of an xml element.

       Example:
           XML_Document.from_string '<foo>hello</foo>' . root_element . at 0 . tag
           # => "foo"
    name : Text

    ## Gets a map of the attributes of an xml element.

       Example:
           XML_Document.from_string '<foo bar="one">hello</foo>' . at 0 . attributes
           # => Map.from_vector [["bar", "one"]]
    attributes : Map Text Text

    ## Gets the child nodes of an xml element.

       Example:
           XML_Document.from_string '<foo><baz>hello</baz></foo>' . at 0 . children
           # => [XML_Document.from_string "<baz>hello</baz>"]
    children : Vector XML_Element

    ## Gets the non-markup contents of the element.

       Example:
           XML_Document.from_string '<foo>hello</foo>' . at 0 . tag
           # => "hello"
    text : Text

    ## Gets the raw XML of the element (including tag, attributes and contents).
    outer_xml : Text

    ## Gets the raw XML contents of the element.
    inner_xml : Text

    ## Gets a child or attribute of an xml element. ("@foo" for attributes")
       Integer is child index.
       Text should support XPath.

       Example:
           XML_Document.from_string '<foo><baz>hello</baz></foo>' . at 0 . at 0
           # => XML_Document.from_string "<baz>hello</baz>"
    at : Text | Integer -> XML_Element | Text ! Key_Not_Found

    ## Gets a child of an xml element.

       Example:
           XML_Document.from_string '<foo><baz>hello</baz></foo>' . at 0 . at 0
           # => XML_Document.from_string "<baz>hello</baz>"
    get : Text | Integer -> Any -> XML_Element

    ## Gets the number children of an xml element.

       Example:
           XML_Document.from_string '<foo><baz>hello</baz></foo>' . at 0 . num_children
           # => 1
    length : Integer

    ## Gets elements matching a given tag name

       Example:
           XML_Document.from_string '<foo><baz>hello</baz></foo>' . get_elements_by_tag_name "baz"
           # => [XML_Document.from_string "<baz>hello</baz>"]
    get_elements_by_tag_name : Text -> Vector XML_Element

[jdunkerley]

Closing discussion as we have started implementing this design.