Message/DOM/SerialWalker.pm

package Message::DOM::SerialWalker;
use strict;
our $VERSION=do{my @r=(q$Revision: 1.8 $=~/\d+/g);sprintf "%d."."%02d" x $#r,@r};
push our @ISA, 'Message::IF::SerialWalker';

sub AUTOLOAD {
  my $method_name = our $AUTOLOAD;
  $method_name =~ s/.*:://;
  return if $method_name eq 'DESTROY';

  if ({
    current_index => 1,
    current_node => 1,
    current_phase => 1,
    expand_entity_references => 1,
    filter => 1,
    root => 1,
    what_to_show => 1,
  }->{$method_name}) {
    no strict 'refs';
    eval qq{
      sub $method_name (\$) { \$_[0]->{$method_name} }
    };
    goto &{ $AUTOLOAD };
  } else {
    require Carp;
    Carp::croak (qq<Can't locate method "$AUTOLOAD">);
  }
} # AUTOLOAD

## |SerialWalker| constants

## |SerialWalkerPhase|
sub PRE_PHASE () { 1 }
sub IN_PHASE () { 2 }
sub POST_PHASE () { 3 }

## |SerialWalker| attributes

sub current_index ($);

sub current_node ($);

sub current_phase ($);

sub expand_entity_references ($);

sub filter ($);

sub root ($);

sub what_to_show ($);

## |SerialWalker| methods

sub next_node ($) {
  my $self = $_[0];

  A: {
    unless (@{$self->{next}}) {
      #
    } elsif ($self->{next}->[0]->[1] != 0) {
      my $v = shift @{$self->{next}};
      $self->{current_phase} = $v->[1];
      $self->{current_index} = $self->{_index}->{$v->[2]}++;
      return ($self->{current_node} = $v->[0]);
    } else {
      my $v = shift @{$self->{next}};
      my $vresult = $self->_test_node ($v->[0]);
      
      my @pnext;
      if ($vresult == 1) { # FILTER_ACCEPT
        my $key = $v->[2].'.'.$self->{_index}->{$v->[2]};

        push @pnext, [$v->[3], IN_PHASE, $v->[4]]
            if defined $v->[3] and $self->{_index}->{$v->[4].'.1'};

        $self->{_index}->{$key} = 0;
        push @pnext, [$v->[0], PRE_PHASE, $key];
  
        push @pnext, [$_, 0, $key, $v->[0], $key]
            for @{$v->[0]->child_nodes};
        push @pnext, [$v->[0], POST_PHASE, $key];
      } elsif ($vresult == 3) { # FILTER_SKIP
        push @pnext, [$_, 0, $v->[2], $v->[3], $v->[4]]
            for @{$v->[0]->child_nodes};
      } elsif ($vresult == 12101) { # MANAKAI_FILTER_OPAQUE
        my $key = $v->[2].'.'.$self->{_index}->{$v->[2]};
        
        push @pnext, [$v->[3], IN_PHASE, $v->[4]]
            if defined $v->[3] and $self->{_index}->{$v->[4].'.1'};

        $self->{_index}->{$key} = 0;
        push @pnext, [$v->[0], PRE_PHASE, $key];
        push @pnext, [$v->[0], POST_PHASE, $key];
      }
      unshift @{$self->{next}}, @pnext;
      redo A;
    }
  } # A

  return undef;
} # next_node

sub _test_node ($$) {
  ## NOTE: There is a code clone in |TreeWalker.pm|.

  unless ($_[0]->{expand_entity_references}) {
    my $parent = $_[1]->parent_node;
    if (defined $parent and $parent->node_type == 5) { # ENTITY_REFERENCE_NODE
      return 2; # FILTER_REJECT ## NOTE: Even if |NodeIterator|.
    }
  }
    
  if ($_[0]->{what_to_show} != 0xFFFFFFFF) { # SHOW_ALL
    my $nt = $_[1]->node_type;
    if ($nt < 33 and ($_[0]->{what_to_show} & (1 << ($nt-1)))) {
      #
    } else {
      return 3; # FILTER_SKIP
    }
  }

  if (defined $_[0]->{filter}) {
    local $Error::Depth = $Error::Depth + 1;
    return $_[0]->{filter}->($_[1]);
  } else {
    return 1; # FILTER_ACCEPT
  }
} # _test_node

package Message::IF::SerialWalker;

package Message::DOM::Document;

sub manakai_create_serial_walker ($$;$$$) {
  unless (defined $_[1]) {
    require Message::DOM::DOMException;
    report Message::DOM::DOMException
        -object => $_[0],
        -type => 'NOT_SUPPORTED_ERR',
        -subtype => 'NULLPO_ERR';
  }

  ## TODO: Initials for current_index and current_phase
  return bless {
                root => $_[1],
                what_to_show => 0+($_[2] or 0),
                filter => $_[3],
                expand_entity_references => $_[4] ? 1 : 0,
                current_node => $_[1],
                next => [[$_[1], 0, '']],
                _index => {'' => 0},
               }, 'Message::DOM::SerialWalker';
} # manakai_create_serial_walker

=pod

## TODO: Documentation

  @LXMethod:
    @@Name: manakaiCreateSerialWalker
    @@enDesc:
      Creates a new <IF::SerialWalker> object.
    @@Param:
      @@@Name: root
      @@@Type: Node
      @@@enDesc:
        The node that will serve as the root for the <IF::SerialWalker>.

        The <P::whatToShow> flags and the <IF::NodeFilter>
        are not considered when setting this value; any node type
        will be accepted as the root.

        The <A::TreeWalker.currentNode> of the created <IF::TreeWalker>
        is initialized to the <P::root> node, whether or not it 
        is visible.  

        The <P::root> functions as a stopping point for traversal
        methods that look upwards in the document structure, i.e.
        <M::SerialWalker.nextNode>.

        The <P::root> <kwd:MUST-NOT> be <DOM::null>.  If it is,
        the implementation <kwd:MUST> throw an exception.
    @@Param:
      @@@Name: whatToShow
      @@@Type: unsignedShort
      @@@actualType: WhatToShow
      @@@enDesc:
        The flags that specifies which node types may appear in the
        logical view of the tree presented by the <IF::SerialWalker>.

        The set of the flags are defined in the <IF::NodeFilter> interface.
        They can be combined using the binary <CODE::OR> operation.
    @@Param:
      @@@Name: filter
      @@@Type: NodeFilter
      @@@enDesc:
        The <IF::NodeFilter> to be used with the created <IF::SerialWalker>.
      @@@nullCase:
        @@@@enDesc:
          Indicates that no filter is used.
    @@Param:
      @@@Name: entityReferenceExpansion
      @@@Type: boolean
      @@@enDesc:
        The <A::SerialWalker.expandEntityReferences> flag of 
        the created <IF::TreeWalker>.
      @@@TrueCase:
        @@@@enDesc:
          The contents of the <IF::tx|EntityReference> nodes
          <EM::are> presented in the logical view.
      @@@FalseCase:
        @@@@enDesc:
          The contents of the <IF::tx|EntityReference> nodes
          are <EM::not> presented in the logical view.
    @@Return:
      @@@Type: SerialWalker
      @@@enDesc:
        {P:: The newly created <IF::SerialWalker>.  It <kwd:MUST>
             have attributes set as:

             - <A::SerialWalker.currentNode>::: <P::root>.

             - <A::SerialWalker.expandEntityReferences>:::
                   <P::entityReferenceExpansion>.

             - <A::SerialWalker.filter>::: <P::filter>.

             - <A::SerialWalker.root>::: <P::root>.

             - <A::SerialWalker.whatToShow>::: <P::whatToShow>.

        }
      @@@dx:raises:
        @@@@@: c|SET_TO_NULL_ERR
        @@@@enDesc:
          If the specified <P::root> is <DOM::null>.
    {ISSUE::
      Better name?
    }

    A <IF::SerialWalker> object can be used to traverse
    the subtree rooted by a node in document order.
    Unlike <IF::TreeWalker> and <IF::NodeIterator>, the
    <IF::SerialWalker> object cannot go back toward
    nodes that had already been seen.  The
    <IF::SerialWalker>, however, revisits a node after its
    children are visited.  This might be useful when
    an application wants to serialize a subtree in a format
    where delimiter and / or terminator should be inserted
    between and / or after nodes.

    How the <IF::SerialWalker> works is defined by the following
    reference algorithm.  An implementation does not have to
    implement this exact algorithm, but it <kwd:MUST> implement
    its method so that it has the same effect as the
    reference algorithm when the underlying subtree has not
    been modified.

    At the time of creation of the <IF::SerialWalker>, 
    the implementation <kwd:MUST> prepare a queue and
    <kwd:MUST> initialize it by pushing the <A::SerialWalker.root> node.

    {P:: When the <M::SerialWalker.nextNode> method is invoked,

       - If the queue is empty, the method <kwd:MUST> return
         <DOM::null>.  It <kwd:MUST-NOT> change 
         <A::SerialWalker.currentNode>, <A::SerialWalker.currentPhase>,
         and <A::SerialWalker.currentIndex> attributes.

       {LI:: Otherwise, 

          - Shift a node from the queue.  If the node has
            the phase value, the method <kwd:MUST> return
            the node.  In addition, it <kwd:MUST> set
            the <A::SerialWalker.currentNode> attribute to the node,
            the <A::SerialWalker.currentPhase> attribute to
            the associated phase value, and the
            <A::SerialWalker.currentIndex> attribute to
            the integer value that is large by one than
            the most recent <A::SerialWalker.currentIndex> value
            when the <A::SerialWalker.currentNode> was
            same as the shiftted node.  If it is the first time
            the node is set to the <A::SerialWalker.currentNode>
            attribute, the <A::SerialWalker.currentIndex>
            attribute <kwd:MUST> set to zero.

          {LI:: Otherwise, determine whether the shifted node
                should be accepted or not, using 
                <A::SerialWalker.expandEntityReferences>,
                <A::SerialWalker.whatToShow>, and
                <A::SerialWalker.filter> attributes, as defined
                for the <IF::TreeWalker> interface.

             {LI:: If the node is <C::NodeFilter.FILTER_ACCEPT>ed,

                = Prepend the node to the queue, with
                  phase value set to <C::SerialWalker.POST_PHASE>.
 
                = Prepend the child nodes of the node, if any,
                  to the queue keeping the document order,
                  without phase value.  That is, the first child
                  <kwd:MUST> be located at the top (first
                  position) of the queue.

                = Prepend the node to the queue, with
                  phase value set to <C::SerialWalker.PRE_PHASE>.
               
                = If the node has a previous sibling in the logical view,
                  preprend the parent node of the node in the logical
                  view, with phase value set to <C::SerialWalker.IN_PHASE>.

                = Invoke the algorithm recursively.

             }

             {LI:: If the node is <C::NodeFilter.FILTER_SKIP>ped,

                = Prepend the child nodes of the node, if any,
                  to the queue keeping the document order,
                  without phase value.  That is, the first child
                  <kwd:MUST> be located at the top (first
                  position) of the queue.

                = Invoke the algorithm recursively.

             }

             {LI:: If the node is <C::NodeFilter.MANAKAI_FILTER_OPAQUE>,
 
                = Prepend the node to the queue, with
                  phase value set to <C::SerialWalker.POST_PHASE>.

                = Prepend the node to the queue, with
                  phase value set to <C::SerialWalker.PRE_PHASE>.
               
                = If the node has a previous sibling in the logical view,
                  preprend the parent node of the node in the logical
                  view, with phase value set to <C::SerialWalker.IN_PHASE>.

                = Invoke the algorithm recursively.

             }

             - Otherwise, invoke the algorithm recursively.

          }
       }

    }

    {NOTE::
      This algorithm will stop unless nodes are simulataneously
      populated to the underlying tree by application via
      e.g. <IF::NodeFilter>.
    }

    Implementation <kwd:MAY> choose to implement the <IF::SerialWalker>
    using another algorithm.  In particular, when the <IF::NodeFilter>
    is invoked might vary across implementations.  Implementations
    should try to return the same effect as the reference algorithm
    even if the underlying subtree is modified, but applications
    <kwd:MUST-NOT> rely on the particular implementation's behavior.

    As long as the underlying subtree is not modified, a node will
    never set to the <A::SerialWalker.currentNode> attribute
    with the <A::SerialWalker.currentPhase> of <C::SerialWalker.PRE_PHASE>.
    If the underlying subtree is modified, depending on how
    the method is implemented, it might be in case.  For 
    the purpose of description below, such duplication was considered
    as if they were different nodes.

    {P:: Even if the underlying subtree has been modified during
         the traversal, the implementation <kwd:MUST> ensure
         the following conditions are met:

      - A node <kwd:MUST-NOT> be set to the <A::SerialWalker.currentNode>
        attribute with the <A::SerialWalker.currentPhase> of
        <C::SerialWalker.PRE_PHASE> or <C::SerialWalker.POST_PHASE>
        more than once respectively.

      - A node <kwd:MUST-NOT> be set to the <A::SerialWalker.currentNode>
        attribute with the <A::SerialWalker.currentPhase> of
        <C::SerialWalker.IN_PHASE> before it is once set to
        the same node with the <A::SerialWalker.currentPhase>
        of <C::SerialWalker.PRE_PHASE>, or after it is once set
        to the same node with the <A::SerialWalker.currentPhase>
        of <C::SerialWalker.POST_PHASE>.

      - A node <kwd:MUST-NOT> be set to the <A::SerialWalker.currentNode>
        attribute with the <A::SerialWalker.currentPhase> of
        <C::SerialWalker.POST_PHASE> before it is once set to
        the same node with the <A::SerialWalker.currentPhase>
        of <C::SerialWalker.PRE_PHASE>.

      - A node <kwd:MUST> be set to the <A::SerialWalker.currentNode>
        attribute with the <A::SerialWalker.currentPhase> of
        <C::SerialWalker.POST_PHASE> later if it is once set to
        the same node with the <A::SerialWalker.currentPhase>
        of <C::SerialWalker.PRE_PHASE>.

      - The <A::SerialWalker.currentPhase> <kwd:MUST-NOT> set
        to <C::SerialWalker.PRE_PHASE> unless its value is
        <C::SerialWalker.PRE_PHASE> or <C::SerialWalker.IN_PHASE>.

      - The <A::SerialWalker.currentPhase> <kwd:MUST-NOT> set
        to <C::SerialWalker.IN_PHASE> unless its value is
        <C::SerialWalker.POST_PHASE>.

      - The <A::SerialWalker.currentPhase> <kwd:MUST-NOT> set
        to <C::SerialWalker.POST_PHASE> unless its value is
        <C::SerialWalker.PRE_PHASE> or <C::SerialWalker.POST_PHASE>.

      - If a node <VAR::N> is set to the <A::SerialWalker.currentNode>
        attribute and then another node <VAR::M> is set to the attribute
        with both <A::SerialWalker.currentPhase> of <C::SerialWalker.PRE_PHASE>,
        the <A::SerialWalker.currentNode> attribute <kwd:MUST-NOT> be set to
        <VAR::N> with <A::SerialWalker.currentPhase> of
        <C::SerialWalker.POST_PHASE> before once the
        <A::SerialWalker.currentNode> attribute is set to
        <VAR::M> with <A::SerialWalker.currentPhase> of 
        <C::SerialWalker.POST_PHASE>.

      - For each time the <A::SerialWalker.currentNode> attribute is
        set to a node, the <A::SerialWalker.currentIndex> <kwd:MUST>
        be increased by one.  If the node is set to the attribute
        for the first time, the <A::SerialWalker.currentIndex> 
        <kwd:MUST> be set to zero.  That is, with and only with
        <C::SerialWalker.PRE_PHASE> the <A::SerialWalker.currentIndex>
        can be zero.
    }

  @LXAttr:
    @@Name: root
    @@enDesc:
      The root node of the <IF::SerialWalker>.
    @@Type: Node
    @@Get:
      @@@enDesc:
        The root node set when the <IF::SerialWalker> is created.

  @LXAttr:
    @@Name: currentNode
    @@enDesc:
      The current node of the <IF::SerialWalker>.

        {NOTE::
          Unlike <IF::TreeWalker>, the <A::SerialWalker.currentNode>
          attribute is read-only.
        }
    @@Type: Node
    @@Get:
      @@@enDesc:
        The current node.

  @mShortConstGroup:
    @@IFQName: SerialWalkerPhase
    @@enDesc:
      An integer to indicate a phase of <IF::SerialWalker>.

    @@mConst:
      @@@Name: PRE_PHASE
      @@@intValue: 1
      @@@enDesc:
        The <A::SerialWalker.currentNode> is visited by
        the <IF::SerialWalker> for the first time.  It is
        expected that the same node will be revisited
        with <A::SerialWalker.currentPhase> of 
        <C::SerialWalker.IN_PHASE> (optionally) and
        <C::SerialWalker.POST_PHASE> later.
    @@mConst:
      @@@Name: IN_PHASE
      @@@intValue: 2
      @@@enDesc:
        The <A::SerialWalker.currentNode> is visited
        by the <IF::SerialWalker>, not for the first
        or last time, between visitings to its two child nodes.
    @@mConst:
      @@@Name: POST_PHASE
      @@@intValue: 3
      @@@enDesc:
        The <A::SerialWalker.currentNode> is visited
        by the <IF::SerialWalker> for the last time.

  @LXAttr:
    @@Name: currentPhase
    @@enDesc:
      The current phase of the <IF::SerialWalker>.
    @@Type: unsignedShort
    @@actualType: SerialWalkerPhase
    @@Get:
      @@@enDesc:
        An integer to indicate the current phase.

  @LXAttr:
    @@Name: currentIndex
    @@enDesc:
      The current index of the <IF::SerialWalker>.  The 
      <DFN::current index> represents how many times the
      <A::SerialWalker.currentNode> is exposed through
      the <IF::SerialWalker>.
    @@Type: unsignedLong
    @@Get:
      @@@enDesc:
        An integer to indicate the current index.

  @LXAttr:
    @@Name: expandEntityReferences
    @@enDesc:
      The value of the flag that determines whether the children of
      <IF::tx|EntityReference> nodes are visible to the <IF::SerialWalker>.

      {NOTE::
        To produce a view of the document that has entity references
        expanded and does not expose the <IF::tx|EntityReference> nodes
        themselves, use the <A::SerialWalker.whatToShow> flags to hide the
        <IF::tx|EntityReference> nodes and set the
        <A::SerialWalker.expandEntityReferences> flag to <DOM::true>
        when creating the <IF::SerialWalker>.

        To produce a view of the document that has <IF::tx|EntityReference>
        nodes but no entity expansion, use the <A::SerialWalker.whatToShow>
        flags to show the <IF::tx|EntityReference> nodes and set the
        <A::SerialWalker.expandEntityReferences> flag to <DOM::false>
        when creating the <IF::SerialWalker>.
      }
    @@Type: boolean
    @@Get:
      @@@enDesc:
        The <CODE::entityReferenceExpansion> value that
        was specified when the <IF::SerialWalker> was created.
      @@@TrueCase:
        @@@@enDesc:
          The children and their descendants of <IF::tx|EntityReference>
          nodes will <EM::not> be rejected.  Note that
          the <A::SerialWalker.whatToShow> flags and the
          <A::SerialWalker.filter> set to the <IF::SerialWalker>
          might reject them as usual way.
      @@@FalseCase:
        @@@@enDesc:
          The children and their descendants of entity reference nodes
          will be rejected.  This rejection takes precedence over
          the <A::SerialWalker.whatToShow> flags and the
          <A::SerialWalker.filter> set to the 
          <IF::SerialWalker>, if any.

  @LXAttr:
    @@Name: filter
    @@enDesc:
      The filter used to screen nodes.
    @@Type: NodeFilter
    @@Get:
      @@@enDesc:
        The <IF::NodeFilter> that was specified when the
        <IF::SerialWalker> was created.
      @@@nullCase:
        @@@@enDesc:
          If no <IF::NodeFilter> was specified when the
          <IF::SerialWalker> was created.

  @LXAttr:
    @@Name: whatToShow
    @@enDesc:
      The flags that determines which node types are presented
      via the <IF::SerialWalker>.  The available set of constants
      is defined in the <IF::NodeFilter> interface.

      Nodes not accepted by the <A::SerialWalker.whatToShow>
      flags will be skipped, but their children may still be
      considered.  This skip takes precedence over the 
      <A::SerialWalker.filter> set to the <IF::SerialWalker>, if any.
    @@Type: unsignedShort
    @@actualType: WhatToShow
    @@Get:
      @@@enDesc:
        The <CODE::whatToShow> value that was specified
        when the <IF::SerialWalker> was created.

  @LXMethod:
    @@Name: nextNode
    @@enDesc:
      Returns the node next to the <A::SerialWalker.currentNode>
      of the <IF::SerialWalker>.
    @@Return:
      @@@Type: Node
      @@@enDesc:
        The next node.
      @@@nullCase:
        @@@@enDesc:
          If no next node.

=cut

=head1 LICENSE

Copyright 2007 Wakaba <[email protected]>

This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=cut

1;
## $Date: 2007/07/14 09:19:11 $
1	wakaba	1.1	package Message::DOM::SerialWalker;
2			use strict;
3			our $VERSION=do{my @r=(q$Revision: 1.8 $=~/\d+/g);sprintf "%d."."%02d" x $#r,@r};
4			push our @ISA, 'Message::IF::SerialWalker';
5
6			sub AUTOLOAD {
7			my $method_name = our $AUTOLOAD;
8			$method_name =~ s/.*:://;
9			return if $method_name eq 'DESTROY';
10
11			if ({
12			current_index => 1,
13			current_node => 1,
14			current_phase => 1,
15			expand_entity_references => 1,
16			filter => 1,
17			root => 1,
18			what_to_show => 1,
19			}->{$method_name}) {
20			no strict 'refs';
21			eval qq{
22			sub $method_name (\$) { \$_[0]->{$method_name} }
23			};
24			goto &{ $AUTOLOAD };
25			} else {
26			require Carp;
27			Carp::croak (qq<Can't locate method "$AUTOLOAD">);
28			}
29			} # AUTOLOAD
30
31			## \|SerialWalker\| constants
32
33			## \|SerialWalkerPhase\|
34			sub PRE_PHASE () { 1 }
35			sub IN_PHASE () { 2 }
36			sub POST_PHASE () { 3 }
37
38			## \|SerialWalker\| attributes
39
40			sub current_index ($);
41
42			sub current_node ($);
43
44			sub current_phase ($);
45
46			sub expand_entity_references ($);
47
48			sub filter ($);
49
50			sub root ($);
51
52			sub what_to_show ($);
53
54			## \|SerialWalker\| methods
55
56			sub next_node ($) {
57			my $self = $_[0];
58
59			A: {
60			unless (@{$self->{next}}) {
61			#
62			} elsif ($self->{next}->[0]->[1] != 0) {
63			my $v = shift @{$self->{next}};
64			$self->{current_phase} = $v->[1];
65			$self->{current_index} = $self->{_index}->{$v->[2]}++;
66			return ($self->{current_node} = $v->[0]);
67			} else {
68			my $v = shift @{$self->{next}};
69			my $vresult = $self->_test_node ($v->[0]);
70
71			my @pnext;
72			if ($vresult == 1) { # FILTER_ACCEPT
73			my $key = $v->[2].'.'.$self->{_index}->{$v->[2]};
74
75			push @pnext, [$v->[3], IN_PHASE, $v->[4]]
76			if defined $v->[3] and $self->{_index}->{$v->[4].'.1'};
77
78			$self->{_index}->{$key} = 0;
79			push @pnext, [$v->[0], PRE_PHASE, $key];
80
81			push @pnext, [$_, 0, $key, $v->[0], $key]
82			for @{$v->[0]->child_nodes};
83			push @pnext, [$v->[0], POST_PHASE, $key];
84			} elsif ($vresult == 3) { # FILTER_SKIP
85			push @pnext, [$_, 0, $v->[2], $v->[3], $v->[4]]
86			for @{$v->[0]->child_nodes};
87			} elsif ($vresult == 12101) { # MANAKAI_FILTER_OPAQUE
88			my $key = $v->[2].'.'.$self->{_index}->{$v->[2]};
89
90			push @pnext, [$v->[3], IN_PHASE, $v->[4]]
91			if defined $v->[3] and $self->{_index}->{$v->[4].'.1'};
92
93			$self->{_index}->{$key} = 0;
94			push @pnext, [$v->[0], PRE_PHASE, $key];
95			push @pnext, [$v->[0], POST_PHASE, $key];
96			}
97			unshift @{$self->{next}}, @pnext;
98			redo A;
99			}
100			} # A
101
102			return undef;
103			} # next_node
104
105			sub _test_node ($$) {
106			## NOTE: There is a code clone in \|TreeWalker.pm\|.
107
108			unless ($_[0]->{expand_entity_references}) {
109			my $parent = $_[1]->parent_node;
110			if (defined $parent and $parent->node_type == 5) { # ENTITY_REFERENCE_NODE
111			return 2; # FILTER_REJECT ## NOTE: Even if \|NodeIterator\|.
112			}
113			}
114
115			if ($_[0]->{what_to_show} != 0xFFFFFFFF) { # SHOW_ALL
116			my $nt = $_[1]->node_type;
117			if ($nt < 33 and ($_[0]->{what_to_show} & (1 << ($nt-1)))) {
118			#
119			} else {
120			return 3; # FILTER_SKIP
121			}
122			}
123
124			if (defined $_[0]->{filter}) {
125			local $Error::Depth = $Error::Depth + 1;
126			return $_[0]->{filter}->($_[1]);
127			} else {
128			return 1; # FILTER_ACCEPT
129			}
130			} # _test_node
131
132			package Message::IF::SerialWalker;
133
134			package Message::DOM::Document;
135
136			sub manakai_create_serial_walker ($$;$$$) {
137			unless (defined $_[1]) {
138			require Message::DOM::DOMException;
139			report Message::DOM::DOMException
140			-object => $_[0],
141			-type => 'NOT_SUPPORTED_ERR',
142			-subtype => 'NULLPO_ERR';
143			}
144
145			## TODO: Initials for current_index and current_phase
146			return bless {
147			root => $_[1],
148			what_to_show => 0+($_[2] or 0),
149			filter => $_[3],
150			expand_entity_references => $_[4] ? 1 : 0,
151			current_node => $_[1],
152			next => [[$_[1], 0, '']],
153			_index => {'' => 0},
154			}, 'Message::DOM::SerialWalker';
155			} # manakai_create_serial_walker
156
157			=pod
158
159			## TODO: Documentation
160
161			@LXMethod:
162			@@Name: manakaiCreateSerialWalker
163			@@enDesc:
164			Creates a new <IF::SerialWalker> object.
165			@@Param:
166			@@@Name: root
167			@@@Type: Node
168			@@@enDesc:
169			The node that will serve as the root for the <IF::SerialWalker>.
170
171			The <P::whatToShow> flags and the <IF::NodeFilter>
172			are not considered when setting this value; any node type
173			will be accepted as the root.
174
175			The <A::TreeWalker.currentNode> of the created <IF::TreeWalker>
176			is initialized to the <P::root> node, whether or not it
177			is visible.
178
179			The <P::root> functions as a stopping point for traversal
180			methods that look upwards in the document structure, i.e.
181			<M::SerialWalker.nextNode>.
182
183			The <P::root> <kwd:MUST-NOT> be <DOM::null>. If it is,
184			the implementation <kwd:MUST> throw an exception.
185			@@Param:
186			@@@Name: whatToShow
187			@@@Type: unsignedShort
188			@@@actualType: WhatToShow
189			@@@enDesc:
190			The flags that specifies which node types may appear in the
191			logical view of the tree presented by the <IF::SerialWalker>.
192
193			The set of the flags are defined in the <IF::NodeFilter> interface.
194			They can be combined using the binary <CODE::OR> operation.
195			@@Param:
196			@@@Name: filter
197			@@@Type: NodeFilter
198			@@@enDesc:
199			The <IF::NodeFilter> to be used with the created <IF::SerialWalker>.
200			@@@nullCase:
201			@@@@enDesc:
202			Indicates that no filter is used.
203			@@Param:
204			@@@Name: entityReferenceExpansion
205			@@@Type: boolean
206			@@@enDesc:
207			The <A::SerialWalker.expandEntityReferences> flag of
208			the created <IF::TreeWalker>.
209			@@@TrueCase:
210			@@@@enDesc:
211			The contents of the <IF::tx\|EntityReference> nodes
212			<EM::are> presented in the logical view.
213			@@@FalseCase:
214			@@@@enDesc:
215			The contents of the <IF::tx\|EntityReference> nodes
216			are <EM::not> presented in the logical view.
217			@@Return:
218			@@@Type: SerialWalker
219			@@@enDesc:
220			{P:: The newly created <IF::SerialWalker>. It <kwd:MUST>
221			have attributes set as:
222
223			- <A::SerialWalker.currentNode>::: <P::root>.
224
225			- <A::SerialWalker.expandEntityReferences>:::
226			<P::entityReferenceExpansion>.
227
228			- <A::SerialWalker.filter>::: <P::filter>.
229
230			- <A::SerialWalker.root>::: <P::root>.
231
232			- <A::SerialWalker.whatToShow>::: <P::whatToShow>.
233
234			}
235			@@@dx:raises:
236			@@@@@: c\|SET_TO_NULL_ERR
237			@@@@enDesc:
238			If the specified <P::root> is <DOM::null>.
239			{ISSUE::
240			Better name?
241			}
242
243			A <IF::SerialWalker> object can be used to traverse
244			the subtree rooted by a node in document order.
245			Unlike <IF::TreeWalker> and <IF::NodeIterator>, the
246			<IF::SerialWalker> object cannot go back toward
247			nodes that had already been seen. The
248			<IF::SerialWalker>, however, revisits a node after its
249			children are visited. This might be useful when
250			an application wants to serialize a subtree in a format
251			where delimiter and / or terminator should be inserted
252			between and / or after nodes.
253
254			How the <IF::SerialWalker> works is defined by the following
255			reference algorithm. An implementation does not have to
256			implement this exact algorithm, but it <kwd:MUST> implement
257			its method so that it has the same effect as the
258			reference algorithm when the underlying subtree has not
259			been modified.
260
261			At the time of creation of the <IF::SerialWalker>,
262			the implementation <kwd:MUST> prepare a queue and
263			<kwd:MUST> initialize it by pushing the <A::SerialWalker.root> node.
264
265			{P:: When the <M::SerialWalker.nextNode> method is invoked,
266
267			- If the queue is empty, the method <kwd:MUST> return
268			<DOM::null>. It <kwd:MUST-NOT> change
269			<A::SerialWalker.currentNode>, <A::SerialWalker.currentPhase>,
270			and <A::SerialWalker.currentIndex> attributes.
271
272			{LI:: Otherwise,
273
274			- Shift a node from the queue. If the node has
275			the phase value, the method <kwd:MUST> return
276			the node. In addition, it <kwd:MUST> set
277			the <A::SerialWalker.currentNode> attribute to the node,
278			the <A::SerialWalker.currentPhase> attribute to
279			the associated phase value, and the
280			<A::SerialWalker.currentIndex> attribute to
281			the integer value that is large by one than
282			the most recent <A::SerialWalker.currentIndex> value
283			when the <A::SerialWalker.currentNode> was
284			same as the shiftted node. If it is the first time
285			the node is set to the <A::SerialWalker.currentNode>
286			attribute, the <A::SerialWalker.currentIndex>
287			attribute <kwd:MUST> set to zero.
288
289			{LI:: Otherwise, determine whether the shifted node
290			should be accepted or not, using
291			<A::SerialWalker.expandEntityReferences>,
292			<A::SerialWalker.whatToShow>, and
293			<A::SerialWalker.filter> attributes, as defined
294			for the <IF::TreeWalker> interface.
295
296			{LI:: If the node is <C::NodeFilter.FILTER_ACCEPT>ed,
297
298			= Prepend the node to the queue, with
299			phase value set to <C::SerialWalker.POST_PHASE>.
300
301			= Prepend the child nodes of the node, if any,
302			to the queue keeping the document order,
303			without phase value. That is, the first child
304			<kwd:MUST> be located at the top (first
305			position) of the queue.
306
307			= Prepend the node to the queue, with
308			phase value set to <C::SerialWalker.PRE_PHASE>.
309
310			= If the node has a previous sibling in the logical view,
311			preprend the parent node of the node in the logical
312			view, with phase value set to <C::SerialWalker.IN_PHASE>.
313
314			= Invoke the algorithm recursively.
315
316			}
317
318			{LI:: If the node is <C::NodeFilter.FILTER_SKIP>ped,
319
320			= Prepend the child nodes of the node, if any,
321			to the queue keeping the document order,
322			without phase value. That is, the first child
323			<kwd:MUST> be located at the top (first
324			position) of the queue.
325
326			= Invoke the algorithm recursively.
327
328			}
329
330			{LI:: If the node is <C::NodeFilter.MANAKAI_FILTER_OPAQUE>,
331
332			= Prepend the node to the queue, with
333			phase value set to <C::SerialWalker.POST_PHASE>.
334
335			= Prepend the node to the queue, with
336			phase value set to <C::SerialWalker.PRE_PHASE>.
337
338			= If the node has a previous sibling in the logical view,
339			preprend the parent node of the node in the logical
340			view, with phase value set to <C::SerialWalker.IN_PHASE>.
341
342			= Invoke the algorithm recursively.
343
344			}
345
346			- Otherwise, invoke the algorithm recursively.
347
348			}
349			}
350
351			}
352
353			{NOTE::
354			This algorithm will stop unless nodes are simulataneously
355			populated to the underlying tree by application via
356			e.g. <IF::NodeFilter>.
357			}
358
359			Implementation <kwd:MAY> choose to implement the <IF::SerialWalker>
360			using another algorithm. In particular, when the <IF::NodeFilter>
361			is invoked might vary across implementations. Implementations
362			should try to return the same effect as the reference algorithm
363			even if the underlying subtree is modified, but applications
364			<kwd:MUST-NOT> rely on the particular implementation's behavior.
365
366			As long as the underlying subtree is not modified, a node will
367			never set to the <A::SerialWalker.currentNode> attribute
368			with the <A::SerialWalker.currentPhase> of <C::SerialWalker.PRE_PHASE>.
369			If the underlying subtree is modified, depending on how
370			the method is implemented, it might be in case. For
371			the purpose of description below, such duplication was considered
372			as if they were different nodes.
373
374			{P:: Even if the underlying subtree has been modified during
375			the traversal, the implementation <kwd:MUST> ensure
376			the following conditions are met:
377
378			- A node <kwd:MUST-NOT> be set to the <A::SerialWalker.currentNode>
379			attribute with the <A::SerialWalker.currentPhase> of
380			<C::SerialWalker.PRE_PHASE> or <C::SerialWalker.POST_PHASE>
381			more than once respectively.
382
383			- A node <kwd:MUST-NOT> be set to the <A::SerialWalker.currentNode>
384			attribute with the <A::SerialWalker.currentPhase> of
385			<C::SerialWalker.IN_PHASE> before it is once set to
386			the same node with the <A::SerialWalker.currentPhase>
387			of <C::SerialWalker.PRE_PHASE>, or after it is once set
388			to the same node with the <A::SerialWalker.currentPhase>
389			of <C::SerialWalker.POST_PHASE>.
390
391			- A node <kwd:MUST-NOT> be set to the <A::SerialWalker.currentNode>
392			attribute with the <A::SerialWalker.currentPhase> of
393			<C::SerialWalker.POST_PHASE> before it is once set to
394			the same node with the <A::SerialWalker.currentPhase>
395			of <C::SerialWalker.PRE_PHASE>.
396
397			- A node <kwd:MUST> be set to the <A::SerialWalker.currentNode>
398			attribute with the <A::SerialWalker.currentPhase> of
399			<C::SerialWalker.POST_PHASE> later if it is once set to
400			the same node with the <A::SerialWalker.currentPhase>
401			of <C::SerialWalker.PRE_PHASE>.
402
403			- The <A::SerialWalker.currentPhase> <kwd:MUST-NOT> set
404			to <C::SerialWalker.PRE_PHASE> unless its value is
405			<C::SerialWalker.PRE_PHASE> or <C::SerialWalker.IN_PHASE>.
406
407			- The <A::SerialWalker.currentPhase> <kwd:MUST-NOT> set
408			to <C::SerialWalker.IN_PHASE> unless its value is
409			<C::SerialWalker.POST_PHASE>.
410
411			- The <A::SerialWalker.currentPhase> <kwd:MUST-NOT> set
412			to <C::SerialWalker.POST_PHASE> unless its value is
413			<C::SerialWalker.PRE_PHASE> or <C::SerialWalker.POST_PHASE>.
414
415			- If a node <VAR::N> is set to the <A::SerialWalker.currentNode>
416			attribute and then another node <VAR::M> is set to the attribute
417			with both <A::SerialWalker.currentPhase> of <C::SerialWalker.PRE_PHASE>,
418			the <A::SerialWalker.currentNode> attribute <kwd:MUST-NOT> be set to
419			<VAR::N> with <A::SerialWalker.currentPhase> of
420			<C::SerialWalker.POST_PHASE> before once the
421			<A::SerialWalker.currentNode> attribute is set to
422			<VAR::M> with <A::SerialWalker.currentPhase> of
423			<C::SerialWalker.POST_PHASE>.
424
425			- For each time the <A::SerialWalker.currentNode> attribute is
426			set to a node, the <A::SerialWalker.currentIndex> <kwd:MUST>
427			be increased by one. If the node is set to the attribute
428			for the first time, the <A::SerialWalker.currentIndex>
429			<kwd:MUST> be set to zero. That is, with and only with
430			<C::SerialWalker.PRE_PHASE> the <A::SerialWalker.currentIndex>
431			can be zero.
432			}
433
434			@LXAttr:
435			@@Name: root
436			@@enDesc:
437			The root node of the <IF::SerialWalker>.
438			@@Type: Node
439			@@Get:
440			@@@enDesc:
441			The root node set when the <IF::SerialWalker> is created.
442
443			@LXAttr:
444			@@Name: currentNode
445			@@enDesc:
446			The current node of the <IF::SerialWalker>.
447
448			{NOTE::
449			Unlike <IF::TreeWalker>, the <A::SerialWalker.currentNode>
450			attribute is read-only.
451			}
452			@@Type: Node
453			@@Get:
454			@@@enDesc:
455			The current node.
456
457			@mShortConstGroup:
458			@@IFQName: SerialWalkerPhase
459			@@enDesc:
460			An integer to indicate a phase of <IF::SerialWalker>.
461
462			@@mConst:
463			@@@Name: PRE_PHASE
464			@@@intValue: 1
465			@@@enDesc:
466			The <A::SerialWalker.currentNode> is visited by
467			the <IF::SerialWalker> for the first time. It is
468			expected that the same node will be revisited
469			with <A::SerialWalker.currentPhase> of
470			<C::SerialWalker.IN_PHASE> (optionally) and
471			<C::SerialWalker.POST_PHASE> later.
472			@@mConst:
473			@@@Name: IN_PHASE
474			@@@intValue: 2
475			@@@enDesc:
476			The <A::SerialWalker.currentNode> is visited
477			by the <IF::SerialWalker>, not for the first
478			or last time, between visitings to its two child nodes.
479			@@mConst:
480			@@@Name: POST_PHASE
481			@@@intValue: 3
482			@@@enDesc:
483			The <A::SerialWalker.currentNode> is visited
484			by the <IF::SerialWalker> for the last time.
485
486			@LXAttr:
487			@@Name: currentPhase
488			@@enDesc:
489			The current phase of the <IF::SerialWalker>.
490			@@Type: unsignedShort
491			@@actualType: SerialWalkerPhase
492			@@Get:
493			@@@enDesc:
494			An integer to indicate the current phase.
495
496			@LXAttr:
497			@@Name: currentIndex
498			@@enDesc:
499			The current index of the <IF::SerialWalker>. The
500			<DFN::current index> represents how many times the
501			<A::SerialWalker.currentNode> is exposed through
502			the <IF::SerialWalker>.
503			@@Type: unsignedLong
504			@@Get:
505			@@@enDesc:
506			An integer to indicate the current index.
507
508			@LXAttr:
509			@@Name: expandEntityReferences
510			@@enDesc:
511			The value of the flag that determines whether the children of
512			<IF::tx\|EntityReference> nodes are visible to the <IF::SerialWalker>.
513
514			{NOTE::
515			To produce a view of the document that has entity references
516			expanded and does not expose the <IF::tx\|EntityReference> nodes
517			themselves, use the <A::SerialWalker.whatToShow> flags to hide the
518			<IF::tx\|EntityReference> nodes and set the
519			<A::SerialWalker.expandEntityReferences> flag to <DOM::true>
520			when creating the <IF::SerialWalker>.
521
522			To produce a view of the document that has <IF::tx\|EntityReference>
523			nodes but no entity expansion, use the <A::SerialWalker.whatToShow>
524			flags to show the <IF::tx\|EntityReference> nodes and set the
525			<A::SerialWalker.expandEntityReferences> flag to <DOM::false>
526			when creating the <IF::SerialWalker>.
527			}
528			@@Type: boolean
529			@@Get:
530			@@@enDesc:
531			The <CODE::entityReferenceExpansion> value that
532			was specified when the <IF::SerialWalker> was created.
533			@@@TrueCase:
534			@@@@enDesc:
535			The children and their descendants of <IF::tx\|EntityReference>
536			nodes will <EM::not> be rejected. Note that
537			the <A::SerialWalker.whatToShow> flags and the
538			<A::SerialWalker.filter> set to the <IF::SerialWalker>
539			might reject them as usual way.
540			@@@FalseCase:
541			@@@@enDesc:
542			The children and their descendants of entity reference nodes
543			will be rejected. This rejection takes precedence over
544			the <A::SerialWalker.whatToShow> flags and the
545			<A::SerialWalker.filter> set to the
546			<IF::SerialWalker>, if any.
547
548			@LXAttr:
549			@@Name: filter
550			@@enDesc:
551			The filter used to screen nodes.
552			@@Type: NodeFilter
553			@@Get:
554			@@@enDesc:
555			The <IF::NodeFilter> that was specified when the
556			<IF::SerialWalker> was created.
557			@@@nullCase:
558			@@@@enDesc:
559			If no <IF::NodeFilter> was specified when the
560			<IF::SerialWalker> was created.
561
562			@LXAttr:
563			@@Name: whatToShow
564			@@enDesc:
565			The flags that determines which node types are presented
566			via the <IF::SerialWalker>. The available set of constants
567			is defined in the <IF::NodeFilter> interface.
568
569			Nodes not accepted by the <A::SerialWalker.whatToShow>
570			flags will be skipped, but their children may still be
571			considered. This skip takes precedence over the
572			<A::SerialWalker.filter> set to the <IF::SerialWalker>, if any.
573			@@Type: unsignedShort
574			@@actualType: WhatToShow
575			@@Get:
576			@@@enDesc:
577			The <CODE::whatToShow> value that was specified
578			when the <IF::SerialWalker> was created.
579
580			@LXMethod:
581			@@Name: nextNode
582			@@enDesc:
583			Returns the node next to the <A::SerialWalker.currentNode>
584			of the <IF::SerialWalker>.
585			@@Return:
586			@@@Type: Node
587			@@@enDesc:
588			The next node.
589			@@@nullCase:
590			@@@@enDesc:
591			If no next node.
592
593			=cut
594
595			=head1 LICENSE
596
597			Copyright 2007 Wakaba <[email protected]>
598
599			This program is free software; you can redistribute it and/or
600			modify it under the same terms as Perl itself.
601
602			=cut
603
604			1;
605			## $Date: 2007/07/14 09:19:11 $