NAME

HTML::Lazy - Declarative HTML generation

SYNOPSIS

use HTML::Lazy (:ALL);

my $document = html-en
    head( Map,
        title(Map, text('HTML::Lazy'))
    ),
    body( Map,
        p({ :class<example> },
            text('Hello world!')
        )
    );

# Execute the generator and show the new HTML
put render($document)

And the result:

output

Hello world!

DESCRIPTION

HTML::Lazy is a declarative HTML document generation module. It provides declarative functions for creating lazy HTML generation closures. The lazy generation can be overridden through an eager renderer and generation can be performed in parrallel with a hyper-renderer.

Tags and adding your own

For a list of html tags which can be exported, see the export list below. If you need one I've missed, you can generate your own tag function like this:

my &head = tag-factory 'head';

You now have a routine for generating head tags.

Prior Art

This is certainly not the first Perl 6 HTML generator and will hardly be the lasst. A number of other modules provide differnt solutions which you should consider:

• XHTML::Writer

• Typesafe::XHTML::Writer

• HTML::Tag

AUTHOR

Sam Gillespie samgwise@gmail.com

COPYRIGHT AND LICENSE

Copyright 2019 Sam Gillespie.

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.

Export groups

Subroutines

sub render

sub render(
    &tag
) returns Str

Calls a no argument Callable to produce the defined content. This routine is here to show programmer intention and catch any errors encountered when building the HTML Str. All errors are returned in the form of a failure so it is important to check the truthiness of the result to determine if the HTML was generated succesfully.

sub pre-render

sub pre-render(
    &tag
) returns Callable

Executes a render and stores the result so it may be rendered later. Use this function to eagerly evaluate a document or sub document and store the resulting Str for use in other documents. Please note that any errors encountered during a pre-render will not be encountered until the result of the pre-rendered output is used, since the Failure object will be caputred in the result.

sub hyper-render

sub hyper-render(
    *@children
) returns Callable

Children of a hyper-render function will be rendered in parrallel when called. The results will be reassembled without change to order.

sub text

sub text(
    Str $text
) returns Callable

Create a closure to emit the text provided. Text is escaped for HTML, use text-raw for including text which should not be sanitised. The escaping uses escape-html from HTML::Escape (https://modules.perl6.org/dist/HTML::Escape:cpan:MOZNION).

sub text-raw

sub text-raw(
    Str $text
) returns Callable

Create a closure to emit the text provided. The text is returned with no escaping. This function is appropriate for inserting HTML from other sources, scripts or CSS. If you are looking to add text content to a page you should look at the text function as it will sanitize the input, so as to avoid any accidental or malicious inclusion of HTML or script content.

sub node

sub node(
    Str:D $tag,
    Associative $attributes,
    *@children
) returns Callable

Generalised html element generator. This function provides the core rules for generating html tags. All tag generators are built upon this function. To create specialised versions of this function use the tag-factory and then further specialised with the C function.

sub tag-factory

sub tag-factory(
    Str:D $tag
) returns Callable

Make functions to create specific tags. Returns a Callable with the signiture (Associative $attributes, *@children --> Callable). The closure created by this routine wraps up an instance of the node routine.

sub with-attributes

sub with-attributes(
    &tag,
    Associative $attributes
) returns Callable

Create a tag with preset attributes. Allows for further specialisation of tag closures from the C routine. The closure returned from this routine has the following signiture (*@children --> Callable).

sub html-en

sub html-en(
    Associative :$attributes = { ... },
    *@children
) returns Callable

Create a HTML tag with DOCTYPE defenition. Use this function as the top of your document. The default arguments to attributes are set for English, {:lang<en>, :dir<ltr>}, but a new Map or hash can be used to tailor this routine to your needs.

sub include-file

sub include-file(
    Str:D $file
) returns Callable

Include content from a file. Use this function to include external files such as scripts and CSS in your templates. Content is included without any sanitisation of the input.