txt: ## dist_cpan-SAMGWISE-HTML-Lazy.md
  [![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
  
  ```
  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](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 [samgwise@gmail.com](mailto: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
  
  | 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
  
  ```
  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.
  