document and test first-code-block #1 #3

README.md

@@ -14,6 +14,30 @@ use Pod::Utilities;
 
 Pod::Utilities is a set of tools to deal with Pod elements. It lets you create several Pod objects, obtain gists and modify headings.
 
+### sub first-code-block
+
+```perl6
+sub first-code-block (
+    Array @pod
+) returns Str;
+```
+
+Returns the first Pod::Block::Code found in an array, concatenating all lines in it.
+If any is found, it will return an empty string.
+
+Example:
+
+```perl6
+=being pod
+    say "some code";
+    say "more code";
+=end pod
+
+first-code-block($=pod[0].contents)
+
+# OUTPUT «say "some code";␤say "more code";␤»
+```
+
 # AUTHOR
 
 Alexander Mouquin <@Mouq>

lib/Pod/Utilities.pm6

@@ -32,8 +32,10 @@ sub pod-gist(Pod::Block $pod, $level = 0) is export {
     @chunks.join;
 }
 
+#| Returns the first Pod::Block::Code found in an array, concatenating 
+#| all lines in it. If any is found, it will return an empty string.
 sub first-code-block(@pod) is export {
-    @pod.first(* ~~ Pod::Block::Code).contents.grep(Str).join;
+    @pod.first(* ~~ Pod::Block::Code).contents.grep(Str).join || "";
 }
 
 sub pod-with-title($title, *@blocks) is export {

t/03-first-code-block.t

@@ -0,0 +1,19 @@
+use v6.c;
+use Test;
+
+plan *;
+
+use Pod::Utilities;
+
+
+=begin pod
+    say "this code rocks.";
+    say "Perl6" ~ "is cool."
+=end pod
+
+my $code = $=pod[0].contents[0].contents[0];
+
+is first-code-block($=pod.first.contents), $code.join, "Basic test";
+is first-code-block([])                  ,         "", "Returns empty string";
+
+done-testing;