documentation, and a few author-tests

3 files changed, 140 insertions, 0 deletions

diff --git a/lib/Tree/Transform/XSLTish/Context.pm b/lib/Tree/Transform/XSLTish/Context.pm
index 2e696a5..0890401 100644
--- a/lib/Tree/Transform/XSLTish/Context.pm
+++ b/lib/Tree/Transform/XSLTish/Context.pm
@@ -7,3 +7,13 @@ has 'node_list' => ( is => 'rw', isa => 'ArrayRef[Object]' );
 
 __PACKAGE__->meta->make_immutable;no Moose;1;
 __END__
+
+=head1 NAME
+
+Tree::Transform::XSLTish::Context - helper class
+
+=head1 AUTHOR
+
+Gianni Ceccarelli <dakkar@thenautilus.net>
+
+=cut
diff --git a/lib/Tree/Transform/XSLTish/Transformer.pm b/lib/Tree/Transform/XSLTish/Transformer.pm
index fd61ea6..c4ff53f 100644
--- a/lib/Tree/Transform/XSLTish/Transformer.pm
+++ b/lib/Tree/Transform/XSLTish/Transformer.pm
@@ -150,6 +150,8 @@ sub find_rule_in_package {
     elsif (@candidates >= 1) {
         return $candidates[0];
     }
+
+    return;
 }
 
 sub find_rule_by_name_in_package {
@@ -214,3 +216,120 @@ sub DESTROY {
 
 1;
 __END__
+
+=head1 NAME
+
+Tree::Transform::XSLTish::Transformer - transformer class for L<Tree::Transform::XSLTish>
+
+=head1 METHODS
+
+=head2 C<new>
+
+  $trans=Tree::Transform::XSLTish::Transformer->new(
+    rules_package => 'Some::Package',
+    engine => $engine_instance,
+  );
+
+You usually don't call this constructor directly, but instead use L<<
+the C<new> function exported by
+Tree::Transform::XSLTish|Tree::Transform::XSLTish/new >>, which passes
+the correct C<rules_package> automatically.
+
+If you don't specify an C<engine>, it will be constructed using the
+class or factory declared in the rules package; if you didn't declare
+anything, it will be an instance of L<Tree::XPathEngine>
+
+=for comment
+
+engine factories are not inherited!
+
+=head2 C<transform>
+
+  @results=$trans->transform($tree);
+
+When you call this function on a tree, the transformer will transform
+it according to your rules and to the L<XSLT processing
+model|http://www.w3.org/TR/xslt.html#section-Processing-Model>.
+
+C<< $trans->transform($node) >> is equivalent to C<<
+$trans->apply_rules($trans->engine->findnodes('/',$node)) >>.
+
+Always call this method in list context.
+
+=head2 C<apply_rules>
+
+   $trans->apply_rules(@nodes);
+
+Just like C<apply-rules> in XSLT, this function will apply the rules
+to the specified nodes, or to the children of the current node if none
+are passed, and return all the results in a single list.
+
+This will die if there are no matching rules, or if there are more
+than one matching rule with highest priority.
+
+Always call this method in list context.
+
+=head2 C<call_rule>
+
+  $trans->call_rule('rule-name');
+
+This fuction will apply the named rule to the current node, and return
+the result.
+
+This will die if there is no rule with the given name.
+
+Always call this method in list context.
+
+=head2 C<it>
+
+  $current_node = $trans->it;
+
+Inside a rule, this fuction will return the node to which the rule is
+being applied.
+
+=head1 INTERNAL FUNCTIONS
+
+These functions should not be called from outside this module.
+
+=head2 C<find_rule>
+
+For each package in the linearized inheritance chain of the rules
+package on which this transformer has been instantiated, calls
+L<find_rule_in_package> and returns the first defined result.
+
+=head2 C<find_rule_in_package>
+
+Gets all the rules having a C<match> attribute, filters those for
+which L<rule_matches> returns true, sorts them priority, and returns
+the one with the highest priority.
+
+Dies if there is more than one rule with the highest priority; returns
+undef if there are no matching rules.
+
+=head2 C<find_rule_by_name>
+
+For each package in the linearized inheritance chain of the rules
+package on which this transformer has been instantiated, calls
+L<find_rule_by_name_in_package> and returns the first defined result.
+
+=head2 C<find_rule_by_name_in_package>
+
+Returns the rule with the given name, if any; returns undef otherwise.
+
+=head2 C<rule_matches>
+
+Evaluates the C<match> XPath expression in a sequence of contexts, to
+see if the current node appears in the resulting node-set. If it does,
+returns true; if there is no such context, returns false.
+
+The first context is the current node; following contexts are each the
+parent node of the previous one.
+
+NOTE: to check whether a node appears in a node-set, we either use the
+C<isSameNode> method, or check the stringifications for equality.
+
+=head1 AUTHOR
+
+Gianni Ceccarelli <dakkar@thenautilus.net>
+
+=cut
diff --git a/lib/Tree/Transform/XSLTish/Utils.pm b/lib/Tree/Transform/XSLTish/Utils.pm
index bed1167..bfb438c 100644
--- a/lib/Tree/Transform/XSLTish/Utils.pm
+++ b/lib/Tree/Transform/XSLTish/Utils.pm
@@ -31,3 +31,14 @@ sub _get_inheritance {
 }
 
 1;
+__END__
+
+=head1 NAME
+
+Tree::Transform::XSLTish::Utils - utility functions
+
+=head1 AUTHOR
+
+Gianni Ceccarelli <dakkar@thenautilus.net>
+
+=cut