diff options
author | Patrick Spek <Tyil@users.noreply.github.com> | 2017-04-26 07:44:59 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2017-04-26 07:44:59 +0200 |
commit | acdac7ea2f81e739c7e2b5cb37d3f3cdc71962a8 (patch) | |
tree | ed702ba420a3cda7f39f0b6b249b294f02dca487 | |
parent | 60aff52595020f378cd0d1a4d9d75894e083b9e0 (diff) | |
parent | b01a053e3d4012064a667745634010dd654b4777 (diff) |
Merge pull request #1 from scriptkitties/docs
Improve documentation
-rw-r--r-- | META6.json | 2 | ||||
-rw-r--r-- | README.md | 68 | ||||
-rw-r--r-- | lib/Config.pm6 | 132 | ||||
-rw-r--r-- | lib/Config/Exception/FileNotFoundException.pm6 | 4 | ||||
-rw-r--r-- | lib/Config/Exception/MissingParserException.pm6 | 13 | ||||
-rw-r--r-- | lib/Config/Exception/UnimplementedMethodException.pm6 | 4 | ||||
-rw-r--r-- | lib/Config/Exception/UnknownTypeException.pm6 | 4 | ||||
-rw-r--r-- | lib/Config/Exception/UnsupportedTypeException.pm6 | 11 | ||||
-rw-r--r-- | lib/Config/Parser.pm6 | 8 | ||||
-rw-r--r-- | t/reading.t | 15 | ||||
-rw-r--r-- | t/test-stub | 0 |
11 files changed, 185 insertions, 76 deletions
@@ -15,7 +15,7 @@ "Config::Exception::FileNotFoundException": "lib/Config/Exception/FileNotFoundException.pm6", "Config::Exception::UnimplementedMethodException": "lib/Config/Exception/UnimplementedMethodException.pm6", "Config::Exception::UnknownTypeException": "lib/Config/Exception/UnknownTypeException.pm6", - "Config::Exception::UnsupportedTypeException": "lib/Config/Exception/UnsupportedTypeException.pm6" + "Config::Exception::MissingParserException": "lib/Config/Exception/MissingParserException.pm6" }, "authors": [ "Patrick Spek <p.spek@tyil.work>" @@ -1,6 +1,74 @@ # Config A perl 6 library for reading and writing configuration files. +[![Build Status](https://travis-ci.org/scriptkitties/p6-Config.svg?branch=master)](https://travis-ci.org/scriptkitties/p6-Config) + +## Installation +This module can be installed using `zef`: + +``` +zef install Config +``` + +Depending on the type of configuration file you want to work on, you will need a +`Config::Parser::` module as well. If you just want an easy-to-use configuration +object without reading/writing a file, no parser is needed. + +## Usage +Include the `Config` module in your script, instantiate it and use it as you +please. + +```perl6 +use Config; + +my $config = Config.new(); + +# load a simple configuration hash +$config.read({ + keyOne => "value", + keyTwo => { + NestedKey => "other value" + } +}); + +# load a configuration files +$config.read("/etc/config.yaml"); + +# load a configuration file with a specific parser +$config.read("/etc/config", "Config::Parser::ini"); + +# retrieve a simple key +$config.get("keyOne"); + +# retrieve a nested key +$config.get("keyTwo.NestedKey"); + +# write out the configuration file +$config.write("/etc/config.yaml"); + +# write out the configuration in another format +$config.write("/etc/config.json", "Config::Parser::json"); +``` + +### Available parsers +Because there's so many ways to structure your configuration files, the parsers +for these are their own modules. This allows for easy implementing new parsers, +or providing a custom parser for your project's configuration file. + +The parser will be loaded during runtime, but you have to make sure it is +installed yourself. + +The following parsers are available: + +- [`Config::Parser::yaml`](https://github.com/scriptkitties/p6-Config-Parser-yaml) + +### Writing your own parser +If you want to make your own parser, simply make a new class in the +`Config::Parser` namespace. This class should extend the `Config::Parser` class, +and implement the `read` and `write` methods. The `read` method *must* return a +`Hash`. The `write` method *must* return a `Bool`, `True` when writing was +successful, `False` if not. + ## License This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software diff --git a/lib/Config.pm6 b/lib/Config.pm6 index 16aa7f7..2fa01bf 100644 --- a/lib/Config.pm6 +++ b/lib/Config.pm6 @@ -2,7 +2,7 @@ use v6.c; -use Config::Exception::UnsupportedTypeException; +use Config::Exception::MissingParserException; use Config::Exception::UnknownTypeException; use Config::Exception::FileNotFoundException; use Config::Type; @@ -14,36 +14,6 @@ class Config is export has $!path; has $!parser; - multi method read() - { - return self.load($!path); - } - - multi method read(Str $path, Str $parser = "") - { - Config::Exception::FileNotFoundException.new.throw() unless $path.IO.f; - - $!parser = self.get-parser($path, $parser); - - require ::($!parser); - $!content = ::($!parser).read($path); - - return True; - } - - multi method read(Hash $hash) - { - $!content = $hash; - } - - method write(Str $path, Str $parser = "") - { - $parser = self.get-parser($path, $parser); - - require ::($parser); - return ::($parser).write($path, $!content); - } - multi method get(Str $key, Any $default = Nil) { my $index = $!content; @@ -70,33 +40,6 @@ class Config is export $index; } - method has(Str $key) { - my $index = $!content; - - for $key.split(".") -> $part { - return False unless defined($index{$part}); - - $index = $index{$part}; - } - - True; - } - - method set(Str $key, Any $value) - { - my $index := $!content; - - for $key.split(".") -> $part { - $index{$part} = {} unless defined($index{$part}); - - $index := $index{$part}; - } - - $index = $value; - - self; - } - method get-parser(Str $path, Str $parser = "") { if ($parser ne "") { @@ -105,7 +48,9 @@ class Config is export my $type = self.get-parser-type($path); - Config::Exception::UnknownTypeException.new.throw() if $type eq Config::Type::unknown; + Config::Exception::UnknownTypeException.new( + type => $type + ).throw() if $type eq Config::Type::unknown; "Config::Parser::" ~ $type; } @@ -128,4 +73,73 @@ class Config is export return Config::Type::unknown; } + + method has(Str $key) { + my $index = $!content; + + for $key.split(".") -> $part { + return False unless defined($index{$part}); + + $index = $index{$part}; + } + + True; + } + + multi method read() + { + return self.load($!path); + } + + multi method read(Str $path, Str $parser = "") + { + Config::Exception::FileNotFoundException.new( + path => $path + ).throw() unless $path.IO.f; + + $!parser = self.get-parser($path, $parser); + + try { + CATCH { + when X::CompUnit::UnsatisfiedDependency { + Config::Exception::MissingParserException.new( + parser => $parser + ).throw(); + } + } + + require ::($!parser); + $!content = ::($!parser).read($path); + } + + return True; + } + + multi method read(Hash $hash) + { + $!content = $hash; + } + + method set(Str $key, Any $value) + { + my $index := $!content; + + for $key.split(".") -> $part { + $index{$part} = {} unless defined($index{$part}); + + $index := $index{$part}; + } + + $index = $value; + + self; + } + + method write(Str $path, Str $parser = "") + { + $parser = self.get-parser($path, $parser); + + require ::($parser); + return ::($parser).write($path, $!content); + } } diff --git a/lib/Config/Exception/FileNotFoundException.pm6 b/lib/Config/Exception/FileNotFoundException.pm6 index 74d7bc1..b00f956 100644 --- a/lib/Config/Exception/FileNotFoundException.pm6 +++ b/lib/Config/Exception/FileNotFoundException.pm6 @@ -4,8 +4,10 @@ use v6.c; class Config::Exception::FileNotFoundException is Exception { + has Str $.path; + method message() { - "Could not find file" + "Could not find file at $!path" } } diff --git a/lib/Config/Exception/MissingParserException.pm6 b/lib/Config/Exception/MissingParserException.pm6 new file mode 100644 index 0000000..484026a --- /dev/null +++ b/lib/Config/Exception/MissingParserException.pm6 @@ -0,0 +1,13 @@ +#! /usr/bin/env false + +use v6.c; + +class Config::Exception::MissingParserException is Exception +{ + has Str $.parser; + + method message() + { + "$!parser is not a valid parser. Are you sure its installed?" + } +} diff --git a/lib/Config/Exception/UnimplementedMethodException.pm6 b/lib/Config/Exception/UnimplementedMethodException.pm6 index ae87db9..10af289 100644 --- a/lib/Config/Exception/UnimplementedMethodException.pm6 +++ b/lib/Config/Exception/UnimplementedMethodException.pm6 @@ -4,8 +4,10 @@ use v6.c; class Config::Exception::UnimplementedMethodException is Exception { + has Str $.method; + method message() { - "This method is not implemented" + "The $!method method is not implemented" } } diff --git a/lib/Config/Exception/UnknownTypeException.pm6 b/lib/Config/Exception/UnknownTypeException.pm6 index de58755..095572b 100644 --- a/lib/Config/Exception/UnknownTypeException.pm6 +++ b/lib/Config/Exception/UnknownTypeException.pm6 @@ -4,8 +4,10 @@ use v6.c; class Config::Exception::UnknownTypeException is Exception { + has Str $.file; + method message() { - "Could not deduce loader type." + "Could not deduce loader type for $!file." } } diff --git a/lib/Config/Exception/UnsupportedTypeException.pm6 b/lib/Config/Exception/UnsupportedTypeException.pm6 deleted file mode 100644 index c2f6f10..0000000 --- a/lib/Config/Exception/UnsupportedTypeException.pm6 +++ /dev/null @@ -1,11 +0,0 @@ -#! /usr/bin/env false - -use v6.c; - -class Config::Exception::UnsupportedTypeException is Exception -{ - method message() - { - "No parser support for the given file. Have you imported a correct parser?" - } -} diff --git a/lib/Config/Parser.pm6 b/lib/Config/Parser.pm6 index 23effc0..1a99ad6 100644 --- a/lib/Config/Parser.pm6 +++ b/lib/Config/Parser.pm6 @@ -8,11 +8,15 @@ class Config::Parser { method read(Str $path --> Hash) { - Config::Exception::UnimplementedMethodException.new.throw(); + Config::Exception::UnimplementedMethodException.new( + method => "read" + ).throw(); } method write(Str $path, Hash $config --> Hash) { - Config::Exception::UnimplementedMethodException.new.throw(); + Config::Exception::UnimplementedMethodException.new( + method => "write" + ).throw(); } } diff --git a/t/reading.t b/t/reading.t new file mode 100644 index 0000000..52859af --- /dev/null +++ b/t/reading.t @@ -0,0 +1,15 @@ +#! /usr/bin/env perl6 + +use v6.c; +use Test; +use lib "lib"; + +plan 3; + +use Config; + +my $config = Config.new(); + +throws-like { $config.read("nonexistant-config") }, Config::Exception::FileNotFoundException, "Reading nonexisting file"; +throws-like { $config.read("t/test-stub") }, Config::Exception::UnknownTypeException, "Reading file of unknown type"; +throws-like { $config.read("t/test-stub", "Config::Parser:NoSuchParserForTest") }, Config::Exception::MissingParserException, "Using non-existing parser"; diff --git a/t/test-stub b/t/test-stub new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/t/test-stub |