minixml

minixml is a package for building xml documents in R.

`minixml` vs `xml2`

xml2 is a fantastic package for parsing a pre-existing XML file and navigating through it, slicing it etc.

minixml is focussed on creating XML documents by assembling nodes with attributes in a programmatic fashion.

Overview

Need to build	R6 object	alternate initialisation
XML elements	`XMLElement$new()`	`xml_elem()`
XML document	`XMLDocument$new()`	`xml_doc()`

Quick Examples

XML Entity	code	result
XML elements	`XMLElement$new('info', "Hello there")`	`<info>Hello there</info>`
XML elements	`xml_elem('info', 'Hello')$update(date = '2019')`	`<info date="2019">Hello</info>`
XML document	`this_xml <- XMLDocument$new('core'); this_xml$add('info', 'hello')`	`<core><info>hello</info></core>`

Installation

You can install minixml from GitHub with:

# install.packages("devtools")
devtools::install_github("coolbutuseless/minixml")

Interface

Individual elements can be created in a number of ways.
- As a stand-alone element
  - new_elem <- XMLElement$new('info', type = 'meta')
  - new_elem <- xml_elem('info', type = 'meta')
- As a sub-element of an existing document or element - the element is created, added to the parent document (or element) and returned.
  - doc <- XMLDocument$new('xx'); new_elem <- doc$add('info', type = 'meta')
  - elem <- XMLElement$new('xxx'); new_elem <- elem$add('info', type = 'meta')
$add() creates an element and adds it to the parent (and returns it)
- new_elem <- doc$add('info', type = 'meta')
$append() appends the given elements as children
- new_elem <- xml_elem('info', type = 'meta'); doc$append(new_elem, ...)
$new(name, ...), $update(...) and $add(name, ...) all accept ... where
- named arguments are added as attributes of this node
- unnamed argument are added as children of this node

Simple example

doc <- xml_elem("thing")
doc$add('node')$
  update(style = "color: blue;")$
  add('mytag', "Some example text.")

doc
<thing>
  <node style="color: blue;">
    <mytag>
      Some example text.
    </mytag>
  </node>
</thing>

Parsing XML into a `minixml` document

minixml uses xml2 to parse XML text (or file) into a minixml document.

my_xml <- "<eg>Node contents</eg>"
doc <- minixml::parse_xml_elem(my_xml)
doc$update(x = 1, y = 2)$
  add(name = 'inner', 'inner contents')

doc
<eg x="1" y="2">
  Node contents
  <inner>
    inner contents
  </inner>
</eg>

More complex example: Creating an XML `X3D` 3d object

X3D is an XML-based 3D object format that is the successor to VRML.

In this example, we’ll build a simple 3D cube to view in the browser.

x3d <- xml_elem("x3d", width = "300px", height="200px")
shape <- x3d$
  add("scene")$
  add("shape")

shape$add("appearance")$add("material", diffuseColor = "0 0 1")
shape$add("box")

x3d
<x3d width="300px" height="200px">
  <scene>
    <shape>
      <appearance>
        <material diffuseColor="0 0 1" />
      </appearance>
      <box />
    </shape>
  </scene>
</x3d>

View the object

To view the X3D object, include it in an HTML document with the x3dom.js javascript.

The following code will run in an R session as an interactive 3d object browser. On github you’ll just see a short gif.

html <- glue::glue("
<html> 
<head> 
  <script type='text/javascript' src='http://www.x3dom.org/download/x3dom.js'> </script> 
</head> 
<body>     {x3d}     </body> 
</html>")

htmltools::html_print(HTML(html))

Introducing the `minixml` package for creating XML documents in R