This file is indexed.

/usr/share/perl5/Text/Markup.pm is in libtext-markup-perl 0.23-2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
package Text::Markup;

use 5.8.1;
use strict;
use Text::Markup::None;
use Carp;

our $VERSION = '0.23';

my %_PARSER_FOR;
my %REGEX_FOR = (
    html          => qr{x?html?},
    markdown      => qr{m(?:d(?:own)?|kdn?|arkdown)},
    multimarkdown => qr{mm(?:d(?:own)?|kdn?|arkdown)},
    pod           => qr{p(?:od|m|l)},
    textile       => qr{textile},
    trac          => qr{tra?c},
    mediawiki     => qr{(?:m(?:edia)?)?wiki},
    rest          => qr{re?st},
    asciidoc      => qr{a(?:sc(?:iidoc)?|doc)?},
    bbcode        => qr{bb(?:code)?},
    creole        => qr{creole},
);

sub register {
    my ($class, $name, $regex) = @_;
    my $pkg = caller;
    $REGEX_FOR{$name}   = $regex;
    $_PARSER_FOR{$name} = $pkg->can('parser')
        or croak "No parser() function defind in $pkg";
}

sub _parser_for {
    my ($self, $format) = @_;
    return Text::Markup::None->can('parser') unless $format;
    return $_PARSER_FOR{$format} if $_PARSER_FOR{$format};
    my $pkg = __PACKAGE__ . '::' . ($format eq 'html' ? 'HTML' : ucfirst $format);
    eval "require $pkg; 1" or die $@;
    return $_PARSER_FOR{$format} = $pkg->can('parser')
        || croak "No parser() function defind in $pkg";
}

sub formats {
    sort keys %REGEX_FOR;
}

sub new {
    my $class = shift;
    bless { default_encoding => 'UTF-8', @_ } => $class;
}

sub parse {
    my $self = shift;
    my %p = @_;
    my $file = $p{file} or croak "No file parameter passed to parse()";
    croak "$file does not exist" unless -e $file && !-d _;

    my $parser = $self->_get_parser(\%p);
    return $parser->(
        $file,
        $p{encoding} || $self->default_encoding,
        $p{options}
    );
}

sub default_format {
    my $self = shift;
    return $self->{default_format} unless @_;
    $self->{default_format} = shift;
}

sub default_encoding {
    my $self = shift;
    return $self->{default_encoding} unless @_;
    $self->{default_encoding} = shift;
}

sub _get_parser {
    my ($self, $p) = @_;
    my $format = $p->{format}
        || $self->guess_format($p->{file})
        || $self->default_format;

    return $self->_parser_for($format);
}

sub guess_format {
    my ($self, $file) = @_;
    for my $format (keys %REGEX_FOR) {
        return $format if $file =~ qr{[.]$REGEX_FOR{$format}$};
    }
    return;
}

1;
__END__

=head1 Name

Text::Markup - Parse text markup into HTML

=head1 Synopsis

  my $parser = Text::Markup->new(
      default_format   => 'markdown',
      default_encoding => 'UTF-8',
  );

  my $html = $parser->parse(file => $markup_file);

=head1 Description

This class is really simple. All it does is take the name of a file and return
an HTML-formatted version of that file. The idea is that one might have files
in lots of different markups, and not know or care what markups each uses.
It's the job of this module to figure that out, parse it, and give you the
resulting HTML.

This distribution includes support for a number of markup formats:

=over

=item * L<Asciidoc|http://www.methods.co.nz/asciidoc/>

=item * L<BBcode|http://www.bbcode.org/>

=item * L<Creole|http://www.wikicreole.org/>

=item * L<HTML|http://whatwg.org/html>

=item * L<Markdown|http://daringfireball.net/projects/markdown/>

=item * L<MultiMarkdown|http://fletcherpenney.net/multimarkdown/>

=item * L<MediaWiki|http://en.wikipedia.org/wiki/Help:Contents/Editing_Wikipedia>

=item * L<Pod|perlpod>

=item * L<reStructuredText|http://docutils.sourceforge.net/docs/user/rst/quickref.html>

=item * L<Textile|http://textism.com/tools/textile/>

=item * L<Trac|http://trac.edgewall.org/wiki/WikiFormatting>

