[libcatmandu-perl] 32/85: Adding more documentation for Catmandu::Sane and Catmandu::Util

[Jonas Smedegaard]

This is an automated email from the git hooks/post-receive script.

js pushed a commit to tag 0.91
in repository libcatmandu-perl.

commit 494f56f0aa54c93377a9648af6fc7d1ede4b03f6
Author: Patrick Hochstenbach <patrick.hochstenbach at ugent.be>
Date:   Mon May 12 14:05:39 2014 +0200

    Adding more documentation for Catmandu::Sane and Catmandu::Util
---
 Build.PL             |  2 +-
 lib/Catmandu/Sane.pm | 23 +++++++++++++++++++++++
 lib/Catmandu/Util.pm | 27 +++++++++++++++++++++++++--
 3 files changed, 49 insertions(+), 3 deletions(-)

diff --git a/Build.PL b/Build.PL
index c4c8972..a792eb0 100644
--- a/Build.PL
+++ b/Build.PL
@@ -1,4 +1,4 @@
 # This Build.PL for Catmandu was generated by Dist::Zilla::Plugin::ModuleBuildTiny 0.006.
 use v5.10.1;
-use Module::Build::Tiny 0.035;
+use Module::Build::Tiny 0.036;
 Build_PL();
diff --git a/lib/Catmandu/Sane.pm b/lib/Catmandu/Sane.pm
index a1a2764..3576537 100644
--- a/lib/Catmandu/Sane.pm
+++ b/lib/Catmandu/Sane.pm
@@ -28,6 +28,29 @@ Catmandu::Sane - Package boilerplate
 
     use Catmandu::Sane;
 
+    # Provides all the 5.10 features.
+    say("what"); 
+    given($foo) {
+        when(1)     { say "1" }
+        when([2,3]) { say "2 or 3" }
+        when(/abc/) { say "has abc" }
+        default     { none of the above } 
+    }
+    sub next_id{
+      state $id;
+      ++$id;
+    }
+
+    # Provides try/catch[/finally] try/catch_case[/finally]
+    try {
+    } catch {}
+
+    # Provides
+    Catmandu::Error->throw("error");
+    Catmandu::BadVal->throw("eek val");
+    Catmandu::BadArg->throw("eek arg");
+    Catmandu::NotImplemented->throw("cant do that!");
+
 =head1 DESCRIPTION
 
 Package boilerplate equivalent to:
diff --git a/lib/Catmandu/Util.pm b/lib/Catmandu/Util.pm
index cab2c55..4ef6aff 100644
--- a/lib/Catmandu/Util.pm
+++ b/lib/Catmandu/Util.pm
@@ -132,10 +132,13 @@ sub write_file {
 }
 
 sub read_yaml {
+    # dies on error
     YAML::Any::LoadFile($_[0]);
 }
 
 sub read_json {
+    my $text = read_file($_[0]);
+    # dies on error
     JSON::decode_json(read_file($_[0]));
 }
 
@@ -579,27 +582,43 @@ Reads the file at C<$path> into a string.
 
     my $str = read_file('/path/to/file.txt');
 
+Throws a Catmandu::Error on failure. 
+
 =item write_file($path, $str);
 
 Writes the string C<$str> to a file at C<$path>.
 
     write_file('/path/to/file.txt', "contents");
 
+Throws a Catmandu::Error on failure. 
+
 =item read_yaml($path);
 
-    my $cfg = read_yaml('config.yaml');
+Reads the YAML file at C<$path> into a Perl hash.
+
+    my $cfg = read_yaml($path);
+
+Dies on failure reading the file or parsing the YAML.
 
 =item read_json($path);
 
-    my $cfg = read_json('config.json');
+Reads the JSON file at C<$path> into a Perl hash.
+
+    my $cfg = read_json($path);
+
+Dies on failure reading the file or parsing the JSON.
 
 =item join_path(@path);
 
+Joins relative paths into an absolute path.
+
     join_path('/path/..', './to', 'file.txt');
     # => "/to/file.txt"
 
 =item normalize_path($path);
 
+Normalizes a relative path to an absolute path.
+
     normalize_path('/path/../to/./file.txt');
     # => "/to/file.txt"
 
@@ -1001,10 +1020,14 @@ Load package C<$pkg> at runtime with C<require> and return it's full name.
     require_package('Catmandu::Util', 'Catmandu');
     # => "Catmandu::Util"
 
+Throws a Catmandu::Error on failure.
+
 =item use_lib(@dirs)
 
 Add directories to C<@INC> at runtime.
 
+Throws a Catmandu::Error on failure.
+
 =back
 
 =head1 SEE ALSO

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libcatmandu-perl.git