https://github.com/vrurg/raku-config-bindish

Parser of BIND9-like configuration files
https://github.com/vrurg/raku-config-bindish

Last synced: about 2 months ago
JSON representation

Parser of BIND9-like configuration files

• Host: GitHub
• URL: https://github.com/vrurg/raku-config-bindish
• Owner: vrurg
• License: artistic-2.0
• Created: 2021-04-07T00:32:47.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2023-12-24T21:07:59.000Z (12 months ago)
• Last Synced: 2024-10-11T20:56:51.899Z (2 months ago)
• Language: Raku
• Size: 476 KB
• Stars: 0
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.html
  • Changelog: ChangeLog.html
  • License: LICENSE

Awesome Lists containing this project

README

        


    README

    

    hr,

img {

    box-sizing: content-box

}

body::after,

body::before,

hr::after,

hr::before {

    display: table;

    content: ""

}

a,

a:not([href]) {

    text-decoration: none

}

hr,

svg:not(:root) {

    overflow: hidden

}

img,

table tr {

    background-color: #fff

}

pre,

table {

    overflow: auto

}

dl,

dl dt,

hr,

pre code,

pre>code,

td,

th {

    padding: 0

}

input,

pre code {

    overflow: visible

}

pre,

pre code {

    word-wrap: normal

}

body {

    -ms-text-size-adjust: 100%;

    -webkit-text-size-adjust: 100%;

    color: #333;

    font-family: "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";

    font-size: 16px;

    line-height: 1.5;

    word-wrap: break-word;

    width: 820px;

    margin: 2em auto;

}

a {

    background-color: transparent;

    -webkit-text-decoration-skip: objects;

    color: #4078c0

}

a:active,

a:hover {

    outline-width: 0;

    text-decoration: underline

}

h1 {

    margin: .67em 0

}

img {

    border-style: none;

    max-width: 100%

}

h1,

h2 {

    padding-bottom: .3em;

    border-bottom: 1px solid #eee

}

input {

    font: inherit;

    margin: 0;

    font-family: inherit;

    font-size: inherit;

    line-height: inherit

}

* {

    box-sizing: border-box

}

strong {

    font-weight: 600

}

body::after,

hr::after {

    clear: both

}

table {

    border-spacing: 0;

    border-collapse: collapse;

    display: block;

    width: 100%

}

blockquote {

    margin: 0;

    padding: 0 1em;

    color: #777;

    border-left: .25em solid #ddd

}

ol ol,

ul ol {

    list-style-type: lower-roman

}

ol ol ol,

ol ul ol,

ul ol ol,

ul ul ol {

    list-style-type: lower-alpha

}

dd {

    margin-left: 0

}

code {

    font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace

}

pre {

    font: 12px Consolas, "Liberation Mono", Menlo, Courier, monospace

}

input {

    -webkit-font-feature-settings: "liga" 0;

    font-feature-settings: "liga" 0

}

body>:first-child {

    margin-top: 0!important

}

body>:last-child {

    margin-bottom: 0!important

}

a:not([href]) {

    color: inherit

}

blockquote,

dl,

ol,

p,

pre,

table,

ul {

    margin-top: 0;

    margin-bottom: 16px

}

hr {

    background: #e7e7e7;

    height: .25em;

    margin: 24px 0;

    border: 0

}

blockquote>:first-child {

    margin-top: 0

}

blockquote>:last-child {

    margin-bottom: 0

}

h1,

h2,

h3,

h4,

h5,

h6 {

    margin-top: 24px;

    margin-bottom: 16px;

    font-weight: 600;

    line-height: 1.25

}

dl dt,

table th {

    font-weight: 700

}

h1 code,

h1 tt,

h2 code,

h2 tt,

h3 code,

h3 tt,

h4 code,

h4 tt,

h5 code,

h5 tt,

h6 code,

h6 tt {

    font-size: inherit

}

h1 {

    font-size: 2em

}

h2 {

    font-size: 1.5em

}

h3 {

    font-size: 1.25em

}

h4 {

    font-size: 1em

}

h5 {

    font-size: .875em

}

h6 {

    font-size: .85em;

    color: #777

}

ol,

ul {

    padding-left: 2em

}

ol ol,

ol ul,

ul ol,

ul ul {

    margin-top: 0;

    margin-bottom: 0

}

li>p {

    margin-top: 16px

}

li+li {

    margin-top: .25em

}

dl dt {

    margin-top: 16px;

    font-size: 1em;

    font-style: italic

}

dl dd {

    padding: 0 16px;

    margin-bottom: 16px

}

table td,

table th {

    padding: 6px 13px;

    border: 1px solid #ddd

}

