Apachish - Apachish configuration format specification
This document describes version 0.9.0 of Apachish (from Perl distribution Apachish), released on 2015-12-11.
0.9
Specification is still rather in flux. Backwards compatibility is not guaranteed between 0.9.x releases.
Apachish is a configuration file format that is mostly compatible with the Apache webserver's file format.
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.
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.
IOD
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.
A blank line is a line containing zero or more whitespaces only. It is ignored.
A comment line begins with # as it's first nonblank character.
#
<ws>* |"#" <COMMENT>
Examples:
# this is a comment
<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.
NAME
\
\\
Unlike in Apache, currently a directive line cannot be continued to another line using backslash.
A directive line cannot contain comments.
Foo arg1 arg2 "arg3 contains spaces, \"quotes\", and backslash \\" Bar ""
Directives in configuration are case-insensitive, but the arguments are case-sensitive.
<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.
>
<Context1> <Context1 ~arg1> <Context1 "arg1>">
Context names are case-insensitive, but its arguments are case-sensitive.
<ws>* "</" <NAME> ">"
</Context1>
An alternative format for simpler/flat configuration: IOD
Please visit the project's homepage at https://metacpan.org/release/Apachish.
Source repository is at https://github.com/perlancar/perl-Apachish.
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.
perlancar <perlancar@cpan.org>
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.
To install Apachish, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Apachish
CPAN shell
perl -MCPAN -e shell install Apachish
For more information on module installation, please visit the detailed CPAN module installation guide.