=back

Adding support for more markup languages is straight-forward, and patches
adding them to this distribution are also welcome. See L</Add a Parser> for
step-by-step instructions.

Or if you just want to use this module, then read on!

=head1 Interface

=head2 Constructor

=head3 C<new>

  my $parser = Text::Markup->new(default_format => 'markdown');

Supported parameters:

=over

=item C<default_format>

The default format to use if one isn't passed to C<parse()> and one can't be
guessed.

=item C<default_encoding>

The character encoding in which to assume a file is encoded if it's not
otherwise explicitly determined by examination of the source file. Defaults to
"UTF-8".

=back

=head2 Class Methods

=head3 C<register>

  Text::Markup->register(foobar => qr{fb|foob(?:ar)?});

Registers a markup parser. You likely won't need to use this method unless
you're creating a new markup parser and not contributing it back to the
Text::Markup project. See L</Add a Parser> for details.

=head3 formats

  my @formats = Text::Markup->formats;

Returns a list of all of the formats currently recognized by Text::Markup.
This will include all core parsers (except for "None") and any that have been
loaded elsewhere and that call C<register> to register themselves.

=head2 Instance Methods

=head3 C<parse>

  my $html = $parser->parse(file => $file_to_parse);

Parses a file and return the generated HTML, or C<undef> if no markup was
found in the file. Supported parameters:

=over

=item C<file>

The file from which to read the markup to be parsed. Required.

=item C<format>

The markup format in the file, which determines the parser used to parse it.
If not specified, Text::Markup will try to guess the format from the file's
suffix. If it can't guess, it falls back on C<default_format>. And if that
attribute is not set, it uses the C<none> parser, which simply encodes the
entire file and wraps it in a C<< <pre> >> element.

=item C<encoding>