table tr {

    border-top: 1px solid #ccc

}

table tr:nth-child(2n) {

    background-color: #f8f8f8

}

code {

    padding: .2em 0;

    margin: 0;

    font-size: 85%;

    background-color: rgba(0, 0, 0, .04);

    border-radius: 3px

}

code::after,

code::before {

    letter-spacing: -.2em;

    content: "\00a0"

}

pre>code {

    margin: 0;

    font-size: 100%;

    word-break: normal;

    white-space: pre;

    background: 0 0;

    border: 0

}

pre {

    padding: 16px;

    font-size: 85%;

    line-height: 1.45;

    background-color: #f7f7f7;

    border-radius: 3px

}

pre code {

    display: inline;

    max-width: auto;

    margin: 0;

    line-height: inherit;

    background-color: transparent;

    border: 0

}

pre code::after,

pre code::before {

    content: normal

}

kbd {

    display: inline-block;

    padding: 3px 5px;

    font: 11px Consolas, "Liberation Mono", Menlo, Courier, monospace;

    line-height: 10px;

    color: #555;

    vertical-align: middle;

    background-color: #fcfcfc;

    border: 1px solid #ccc;

    border-bottom-color: #bbb;

    border-radius: 3px;

    box-shadow: inset 0 -1px 0 #bbb

}

hr {

    border-bottom-color: #eee

}

    

.toc-level-1 .toc-text { padding-left: 1.5em; }

.toc-level-2 .toc-text { padding-left: 2.5em; }

.toc-level-3 .toc-text { padding-left: 3.5em; }

.toc-level-4 .toc-text { padding-left: 4.5em; }

.toc-level-5 .toc-text { padding-left: 5.5em; }

#TOC * { border-width: 0; }

li > p { margin: inherit; }

li > .pod-block-code { margin-top: 16px; }

    


    


Table of Contents

1NAME

2SYNOPSIS

3DISCLAIMER

4DESCRIPTION

5EXTENSIONS

6ATTRIBUTES

6.1Config::BINDish::Grammar::Strictness $.strict

6.2Pair:D @.blocks, Pair:D @.options

6.3$.grammar, $.actions

6.4IO::Path $.file

6.5Bool $.flat = False

6.6$.top

6.7$.match

7METHODS

7.1extend-grammar( +@ext ), extend-actions( +@ext )

7.2build-grammar(), build-actions()

7.3multi method read(IO:D(Str:D) :$file, |args), multi method read(Str:D :$string, |args)

7.3.1multi get(...)

8EXPORTS

9SEE ALSO

10COPYRIGHT

11LICENSE


    


    
NAME

Config::BINDish - parse BIND9/named kind of config files

SYNOPSIS

my $cfg = Config::BINDish.new;

$cfg.read: string => q:to/CFG/;

server "s1" {

    name "my.server";

    paths {

        base "/opt/myapp";

        pool "files" static {

            "pub/img";

            "static/img";

            "docs";

        };

        pool "files" dynamic {

            "users/reports";

            "system/reports"

        }

    }

}

CFG

say $cfg.top.get( :server("s1") => :paths => :pool("images") => 'root' ); # ./pub/img

$cfg.read: file => $my-config-filename;

DISCLAIMER

This module is very much experimental in the sense of the API methods it provides. The grammar is expected to be more stable, yet no warranties can be given at the moment.

DESCRIPTION

In this documentation I'll be referring to the configuration format implemented by the module as BINDish config or simply BINDish.

EXTENSIONS

BINDish configuration parser can be augmented with 3rd-party extensions. Every extension is implemented as a role which will be used to build the final grammar or actions classes (see Grammar). The classes are based upon Config::BINDish::Grammar and Config::BINDish::Actions respectively. Here is the steps Config::BINDish does to build them:





An empty class is created which will serve as the final version





Extension roles are punned and added as parents to the class





Then the base class is added as the last parent





The order in which the extensions are added is defined by the order and the way they're registered. The later added ones serve as the earlier parents meaning that Raku's method call dispatching will have their methods invoked first.

There are two and a half ways to extend the parser. First is to use `is BINDish-grammar` or `is BINDish-actions` trait:

unit module Config::BINDish::Ext1;

use Config::BINDish;

role Grammar is BINDish-grammar {

    token value:sym<mine> {

        ...

    }

}

role Actions is BINDish-actions {

    method value:sym<mine>($/) {

        ...

    }

}

In this case the role they're applied to will be auto-registered with Config::BINDish. When such extension is contained by a module then it would be added when the module is used:

use Config::BINDish::Ext1;

use Config::BINDish::Ext2;

