Regexp/Visualize/Simple.pod

=head1 NAME

Regexp::Visualize::Simple - Regular expression visualization using Graph::Easy

=head1 SYNOPSIS

  use Regexp::Visualize::Simple
  
  $parser = ... Regexp::Parser object ...;
  
  my $v = Regexp::Visualize::Simple->new;
  $v->push_regexp_node ($parser->root);
  
  while ($v->has_regexp_node) {
    my ($g, $index) = $v->next_graph;
    
    # $g is a Graph::Easy object
    print "$index:\n";
    print $g->as_svg;
  }

=head1 DESCRIPTION

The C<Regexp::Visualize::Simple> generates a series of C<Graph::Easy>
objects, which as a whole represents a regular expression parsed by
C<Regexp::Parser>.  Generated graphs can be exported to arbitrary
image format, such as PNG and SVG, supported by C<Graph::Easy>.  As an
input any regular expression dialect supported by C<Regexp::Parser> or
its subclasses can be used.

It is sometimes impossible or undesired to represents a regular
expression as one complete graph.  For example, if a regular
expression containing C<(?!...)> segment were represented as a graph,
it would be difficult to understand.  Therefore, the result
visualization might sometimes be split into multiple graphs.  This is
why this module defines iterator methods C<has_regexp_node> and
C<next_graph>.

=head1 METHODS

=over 4

=item I<$v> = Regexp::Visualize::Simple->new;

Creates a new instance of the regular expression visualizer.

=item I<$v>->push_regexp_node (I<$node>);

Push a regular expression node that represents a subgraph to be
visualized.

=item I<$node> = I<$v>->shift_regexp_node ();

Shifts a regular expression node from the queue hold by the visualizer
object, if any, or returns C<undef>.

=item I<$boolean> = I<$v>->has_regexp_node ();

Returns whether the visualizer object contains one or more nodes in
the queue of regular expression nodes to be graphized.

=item (I<$g>, I<$index>) = I<$v>->next_graph ();

Generates a graph from the first node in the queue o the regular
expression node hold by the visualizer object.

If there is no node to be graphized in the queue, then a list of two
C<undef> values is returned.

Otherwise, a list of the C<Graph::Easy> object generated from the
regular expression node and the index number of the graph is returned.
The first graph generated by the visualizer object has the index of
zero (C<0>), and the next graph has one (C<1>).

=back

=head1 DEPENDENCY

This module requires Perl 5.10.0 or later.

This module depends on the C<Graph::Easy> module.

This module assumes the input regular expression nodes implementing
C<Regexp::Parser>-compatible interface.  Such modules include
C<Regexp::Parser::Perl58> and C<Regexp::Parser::JavaScript>.

=head1 SEE ALSO

The latest version of this module is available at
L<http://suika.fam.cx/regexp/>.

Regular expression visualizer
L<http://suika.fam.cx/regexp/visualizer/input>.  This is a Web
interface for this module.  Its source code is available at
L<http://suika.fam.cx/regexp/visualizer/regexp.cgi,cvslog>.

L<Regexp::Parser::Perl58> - A subclass of C<Regexp::Parser> supporting
Perl 5.8 regular expression syntax.

L<Regexp::Parser::JavaScript> - A subclass of C<Regexp::Parser>
supporting JavaScript regular expression syntax.

These two modules above are available at
L<http://suika.fam.cx/regexp/>.

L<Graph::Easy>.  This module is available from CPAN.

=head1 DEVELOPMENT

CVS log:
L<http://suika.fam.cx/regexp/lib/Regexp/Visualize/Simple.pm,cvslog>.

Bug tracking system: L<http://manakai.g.hatena.ne.jp/task/7/>.

=head2 TODO

Localization / customization support.

=head1 AUTHOR

Wakaba <w@suika.fam.cx>.

=head1 LICENSE

Copyright 2008-2009 Wakaba <w@suika.fam.cx>.

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

=cut

