Merge pull request #9 from tbrowder/next-ver

Update description and other documentation

Author: tbrowder

Changes

@@ -1,6 +1,15 @@
 Revision history for Pod-TreeWalker
 
 {{$NEXT}}
+    - Enabled creation of a separate document for the Listener
+      role from existing pod in file 
+        'lib/Pod/TreeWalker/Listener.rakumod'.
+    - Updated copyright date in file
+        'lib/Pod/TreeWalker/Listener.rakumod'.
+    - Added a short example of actual use along with other
+        README.md tweaks.
+    - Added missing dep 'Test::Coverage' to META6.json
+    - Adjusted Test::Coverage numbers in xt/
 
 0.0.5  2025-05-06T11:02:12+02:00
     - Changed trait 'is built' to 'is required' on the Listener

Listener.md

@@ -0,0 +1,116 @@
+NAME
+====
+
+Pod::TreeWalker::Listener - Role for classes which handle events produced by Pod::TreeWalker
+
+SYNOPSIS
+========
+
+```raku
+class MyListener does Pod::TreeWalker::Listener {
+    multi method start(Pod::Heading $node --> False) {
+        say "Heading level {$node.level}";
+    }
+
+    multi method end(  Pod::Heading $node --> False) {
+        say "Heading level {$node.level}";
+    }
+
+    method table-row (Array $row) { ... }
+}
+```
+
+DESCRIPTION
+===========
+
+This role defines the API which objects passed to `Pod::TreeWalker`'s constructor are expected to implement.
+
+METHODS TO BE IMPLEMENTED
+=========================
+
+start
+-----
+
+```raku
+$listener.start(... $node --> False)
+```
+
+The `start` method is a multi method which is called for most Pod objects. It is passed a [doc:Pod::Block](doc:Pod::Block) object of some sort.
+
+If this method returns `False`, then the `Pod::TreeWalker` will not look at the contents of the node, nor will it call the corresponding `end` method for the node.
+
+### Tables
+
+The headers of a table (from `$node.headers`) are passed as an array of [Pod::Blocks](Pod::Blocks).
+
+end
+---
+
+```raku
+$listener.end(  ... $node --> False)
+```
+
+The `end` is a multi method that is called for most Pod objects. It is passed a `Pod::Block` object of some sort.
+
+start-list
+----------
+
+```raku
+$listener.start-list(Int :$level, Bool :numbered)
+```
+
+This method is called whenever a new list level is encountered. It can be called multiple times in a row if a list item is introduced that skips levels, for example:
+
+    =item1 start-list is called once
+    =item3 start-list is called twice
+
+end-list
+--------
+
+```raku
+$listener.end-list(Int :$level, Bool :numbered)
+```
+
+This method is called whenever a list level is done. List `start-list`, it can be called multiple times in a row.
+
+table-row
+---------
+
+```raku
+$listener.table-row(Array $row)
+```
+
+This method is called once for each row in a table. Each element of `$row` will in turn be a [Pod::Block](Pod::Block).
+
+config
+------
+
+```raku
+$listener.config(Pod::Config $node --> False)
+```
+
+This method is called for Pod config declarations.
+
+text
+----
+
+```raku
+$listener.text(Str $text)
+```
+
+This method is called for plain text, usually inside a paragraph block.
+
+AUTHOR
+======
+
+Dave Rolsky
+
+COPYRIGHT AND LICENSE
+=====================
+
+Copyright 2015 - 2018 Dave Rolsky
+
+Copyright 2019 - 2025 Raku Community
+
+This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
+

META6.json

@@ -23,6 +23,7 @@
     "TREE"
   ],
   "test-depends": [
+    "Test::Coverage"
   ],
   "version": "0.0.5"
 }

README.md

@@ -11,35 +11,38 @@ SYNOPSIS
 ```raku
 use Pod::TreeWalker;
 
-my $to-html = Pod::To::HTML.new(...);
-Pod::TreeWalker.new( :listener($to-html) ).walk-pod($=pod);
+my $L = My::Listener.new;
+my $o = Pod::TreeWalker.new: :listener($L);
+my @events = $o.walk-pod($=pod);
 ```
 
 DESCRIPTION
 ===========
 
 This class provides an API for walking a pod tree (as provided by `$=pod`). Each node in the tree will trigger one or more events. These events cause methods to be called on a listener object that you provide. This lets you do something with a Pod document without having to know much about the underlying tree structure of Pod.
 