Note that considering the order of use statements, Ext2 will be able to override methods of Ext1.

The specificifty of using the traits is that extensions declared this way will become application-wide available. So, even if the extension module is used by a module used by the main code, the extension will be available to any instance of Config::BINDish.

Note: We say that extensions registered with the traits are registered statically.

The other 1.5 ways of adding the extensions are to use extend-grammar and extend-actions constructor arguments or methods with the same names:

my $cfg = Config::BINDish.new: :extend-grammar(ExtG1, ExtG2), :extend-actions(ExtA1, ExtA2);

$cfg.extend-grammar(ExtG3)

    .extend-actions(ExtA3);

In this case extension roles don't need the traits applied. This way we call dynamic registration.

The other specific of dynamic extensions is that they will go after the static ones. I.e. in the above examples ExtG* and ExtA* will be positioned before Ext1 and Ext2 in the MRO order, prioritizing the former over the latter ones.

Why is the above called 1.5 ways? Because the constructor eventually uses the extend-* methods with corresponding :extend-* named attributes.

See also Config::BINDish::Grammar and Config::BINDish::Actions.

ATTRIBUTES



Config::BINDish::Grammar::Strictness $.strict



The default grammar strictness mode. See Config::BINDish::Grammar::Strictness documentation for details.



Pair:D @.blocks, Pair:D @.options



These two attributes contain user-defined (pre-declared) structure of the config file. More information about them can be found in Config::BINDish::Grammar documentation, in Pre-declaration section.

$.grammar, $.actions

The final grammar and actions class versions with all registered extensions applied. Both attributes are lazy and clearable in terms of AttrX::Mooish. It means that the following is possible:

say $cfg.grammar.^name; # Config::BINDish::Grammar...

$cfg.extend-grammar(MyApp::GrammarMod);

$cfg.clear-grammar;     # Actually, extend-grammar already does this. This line is here to demo the concept only.

say $cfg.grammar.^name; # Config::BINDish::Grammar+{MyApp::GrammarMod}...



IO::Path $.file



If read method was called with :file<...> argument then this attribute will hold corresponding IO::Path object for the file name.



Bool $.flat = False



If set to True then Config::BINDish::Actions will act in flattening mode.

$.top

The top node produced by the grammar actions. I.e. it is the result of $<TOP>.ast of the Match object produced by grammar's parse method. For Config::BINDish::Actions it would be an instance of Config::BINDish::AST::TOP. But an extension can produce something to its taste which wouldn't be an AST whatsoever. The only requirement imposed on the object stored in the attribute is to provide get method.

This attribute handles method get.

$.match

This attribute stores the Match object produced by grammar's parse method.

METHODS

extend-grammar( +@ext ), extend-actions( +@ext )

Interface to dynamically register extensions. Take a list of roles and records them as extensions. Then it clears $.grammar or $.actions attributes, respectively. Both return self to allow method call chaining.

build-grammar(), build-actions()

Methods used by AttrX::Mooish to lazily initialize $.grammar and $.actions attributes respectively.

multi method read(Config::BINDish:U: |args)

Instantiates Config::BINDish class and re-invokes read method on the instance with args capture.

multi method read(IO:D(Str:D) :$file, |args), multi method read(Str:D :$string, |args)

Parses a configuration stored either in a $string or in a $file and returns the resulting Match object. The capture args is passed over to the parse method of $.grammar alongside with $.actions, $.strict, $.flat, %.blocks, and %.options attributes.

The method returns what is returned by grammar's parse method. The same value is then stored in $.match attribute.

multi get(...)

Method is handled by $.top attribute. See Config::BINDish::AST::Blockish for detailed method description.

EXPORTS

By default this module exports only BINDish-grammar and BINDish-actions traits. But if used with either "op" or "ascii-op" positional arguments it will also export _request operator_ in either unicode or ASCII form:

use Config::BINDish <op>;

my $cfg = Config::BINDish.new.read(...);

say $cfg ∷ :top-block<name> ∷ "option";

Or:

use Config::BINDish <ascii-op>;

my $cfg = Config::BINDish.new.read(...);

say $cfg :: :top-block<name> :: "option";

*Note* that :: (ASCII version) may conflict with Raku's name resolution. Though in my tests this never happened, I would still prefer the unicode version over the ASCII.

More information about the operator can be found in Config::BINDish::Ops.

SEE ALSO





Config::BINDish::Grammar





Config::BINDish::AST





Config::BINDish::Ops





Config::BINDish::Expandable





Config::BINDish::INET





README





INDEX





COPYRIGHT

(c) 2023, Vadim Belman <[email protected]>

LICENSE

Artistic License 2.0

See the LICENSE file in this distribution.