Package mmmc contains generic Golang XML stuff:
names, attributes, tags, elements, trees, files, documents.
Files in this directory use Markdown, so use `godoc2md` on 'em.
We make our own versions of Golang XML structures so that we can give
them sensible new names and we can define our own methods for them.
We also use a couple of shortened names (Att *Attribute*, Elm *Element*)
to keep code readable. )
### Method naming
- `NewFoo(..)` always allocates memory.
- `Echo()` echoes an object back in source XML form, but normailzed.
- `EchoCommented()` also outputs XML source form, but possibly with
additional annotations added by processing.
- `String()“ outputs a form that is useful for development and
debugging but cannot be processed by an XML parser.
### About encoding/decoding and XML mixed content
When working with XML we can generally distinguish between two types of files:
- Files containing record-oriented data - expressed using XML elements
- Files containing natural language documents - also expressed using
- Files containing validation rules - generally expressed as XSD,
RNG, or DTD. It is interesting to note that DTDs actually obey the
same syntax rules as the other two; the typical file extensions
(`.dtd .mod`) are helpful to humans but are not required by a
parser that fully understands XML syntax.
Package gtree defines low-level structures for Generic Golang XML analysis,
structures that are built directly atop (or map'd directly to) Golang's own
XML structures. We do this for three reasons:
- So that we can define our own helper methods in our own golang namespace;
- Cos golang's XML package uses lousy naming (`Name Name`, anyone ?);
- Cos golang's XML is written for XML data records, not for mixed content.
This repo implements a protocol stack that goes:
- the input text file (i.e. XML or other markup)
- package encoding/xml (golang's XML package)
- package gparse (low-level stuff)
- package gfile (deep analysis of individual markup files)
- package mmmc (processing of heterogeneous markup files)
In general, all go files in this protocol stack should be organised as: <br/>
- struct definition()
- constructors (named `New*`)
- printf stuff (Raw(), Echo(), String())
Some characteristic methods:
- Raw() returns the original string passed from the golang XML parser
- Echo() returns a string of the item in normalised form, altho the
presence of terminating newlines is not uniform
String() returns a string suitable for runtime nonitoring and debugging
NOTE:1280 the use of shorthand in variable names: Doc, Elm, Att.
NOTE:1220 that we store non-nil namespaces with a colon appended, for easy output.
NOTE:1230 that we use `godoc2md`, so we can use Markdown in these code comments.
NOTE:1030 that like other godoc comments, this package comment must be *right*
above the target statement (`package`) if it is to be included by `godoc2md`.