NAME

Shebangml - markup with bacon

SYNOPSIS

This is an experimental markup language + parser|interpreter with support for plugins and cleanly configurable add-on features. I use it as a personal home page tool and lots of other things.

See Shebangml::Syntax for details.

Methods

configure

  $hbml->configure(%options);

add_handler

Adds a handler for a namespace.

  $hbml->add_handler($name);

The $name will have Shebangml::Handler:: prepended to it, and should already be loaded at this point. It is good practice to declare a version (e.g. our $VERSION = v0.1.1) in your handler package -- and may be required in the future.

If a new method is available, a new object will be constructed and stored as the handler. Otherwise, the handler will be treated as a class name. Tags in the handlers namespace are constructed as:

  .yourclass.themethod[foo=bar]

or

  .yourclass.themethod[foo=bar]{{{content literal}}}

These would cause the processing to invoke one of the following (the latter if you have defined new()) and send the result to $hbml->output().

  Shebangml::Handler::yourclass->themethod($atts, $content);

  $yourobject->themethod($atts, $content);

add_hook

  $hbml->add_hook($name => sub {...});

process

Processes a given input $source. This method holds its own state and can be repeatedly called with new inputs (each of which must be a well-formed shebangml document) using the same $hbml object.

Arguments are passed to "new" in Shebangml::State.

  $hbml->process($source);

put_tag

Handles contentless tags and any tags constructed with the {{{ ... }}} literal quoting mechanism.

  $hbml->put_tag($tag, $atts, $string);

put_tag_start

  $hbml->put_tag_start($tag, $atts);

put_tag_end

  $hbml->put_tag_end($tag);

put_text

  $hbml->put_text($text);

run_tag

This method is called for any whole, starting, or ending tags which start with a dot ('.'). The builtin or plugin handler for the given tag must exist and must have a prototype which corresponds to the way it is used.

  $hbml->run_tag($tag, @and_stuff);

Yes, your method should have a prototype.

escape_text

  my $out = $hbml->escape_text($text);

put_literal

  $hbml->put_literal($string);

output

  $hbml->output(@strings);

Builtins

do_include

  $hbml->do_include($atts);

do_doctype

  $hbml->do_doctype($atts);

atts

Parses one or more lines of attribute strings into pairs and returns an atts object.

  my $atts = $self->atts(@atts);

Experimental

Some parts which might not survive revision:

current_file

This is set during process() and becomes accessible for callbacks as a class accessor.

AUTHOR

Eric Wilhelm @ <ewilhelm at cpan dot org>

http://scratchcomputing.com/

BUGS

If you found this module on CPAN, please report any bugs or feature requests through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

If you pulled this development version from my /svn/, please contact me directly.

COPYRIGHT

Copyright (C) 2008 Eric L. Wilhelm, All Rights Reserved.

NO WARRANTY

Absolutely, positively NO WARRANTY, neither express or implied, is offered with this software. You use this software at your own risk. In case of loss, no person or entity owes you anything whatsoever. You have been warned.

LICENSE

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

cpanm Shebangml

perl -MCPAN -e shell
install Shebangml