The character encoding to assume the source file is encoded in (if such cannot
be determined by other means, such as a
L<BOM|http://en.wikipedia.org/wiki/Byte_order_mark>). If not specified, the
value of the C<default_encoding> attribute will be used, and if that attribute
is not set, UTF-8 will be assumed.

=item C<options>

An array reference of options for the parser. See the documentation of the
various parser modules for details.

=back

=head3 C<default_format>

  my $format = $parser->default_format;
  $parser->default_format('markdown');

An accessor for the default format attribute.

=head3 C<default_encoding>

  my $encoding = $parser->default_encoding;
  $parser->default_encoding('Big5');

An accessor for the default encoding attribute.

=head3 C<guess_format>

  my $format = $parser->guess_format($filename);

Compares the passed file name's suffix to the regular expressions of all
registered formatting parser and returns the first one that matches. Returns
C<undef> if none matches.

=head1 Add a Parser

Adding support for markup formats not supported by the core Text::Markup
distribution is a straight-forward exercise. Say you wanted to add a "FooBar"
markup parser. Here are the steps to take:

=over

=item 1

Fork L<this project on GitHub|https://github.com/theory/text-markup/>

=item 2

Clone your fork and create a new branch in which to work:

  git clone git@github.com:$USER/text-markup.git
  cd text-markup
  git checkout -b foobar

=item 3

Create a new module named C<Text::Markup::FooBar>. The simplest thing to do is
copy an existing module and modify it. The HTML parser is probably the simplest:

  cp lib/Text/Markup/HTML.pm lib/Text/Markup/FooBar.pm
  perl -i -pe 's{HTML}{FooBar}g' lib/Text/Markup/FooBar.pm
  perl -i -pe 's{html}{foobar}g' lib/Text/Markup/FooBar.pm

=item 4

Implement the C<parser> function in your new module. If you were to use a
C<Text::FooBar> module, it might look something like this:

  package Text::Markup::FooBar;

  use 5.8.1;
  use strict;
  use Text::FooBar ();
  use File::BOM qw(open_bom)

  sub parser {
      my ($file, $encoding, $opts) = @_;
      my $md = Text::FooBar->new(@{ $opts || [] });
      open_bom my $fh, $file, ":encoding($encoding)";
      local $/;
      my $html = $md->parse(<$fh>);
      return unless $html =~ /\S/;
      utf8::encode($html);
      return join( "\n",
          '<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />',
          '</head>',
          '<body>',
          $html,
          '</body>',
          '</html>',
      );
  }

Use the C<$encoding> argument as appropriate to read in the source file. If
your parser requires that text be decoded to Perl's internal form, use of
L<File::BOM> is recommended, so that an explicit BOM will determine the
encoding. Otherwise, fall back on the specified encoding. Note that some
parsers, such as an HTML parser, would want text encoded before it parsed it.
In such a case, read in the file as raw bytes:

      open my $fh, '<:raw', $file or die "Cannot open $file: $!\n";

The returned HTML, however, B<must be encoded in UTF-8>. Please include an
L<encoding
declaration|http://en.wikipedia.org/wiki/Character_encodings_in_HTML>, such as
a content-type C<< <meta> >> element:

  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

This will allow any consumers of the returned HTML to parse it correctly.
If the parser parsed no content, C<parser()> should return C<undef>.

=item 5

Edit F<lib/Text/Markup.pm> and add an entry to its C<%REGEX_FOR> hash for your
new format. The key should be the name of the format (lowercase, the same as
the last part of your module's name). The value should be a regular expression
that matches the file extensions that suggest that a file is formatted in your
parser's markup language. For our FooBar parser, the line might look like
this:

    foobar => qr{fb|foob(?:ar)?},

=item 6

Add a file in your parser's markup language to F<t/markups>. It should be
named for your parser and end in F<.txt>, that is, F<t/markups/foobar.txt>.

=item 7

Add an HTML file, F<t/html/foobar.html>, which should be the expected output
once F<t/markups/foobar.txt> is parsed into HTML. This will be used to test
that your parser works correctly.

=item 8

Edit F<t/formats.t> by adding a line to its C<__DATA__> section. The line
should be a comma-separated list describing your parser. The columns are:

=over

=item * Format

The lowercased name of the format.

=item * Format Module

The name of the parser module.

=item * Required Module

The name of a module that's required to be installed in order for your parser
to load.

=item * Extensions

Additional comma-separated values should be a list of file extensions that
your parser should recognize.

=back

So for our FooBar parser, it might look like this:

  markdown,Text::Markup::FooBar,Text::FooBar 0.22,fb,foob,foobar

=item 9

Test your new parser by running

  prove -lv t/formats.t

This will test I<all> included parsers, but of course you should only pay
attention to how your parser works. Tweak until your tests pass. Note that one
test has the parser parse a file with just a couple of empty lines, to ensure
that the parser finds no content and returns C<undef>.

=item 10

Don't forget to write the documentation in your new parser module! If you
copied F<Text::Markup::HTML>, you can just modify as appropriate.

=item 11

Add any new module requirements to the C<requires> section of F<Build.PL>.

=item 12

Commit and push the branch to your fork on GitHub:

  git add .
  git commit -am 'Add great new FooBar parser!'
  git push origin -u foobar

=item 13

And finally, submit a pull request to the upstream repository via the GitHub
UI.

=back

If you don't want to submit your parser, you can still create and use one
independently. Rather than add its information to the C<%REGEX_FOR> hash in
this module, you can just load your parser manually, and have it call the
C<register> method, like so:

  package My::Markup::FooBar;
  use Text::Markup;
  Text::Markup->register(foobar => qr{fb|foob(?:ar)?});

This will be useful for creating private parsers you might not want to
contribute, or that you'd want to distribute independently.

=head1 See Also

=over

=item *

The L<markup|https://github.com/github/markup> Ruby library -- the inspiration
for this module -- provides similar functionality, and is used to parse
F<README.your_favorite_markup> on GitHub.

=item *

L<Markup::Unified> offers similar functionality.

=back

=head1 Support

This module is stored in an open L<GitHub
repository|http://github.com/theory/text-markup/>. Feel free to fork and
contribute!

Please file bug reports via L<GitHub
Issues|http://github.com/theory/text-markup/issues/> or by sending mail to
L<bug-Text-Markup@rt.cpan.org|mailto:bug-Text-Markup@rt.cpan.org>.

=head1 Author

David E. Wheeler <david@justatheory.com>

=head1 Copyright and License

Copyright (c) 2011-2014 David E. Wheeler. Some Rights Reserved.

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

=cut