HTML::Lazy

[![Build Status](https://travis-ci.org/samgwise/html-lazy.svg?branch=master)](https://travis-ci.org/samgwise/html-lazy) NAME ==== HTML::Lazy - Declarative HTML generation SYNOPSIS ======== ```perl6 use HTML::Lazy (:ALL); my $document = html-en head( Map, title(Map, text('HTML::Lazy')) ), body( Map, p({ :class }, text('Hello world!') ) ); # Execute the generator and show the new HTML put render($document) ``` And the result: output ====== HTML::Lazy

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: ```perl6 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](https://github.com/gfldex/perl6-xhtml-writer) * [Typesafe::XHTML::Writer](https://github.com/gfldex/perl6-typesafe-xhtml-writer) * [HTML::Tag](https://github.com/adaptiveoptics/HTML-Tag) AUTHOR ====== Sam Gillespie 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 =============

Symbol	Export groups
&render	:DEFAULT, :ALL
&pre-render	:DEFAULT, :ALL
&hyper-render	:DEFAULT, :ALL
&text	:DEFAULT, :ALL
&text-raw	:DEFAULT, :ALL
&node	:DEFAULT, :ALL
&tag-factory	:DEFAULT, :ALL
&with-attributes	:DEFAULT, :ALL
&html-en	:DEFAULT, :ALL
&include-file	:DEFAULT, :ALL
&head	:tags, :ALL
&title	:tags, :ALL
&meta	:tags, :ALL
&body	:tags, :ALL
&div	:tags, :ALL
&footer	:tags, :ALL
&header	:tags, :ALL
&br	:tags, :ALL
&col	:tags, :ALL
&colgroup	:tags, :ALL
&ul	:tags, :ALL
&ol	:tags, :ALL
&li	:tags, :ALL
&code	:tags, :ALL
&samp	:tags, :ALL
&pre	:tags, :ALL
&table	:tags, :ALL
&thead	:tags, :ALL
&tbody	:tags, :ALL
&tfoot	:tags, :ALL
&tr	:tags, :ALL
&th	:tags, :ALL
&td	:tags, :ALL
&caption	:tags, :ALL
&figure	:tags, :ALL
&figurecaption	:tags, :ALL
&a	:tags, :ALL
&img	:tags, :ALL
&audio	:tags, :ALL
&video	:tags, :ALL
&canvas	:tags, :ALL
&link	:tags, :ALL
&script	:tags, :ALL
&style	:tags, :ALL
&asource	:tags, :ALL
&svg	:tags, :ALL
&noscript	:tags, :ALL
&iframe	:tags, :ALL
&template	:tags, :ALL
&form	:tags, :ALL
&input	:tags, :ALL
&label	:tags, :ALL
&optgroup	:tags, :ALL
&option	:tags, :ALL
&select	:tags, :ALL
&textarea	:tags, :ALL
&button	:tags, :ALL
&span	:tags, :ALL
&p	:tags, :ALL
&i	:tags, :ALL
&b	:tags, :ALL
&q	:tags, :ALL
&blockquote	:tags, :ALL
&em	:tags, :ALL
&sub	:tags, :ALL
&sup	:tags, :ALL
&h1	:tags, :ALL
&h2	:tags, :ALL
&h3	:tags, :ALL
&h4	:tags, :ALL
&h5	:tags, :ALL
&h6	:tags, :ALL

Subroutines =========== ### sub render ```perl6 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 ```perl6 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 ```perl6 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 ```perl6 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 ```perl6 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 ```perl6 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 ```perl6 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 ```perl6 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 ```perl6 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, :dir}`, but a new Map or hash can be used to tailor this routine to your needs. ### sub include-file ```perl6 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.