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	=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:$