NAME
Apachish - Apachish configuration format specification
VERSION
This document describes version 0.9.0 of Apachish (from Perl distribution Apachish), released on 2015-12-11.
SPECIFICATION VERSION
0.9
STATUS
Specification is still rather in flux. Backwards compatibility is not guaranteed between 0.9.x releases.
ABSTRACT
Apachish is a configuration file format that is mostly compatible with the Apache webserver's file format.
NOTATION
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
RATIONALE
Apachish is the configuration format to complement IOD and is meant for configuration that needs to be nested. The main goal, like IOD, is to make it easy to have a round-trip parser/writer for it. That way, the configuration can be written/modified by software without destroying formatting/comments.
SPECIFICATION
A configuration is a text file containing a sequence of lines. Encoding MUST be UTF-8. Each line is either a blank line, a comment line, a directive line, open context line, or close context line. Parsing is done line-by-line and in a single pass.
A context surrounds directives and can also contain subcontext in a tree-like fashion. Contexts cannot overlap one another.
Blank line
A blank line is a line containing zero or more whitespaces only. It is ignored.
Comment line
A comment line begins with # as it's first nonblank character.
<ws>* |"#" <COMMENT>Examples:
# this is a commentDirective line
<ws>* <NAME> (<ws>+ <ARGUMENT>)+NAME can only contain alphanumeric (A-Z, a-z, 0-9) characters or underscores. Arguments is a sequence of one or more non-whitespace characters except double quotes. Arguments can contain whitespace if it is quoted. They can also contain double quotes using escaping with backslash (\). A literal backslash is written using \\. To express an empty argument, you also use double quotes.
Unlike in Apache, currently a directive line cannot be continued to another line using backslash.
A directive line cannot contain comments.
Examples:
Foo arg1 arg2 "arg3 contains spaces, \"quotes\", and backslash \\"
Bar ""Directives in configuration are case-insensitive, but the arguments are case-sensitive.
Open context line
<ws>* "<" <NAME> (<ws>+ <ARGUMENT>)* ">"NAME can only contain alphanumeric (A-Z, a-z, 0-9) characters or underscores. Arguments are also like in directive names except they also cannot contain closing bracket (>) characters unless they are quoted.
Examples:
<Context1>
<Context1 ~arg1>
<Context1 "arg1>">Context names are case-insensitive, but its arguments are case-sensitive.
Close context line
<ws>* "</" <NAME> ">"Examples:
</Context1>SEE ALSO
An alternative format for simpler/flat configuration: IOD
HOMEPAGE
Please visit the project's homepage at https://metacpan.org/release/Apachish.
SOURCE
Source repository is at https://github.com/perlancar/perl-Apachish.
BUGS
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Apachish
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
AUTHOR
perlancar <perlancar@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2015 by perlancar@cpan.org.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.