diff --git a/README.pod b/README.pod new file mode 100644 index 0000000..cfad722 --- /dev/null +++ b/README.pod @@ -0,0 +1,271 @@ +=pod + +=head1 NAME + +Text::Haml - Haml Perl implementation + +=head1 SYNOPSIS + + use Text::Haml; + + my $haml = Text::Haml->new; + + my $html = $haml->render('%p foo'); #

foo

+ + $html = $haml->render('= $user', user => 'friend'); #
friend
+ + # Use Haml file + $html = $haml->render_file('tmpl/index.haml', user => 'friend'); + +=head1 DESCRIPTION + +L implements Haml +L specification. + +L passes specification tests written by Norman Clarke +http://github.com/norman/haml-spec and supports only cross-language Haml +features. Do not expect Ruby specific things to work. + +=head1 ATTRIBUTES + +L implements the following attributes: + +=head2 C + +Holds the string of code that is appended to the generated Perl code. + +=head2 C + +Holds the Perl code. + +=head2 C + +Holds compiled code. + +=head2 C + + $haml->encoding('utf-8'); + +Default is utf-8. + +=head2 C + +Escape subroutine presented as string. + +Default is + + $haml->escape(<<'EOF'); + my $s = shift; + $s =~ s/&/&/g; + $s =~ s//>/g; + $s =~ s/"/"/g; + $s =~ s/'/'/g; + return $s; + EOF + +=head2 C + + $haml->escape_html(0); + +Switch on/off Haml output html escaping. Default is on. + +=head2 C + +Holds filters. + +=head2 C + + $haml->format('xhtml'); + +Supported formats: xhtml, html, html5. + +Default is xhtml. + +=head2 C + +Holds the namespace under which the Perl package is generated. + +=head2 C + +Holds the string of code that is prepended to the generated Perl code. + +=head2 C + +Holds the variables that are passed during the rendering. + +=head2 C + +When options is B (by default) passed variables are normal Perl +variables and are used with C<$> prefix. + + $haml->render('%p $var', var => 'hello'); + +When this option is B passed variables are Perl lvalue +subroutines and are used without C<$> prefix. + + $haml->render('%p var', var => 'hello'); + +But if you declare Perl variable in a block, it must be used with C<$> +prefix. + + $haml->render('< + + helpers => { + foo => sub { + my $self = shift; + my $string = shift; + + $string =~ s/r/z/; + + return $string; + } + } + +Holds helpers subroutines. Helpers can be called in Haml text as normal Perl +functions. See also add_helper. + +=head2 C + + $haml->helpers_args($my_context); + +First argument passed to the helper (L instance by default). + +=head2 C + + $haml->error; + +Holds the last error. + +=head2 C + +Holds parsed haml elements. + +=head2 C + +Holds path of Haml templates. Current directory is a default. +If you want to set several paths, arrayref can also be set up. +This way is the same as L. + +=head2 C + +Holds cache level of Haml templates. 1 is a default. +0 means "Not cached", 1 means "Checked template mtime" and 2 means "Used always cached". +This way is the same as L. + +=head2 C + +Holds cache directory of Haml templates. $ENV{HOME}/.text_haml_cache is a default. +Unless $ENV{HOME}, File::Spec->tempdir was used. +This way is the same as L. + +=head1 METHODS + +=head2 C + + my $haml = Text::Haml->new; + +=head2 C + + $haml->add_helper(current_time => sub { time }); + +Adds a new helper. + +=head2 C + + $haml->add_filter(compress => sub { $_[0] =~ s/\s+/ /g; $_[0]}); + +Adds a new filter. + +=head2 C + + $haml->build(@_); + +Builds the Perl code. + +=head2 C + + $haml->compile; + +Compiles parsed code. + +=head2 C + + $haml->interpret(@_); + +Interprets compiled code. + +=head2 C + + $haml->parse('%p foo'); + +Parses Haml string building a tree. + +=head2 C + + my $text = $haml->render('%p foo'); + + my $text = $haml->render('%p var', var => 'hello'); + +Renders Haml string. Returns undef on error. See error attribute. + +=head2 C + + my $text = $haml->render_file('foo.haml', var => 'hello'); + +A helper method that loads a file and passes it to the render method. +Since "%____vars" is used internally, you cannot use this as parameter name. + +=head1 PERL SPECIFIC IMPLEMENTATION ISSUES + +=head2 String interpolation + +Despite of existing string interpolation in Perl, Ruby interpolation is also +supported. + +$haml->render('%p Hello #{user}', user => 'foo') + +=head2 Hash keys + +When declaring tag attributes C<:> symbol can be used. + +$haml->render("%a{:href => 'bar'}"); + +Perl-style is supported but not recommented, since your Haml template won't +work with Ruby Haml implementation parser. + +$haml->render("%a{href => 'bar'}"); + +=head1 DEVELOPMENT + +=head2 Repository + + http://github.com/vti/text-haml + +=head1 AUTHOR + +Viacheslav Tykhanovskyi, C. + +=head1 CREDITS + +In alphabetical order: + +Nick Ragouzis + +Norman Clarke + +Wanradt Koell + +=head1 COPYRIGHT AND LICENSE + +Copyright (C) 2009-2012, Viacheslav Tykhanovskyi. + +This program is free software, you can redistribute it and/or modify it under +the terms of the Artistic License version 2.0. + +=cut diff --git a/lib/Text/Haml.pm b/lib/Text/Haml.pm index d1e514a..12c88cd 100644 --- a/lib/Text/Haml.pm +++ b/lib/Text/Haml.pm @@ -11,7 +11,7 @@ use File::Spec; use File::Basename (); use URI::Escape (); -our $VERSION = '0.990107'; +our $VERSION = '0.990108'; use constant CHUNK_SIZE => 4096; @@ -1426,9 +1426,11 @@ Nick Ragouzis Norman Clarke +Wanradt Koell + =head1 COPYRIGHT AND LICENSE -Copyright (C) 2009-2011, Viacheslav Tykhanovskyi. +Copyright (C) 2009-2012, Viacheslav Tykhanovskyi. This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.