Documentation for direct use of modules

Posted on 2007-05-15 09:19:12-07 by dataweaver

I'm looking to write a Mason-driven wiki engine based on reStructured Text. As such, I have less need of a command-line parser than of a Perl module that I can have my Mason pages use. The sort of documentation that I'd find most useful is not how to use prest, but rather how to use Text::Restructured.

Direct Responses: 5575 | Write a response

Posted on 2007-06-29 15:47:57-07 by rsthacker in response to 5134

Re: Documentation for direct use of modules

Sorry to take so long to respond, but I didn't even know this forum was here... There is some documentation under Prest Internals.
Basically, what you want to do is call

use Text::Restructured::Writer; my $writer = new Text::Restructured::Writer($writer_name, \%opt);

to instantiate a writer with a given name (probably 'html') and set of options such as are accepted by prest. Then you need to instantiate a copy of the reStructuredText parser and parse the text

use Text::Restructured; $rst_parser = new Text::Restructured(\%opt, $tool_id); $dom = $rst_parser->Parse($text, $source_name);

Finally, you have to call the writer with the parsed document object model

$output = $writer->ProcessDOM($dom);

Direct Responses: 5578 | Write a response

Posted on 2007-06-29 21:07:35-07 by dataweaver in response to 5575

Re: Documentation for direct use of modules

Thank you.

When I call Text::Restructured::Parse, it asks for two arguments: $text and $filename. What roles do each of these play in the behavior of the function? Do I feed the text to be parsed into $text, or do I put a path to a file to be parsed in $filename? If the former, what do I put in $filename? If the latter, what do I put in $text?

I am unfamiliar with how one would go about converting a set of command-line options into a hash for use in Text::Restructured::Writer::new or Text::Restructured::new. Could you provide some advice or an example?

Direct Responses: 5580 | Write a response

Posted on 2007-06-29 21:39:11-07 by rsthacker in response to 5578

Re: Documentation for direct use of modules

The $text argument contains the text to be parsed. The $filename argument should probably be renamed to something like $source, since it is only used to carry around the source information for generating error messages. Since the original use from prest involved only sources that were read from a file, it was called $filename. In general, it would be better for the Parse routine to allow you to pass in a line number too, so the real argument list should be

Parse($some_text, "my data file", 166)

to help people determine how to find where any parsing errors originated.

The command line options hash is just what Getopt::Long::GetOptions would return with the argument qw(d+ e:s h w=s D:s% W:s% V). In other words, if you were to invoke

prest -D include-path='<.>':/my/path -D perl-path=/my/path:'<inc>' -D image-exts=.fig=.png,.dot=. +png,.ai=.png -D trusted -w latex my_file.rst

you would define

%opt = (D => {'include-path' => "include-path='<.>':/my/path", 'perl-path' => "perl-path=/my/path:'<inc>'", 'image-exts' => 'image-exts=.fig=.png,.dot=.png,.ai=.png', trusted => 1 }, w => 'latex');

Direct Responses: Write a response