1package Text::AsciiTeX;
2
3use strict;
4use warnings;
5
6use parent 'Exporter';
7
8our $VERSION = '0.05';
9$VERSION = eval $VERSION;
10
11require XSLoader;
12XSLoader::load('Text::AsciiTeX', $VERSION);
13
14our @EXPORT = ( qw/ render / );
15
16sub render {
17  my ($eq, $columns) = @_;
18
19  # defaults
20  $eq ||= '';
21  $columns = (defined $columns) ? $columns : 80;
22
23  my $text_array = c_render($eq, $columns);
24
25  my $wantarray = wantarray;
26
27  if ($wantarray) {
28    return @$text_array;
29  }
30
31  my $text_string = join( "\n", @$text_array ) . "\n";
32
33  if (defined $wantarray) {
34    return $text_string;
35  }
36
37  print $text_string;
38  return;
39}
40
411;
42
43__END__
44
45__POD__
46
47=head1 NAME
48
49Text::AsciiTeX - Convert (La)TeX formulas to ASCII art
50
51=head1 SYNOPSIS
52
53 use Text::AsciiArt;
54
55 #equivalent examples
56
57 my @text_array = render('\frac{1}{e}');
58 print "$_\n" for @text_array;
59
60 my $text_array = render('\frac{1}{e}');
61 print $text_array;
62
63 print scalar render('\frac{1}{e}');
64
65 render('\frac{1}{e}');
66
67=head1 DESCRIPTION
68
69This module provides a mechanism to render (La)TeX formulae to ASCII art. It is based solely on F<AsciiTeX> written by Bart Pieters (See L</"UNDERLYING TECHNOLOGIES">).
70
71=head1 EXPORTED FUNCTION
72
73This module exports the C<render> function.
74
75=head2 C<< render( $latex [, $columns] ) >>
76
77=head3 Argument(s)
78
79The function C<render> accepts a string containing a formula in (La)TeX formatting. Optionally, an integer may be given to specify the number of columns for the output or zero for no-breaking. The default number of columns is 80.
80
81=head3 Return
82
83Since version 0.03 the return value is context aware.
84
85=over
86
87=item *
88
89In list context, C<render> returns a list whose elements are strings, one for each row of the art. Printing each line, terminated by a newline will probably do what you expect.
90
91=item *
92
93In scalar context, C<render> will return a string of the concatenated lines, each ended with a newline.
94
95=item *
96
97In void context, C<render> will print the scalar context return directly to the C<select>ed file handle (usually C<STDOUT>).
98
99=back
100
101=head1 EXAMPLES
102
103For use examples see L</SYNOPSIS>. For a list of allowed syntax and syntax examples read L<Text::AsciiTeX::Syntax>.
104
105=head1 UNDERLYING TECHNOLOGIES
106
107This module is basically just a C-level Perl wrapper of F<AsciiTeX> written by Bart Pieters. That project is hosted at L<http://asciitex.sourceforge.net/>. F<AsciiTeX> in turn was a fork of F<eqascii> which was written by Przemek Borys. This module owes a debt of thanks to both authors.
108
109=head1 SOURCE REPOSITORY
110
111L<http://github.com/jberger/Text::AsciiTeX>
112
113=head1 AUTHOR
114
115Joel Berger, E<lt>joel.a.berger@gmail.comE<gt>
116
117=head1 COPYRIGHT AND LICENSE
118
119Copyright (C) 2012 by Joel Berger
120
121This library is free software; you can redistribute it and/or modify
122it under the same terms as Perl itself.
123