README
¶
config-xml
Read XML configuration through config — with no added dependency
Part of the phpboyscout Go toolkit — small, framework-free Go modules extracted from go-tool-base. Documented with the parent module at config.go.phpboyscout.uk
config reads and writes only YAML. Every other file
format is a sibling module like this one — and this one adds nothing to your dependency
graph, because it reads XML with the standard library.
import (
"gitlab.com/phpboyscout/go/config"
configxml "gitlab.com/phpboyscout/go/config-xml"
)
store, err := config.NewStore(ctx,
config.WithFiles(fsys, "/etc/app.yaml"), // YAML, the default
config.WithBackend(configxml.New(fsys, "/etc/log4j.xml")), // outranks it
)
Attributes and elements share one namespace
Real configuration XML is attribute-heavy — log4j and .NET appSettings are almost entirely
attributes — so an attribute reads by the same dotted path a child element would:
<server port="8080"><host>localhost</host></server>
gives server.port and server.host. A repeated element becomes a slice, and a single one a
scalar that the read path promotes to a one-element slice when a consumer asks for one — so
declare repeatable elements as slices and one entry or many both decode.
What it refuses, at load
Two shapes cannot be a value tree, and are refused with config.ErrBackendUnsafe naming the
element rather than silently dropping half of it:
- an attribute and a child element that share a name — two candidates for one key, no basis to choose;
- an element with both text content and attributes or children — it is at once a scalar and a map, and a key cannot be both.
Read-only
No Go library round-trips XML preserving formatting and comments, so this module reads and does not write. A write to a key an XML layer defines is routed past it and reported shadowed rather than failing.
What it costs
Only the config graph — encoding/xml is standard library, so there is no parser module. An
allowlist test asserts it, so an unforeseen transitive addition fails the build. No filesystem
library: you supply the config.FS.
License
See LICENSE.
Documentation
¶
Overview ¶
Package configxml reads XML configuration through the config codec seam.
It is a sibling of the config core, not part of it: a consumer who needs XML takes this module, and one who does not pays nothing for it. The core reads and writes only YAML; every other file format is a module like this one. This one adds no dependency at all — it reads XML with the standard library.
config.NewStore(ctx, config.WithFiles(fsys, "/etc/app.yaml"), // YAML, the default config.WithBackend(configxml.New(fsys, "/etc/log4j.xml")), )
Attributes and elements share one namespace ¶
Real configuration XML is attribute-heavy — log4j and .NET appSettings are almost entirely attributes — so an attribute reads by the same dotted path a child element would:
<server port="8080"><host>localhost</host></server>
gives server.port and server.host. A repeated element becomes a slice, and a single one a scalar that the read path promotes to a one-element slice when a consumer asks for one — so declare repeatable elements as slices and a single or many entries both decode.
What it refuses, at load ¶
Two shapes cannot be represented as a value tree, and are refused with config.ErrBackendUnsafe naming the element rather than silently discarding half of it:
- an attribute and a child element that share a name — the module has two candidates for one key and no basis to choose;
- an element with both attributes or children and its own text content — it is simultaneously a scalar and a map, and a key cannot be both.
Read-only ¶
No Go library round-trips XML preserving formatting and comments, so this module reads and does not write. A write to a key an XML layer defines is routed past it and reported shadowed rather than failing. See the non-YAML format adapters spec, D21.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Codec ¶ added in v0.2.0
type Codec struct{}
Codec decodes an XML document into layer values. New uses it, and it is exported so a backend adapter can reuse it as a value decoder — a Consul or etcd key whose value is an XML document, decoded into a subtree via that adapter's WithValueCodec option. It is a config.Codec.
It is a named type carrying only Decode: XML is read-only (nothing round-trips it), so unlike the writable formats it is not shaped to gain editing methods.
Source Files