+Note: Use distribution `Pod::Load` for an easy way to access the Pod from a file or a string.
+
 METHODS
 =======
 
 new
 ---
 
 ```raku
-my $walker = Pod::TreeWalker.new( :listener($object) )
+my $walker = Pod::TreeWalker.new: :listener($object);
 ```
 
-The constructor requires a single named argument `:listener`. This object must implement the [Pod::TreeWalker::Listener](./t/lib/TestListener.rakumod) API as demonstrated in file './t/lib/TestListener.rakumod'.
+The constructor requires a single named argument `:listener`. This object must implement the `Pod::TreeWalker::Listener` API as demonstrated in file './t/lib/TestListener.rakumod'. See more details in **Listener.md**.
 
 walk-pod
 --------
 
 ```raku
-$walker.walk-pod($pod);
+my @events = $walker.walk-pod($pod);
 ```
 
-This method walks through a pod tree starting with the top node in `$pod`. You can provide either an array of pod nodes (as stored in `$=pod`) or a single top-level node (such as `$=pod[0]`).
+This method walks through a pod tree starting with the top node in `$pod`. You can provide either an array of pod nodes (as stored in `$=pod`) or a single top-level node (such as `$=pod[0]`). The `@events` list provides the details of each pod node encountered.
 
 text-content-of
 ---------------

dist.ini

@@ -15,3 +15,6 @@ filename = doc/Pod-TreeWalker.rakudoc
 provider = github-actions/linux.yml
 provider = github-actions/macos.yml
 provider = github-actions/windows.yml
+
+[RunAfterBuild]
+cmd = raku --doc=Markdown lib/Pod/TreeWalker/Listener.rakumod > Listener.md

doc/Pod-TreeWalker.rakudoc

@@ -10,8 +10,9 @@ Pod::TreeWalker - Walk a Pod tree and generate an event for each node
 
 use Pod::TreeWalker;
 
-my $to-html = Pod::To::HTML.new(...);
-Pod::TreeWalker.new( :listener($to-html) ).walk-pod($=pod);
+my $L = My::Listener.new;
+my $o = Pod::TreeWalker.new: :listener($L);
+my @events = $o.walk-pod($=pod);
 
 =end code
 
@@ -23,31 +24,36 @@ cause methods to be called on a listener object that you provide. This lets
 you do something with a Pod document without having to know much about the
 underlying tree structure of Pod.
 
+Note: Use distribution C<Pod::Load> for an easy way to access the Pod
+from a file or a string.
+
 =head1 METHODS
 
 =head2 new
 
 =begin code :lang<raku>
 
-my $walker = Pod::TreeWalker.new( :listener($object) )
+my $walker = Pod::TreeWalker.new: :listener($object);
 
 =end code
 
 The constructor requires a single named argument C<:listener>. This object must
-implement the L<Pod::TreeWalker::Listener|./t/lib/TestListener.rakumod> API
+implement the C<Pod::TreeWalker::Listener> API
 as demonstrated in file './t/lib/TestListener.rakumod'.
+See more details in B<Listener.md>.
 
 =head2 walk-pod
 
 =begin code :lang<raku>
 
-$walker.walk-pod($pod);
+my @events = $walker.walk-pod($pod);
 
 =end code
 
 This method walks through a pod tree starting with the top node in
 C<$pod>. You can provide either an array of pod nodes (as stored in C<$=pod>)
 or a single top-level node (such as C<$=pod[0]>).
+The C<@events> list provides the details of each pod node encountered.
 
 =head2 text-content-of
 

lib/Pod/TreeWalker/Listener.rakumod

@@ -142,7 +142,7 @@ Dave Rolsky
 
 Copyright 2015 - 2018 Dave Rolsky
 
-Copyright 2019 - 2022 Raku Community
+Copyright 2019 - 2025 Raku Community
 
 This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
 

xt/coverage.rakutest

@@ -2,9 +2,9 @@ use Test::Coverage;
 
 plan 2;
 
-coverage-at-least 81;
+coverage-at-least 80;
 
-uncovered-at-most 14;
+uncovered-at-most 15;
 
 source-with-coverage;