# $Date:$
1	wakaba	1.1	=head1 NAME
2
3			Regexp::Visualize::Simple - Regular expression visualization using Graph::Easy
4
5			=head1 SYNOPSIS
6
7			use Regexp::Visualize::Simple
8
9			$parser = ... Regexp::Parser object ...;
10
11			my $v = Regexp::Visualize::Simple->new;
12			$v->push_regexp_node ($parser->root);
13
14			while ($v->has_regexp_node) {
15			my ($g, $index) = $v->next_graph;
16
17			# $g is a Graph::Easy object
18			print "$index:\n";
19			print $g->as_svg;
20			}
21
22			=head1 DESCRIPTION
23
24			The C<Regexp::Visualize::Simple> generates a series of C<Graph::Easy>
25			objects, which as a whole represents a regular expression parsed by
26			C<Regexp::Parser>. Generated graphs can be exported to arbitrary
27			image format, such as PNG and SVG, supported by C<Graph::Easy>. As an
28			input any regular expression dialect supported by C<Regexp::Parser> or
29			its subclasses can be used.
30
31			It is sometimes impossible or undesired to represents a regular
32			expression as one complete graph. For example, if a regular
33			expression containing C<(?!...)> segment were represented as a graph,
34			it would be difficult to understand. Therefore, the result
35			visualization might sometimes be split into multiple graphs. This is
36			why this module defines iterator methods C<has_regexp_node> and
37			C<next_graph>.
38
39			=head1 METHODS
40
41			=over 4
42
43			=item I<$v> = Regexp::Visualize::Simple->new;
44
45			Creates a new instance of the regular expression visualizer.
46
47			=item I<$v>->push_regexp_node (I<$node>);
48
49			Push a regular expression node that represents a subgraph to be
50			visualized.
51
52			=item I<$node> = I<$v>->shift_regexp_node ();
53
54			Shifts a regular expression node from the queue hold by the visualizer
55			object, if any, or returns C<undef>.
56
57			=item I<$boolean> = I<$v>->has_regexp_node ();
58
59			Returns whether the visualizer object contains one or more nodes in
60			the queue of regular expression nodes to be graphized.
61
62			=item (I<$g>, I<$index>) = I<$v>->next_graph ();
63
64			Generates a graph from the first node in the queue o the regular
65			expression node hold by the visualizer object.
66
67			If there is no node to be graphized in the queue, then a list of two
68			C<undef> values is returned.
69
70			Otherwise, a list of the C<Graph::Easy> object generated from the
71			regular expression node and the index number of the graph is returned.
72			The first graph generated by the visualizer object has the index of
73			zero (C<0>), and the next graph has one (C<1>).
74
75			=back
76
77			=head1 DEPENDENCY
78
79			This module requires Perl 5.10.0 or later.
80
81			This module depends on the C<Graph::Easy> module.
82
83			This module assumes the input regular expression nodes implementing
84			C<Regexp::Parser>-compatible interface. Such modules include
85			C<Regexp::Parser::Perl58> and C<Regexp::Parser::JavaScript>.
86
87			=head1 SEE ALSO
88
89			The latest version of this module is available at
90			L<http://suika.fam.cx/regexp/>.
91
92			Regular expression visualizer
93			L<http://suika.fam.cx/regexp/visualizer/input>. This is a Web
94			interface for this module. Its source code is available at
95			L<http://suika.fam.cx/regexp/visualizer/regexp.cgi,cvslog>.
96
97			L<Regexp::Parser::Perl58> - A subclass of C<Regexp::Parser> supporting
98			Perl 5.8 regular expression syntax.
99
100			L<Regexp::Parser::JavaScript> - A subclass of C<Regexp::Parser>
101			supporting JavaScript regular expression syntax.
102
103			These two modules above are available at
104			L<http://suika.fam.cx/regexp/>.
105
106			L<Graph::Easy>. This module is available from CPAN.
107
108			=head1 DEVELOPMENT
109
110			CVS log:
111			L<http://suika.fam.cx/regexp/lib/Regexp/Visualize/Simple.pm,cvslog>.
112
113			Bug tracking system: L<http://manakai.g.hatena.ne.jp/task/7/>.
114
115			=head2 TODO
116
117			Localization / customization support.
118
119			=head1 AUTHOR
120
121			Wakaba <w@suika.fam.cx>.
122
123			=head1 LICENSE
124
125			Copyright 2008-2009 Wakaba <w@suika.fam.cx>.
126
127			This library is free software; you can redistribute it and/or modify
128			it under the same terms as Perl itself.
129
130			=cut
131
132			# $Date:$