Skip to content

Latest commit

 

History

History
146 lines (109 loc) · 4.79 KB

README.md

File metadata and controls

146 lines (109 loc) · 4.79 KB
Raw

xmlwriter: functions module for shellfire

This module provides a simple framework for writing XML to standard out in a shellfire application.

Compatibility

Overview

The functions are trivial to use. For example, to create the following XML (without line feeds, in reality):-

<?xml version="1.0" charset="UTF-8"?>
<!DOCTYPE comps PUBLIC "-//CentOS//DTD Comps info//EN" "comps.dtd">
<comps>
	<group project="sw&lt;&gt;ddle">
		<id>groupId</id>
		<name>groupName</name>
		<description>All available packages for 'groupName'</description>
		<default value="false"/>
		<uservisible value="false">TEXT</uservisible>
	</group>
</comps>

Use the code:-

xmlwriter_declaration '1.0' 'UTF-8' 'no'
xmlwriter_dtd comps "-//CentOS//DTD Comps info//EN"
xmlwriter_open comps
	xmlwriter_open group project 'sw<>ddle'
		xmlwriter_leaf id "groupId"
		xmlwriter_leaf name "groupName"
		xmlwriter_leaf description "All available packages for 'groupName'"
		xmlwriter_leaf default value false
		xmlwriter_leaf uservisible value false TEXT
	xmlwriter_close group
xmlwriter_close comps

To use namespaces in XML, simply make the node name the namespace prefix, eg namespace:comps. We don't care one way or the other.

Importing

To import this module, add a git submodule to your repository. From the root of your git repository in the terminal, type:-

mkdir -p lib/shellfire
cd lib/shellfire
git submodule add "https://github.com/shellfire-dev/xmlwriter.git"
cd -
git submodule init --update

You may need to change the url https://github.com/shellfire-dev/xmlwriter.git above if using a fork.

You will also need to add paths - include the module paths.d.

Namespace xmlwriter

This namespace exposes helper functions to create an XML document.

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn xmlwriter

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn xmlwriter
	…
}

Functions

xmlwriter_declaration

Parameter Value Optional
version XML version. Version 1.0 is preferred by most consumers. No
encoding IANA content type; UTF-8 should always be specified. No
standalone Boolean. No

Writes an XML declaration to standard out.

xmlwriter_dtd

Parameter Value Optional
name DTD name No
path DTD path No

Writes an XML DTD to standard out.

xmlwriter_open

Parameter Value Optional
nodeName XML node name No
… Attribute Name-Value string pairs Yes

Writes an XML opening tag of nodeName, with attributes as the XML encoded form of the UTF-8 encoded strings of attribute and value to standard out.

xmlwriter_close

Parameter Value Optional
nodeName XML node name No

Writes an XML closing tag of nodeName to standard out.

xmlwriter_leaf

Parameter Value Optional
nodeName XML node name No
… Attribute Name-Value string pairs Yes
text Node text value Yes

Writes a leaf XML node of nodeName, with attributes as the XML encoded form of the UTF-8 encoded strings of attribute and value. If text is supplied, writes it as the text content of the node (even if empty) to standard out. Otherwise writes a self-closed node to standard out.