{
    "content": [
        {
            "type": "text",
            "text": "# Template::Manual::Syntax (perldoc)\n\n## NAME\n\nTemplate::Manual::Syntax - Directive syntax, structure and semantics\n\n## Sections\n\n- **NAME**\n- **Tag Styles**\n- **Outline Tags**\n- **Comments**\n- **Chomping Whitespace**\n- **Implicit Directives: GET and SET**\n- **Block Directives**\n- **Capturing Block Output**\n- **Chaining Filters**\n- **Multiple Directive Blocks**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Template::Manual::Syntax",
        "section": "",
        "mode": "perldoc",
        "summary": "Template::Manual::Syntax - Directive syntax, structure and semantics",
        "synopsis": null,
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "Tag Styles",
                "lines": 37,
                "subsections": []
            },
            {
                "name": "Outline Tags",
                "lines": 62,
                "subsections": []
            },
            {
                "name": "Comments",
                "lines": 14,
                "subsections": []
            },
            {
                "name": "Chomping Whitespace",
                "lines": 7,
                "subsections": []
            },
            {
                "name": "Implicit Directives: GET and SET",
                "lines": 31,
                "subsections": []
            },
            {
                "name": "Block Directives",
                "lines": 47,
                "subsections": []
            },
            {
                "name": "Capturing Block Output",
                "lines": 42,
                "subsections": []
            },
            {
                "name": "Chaining Filters",
                "lines": 9,
                "subsections": []
            },
            {
                "name": "Multiple Directive Blocks",
                "lines": 18,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Template::Manual::Syntax - Directive syntax, structure and semantics\n",
                "subsections": []
            },
            "Tag Styles": {
                "content": "Template directives are embedded between start and end markers tags. By default these tag\nmarkers are \"[%\" and \"%]\".\n\n[% PROCESS header %]\n\n<h1>Hello World!</h1>\n<a href=\"[% page.next %]\"><img src=\"[% icon.next %].gif\"></a>\n\n[% PROCESS footer %]\n\nYou can change the tag characters using the \"STARTTAG\", \"ENDTAG\" and \"TAGSTYLE\" configuration\noptions. You can also use the \"TAGS\" directive to define a new tag style for the current\ntemplate file.\n\nYou can also set the \"INTERPOLATE\" option to allow simple variable references to be embedded\ndirectly in templates, prefixed by a \"$\".\n\n# INTERPOLATE = 0\n<td>[% name %]</td>\n<td>[% email %]</td>\n\n# INTERPOLATE = 1\n<td>$name</td>\n<td>$email</td>\n\nDirectives may be embedded anywhere in a line of text and can be split across several lines.\nInsignificant whitespace is generally ignored within the directive.\n\n[% INCLUDE header\ntitle = 'Hello World'\nbgcol = '#ffffff'\n%]\n\n[%INCLUDE menu align='right'%]\n\nName: [% name %]  ([%id%])\n",
                "subsections": []
            },
            "Outline Tags": {
                "content": "As of version 2.26, the Template Toolkit supports \"outline\" tags. These have a designated marker\nat the start of a line (\"%%\" by default) and continue to the end of a line. The newline\ncharacter at the end of the line is discarded (aka \"chomped\").\n\nSo rather than writing something like this:\n\n[% IF some.list.size -%]\n<ul>\n[%   FOREACH item IN some.list -%]\n<li>[% item.html %]</li>\n[%   END -%]\n</ul>\n[% END -%]\n\nYou can write it like this instead:\n\n%% IF some.list.size\n<ul>\n%%   FOREACH item IN some.list\n<li>[% item.html %]</li>\n%%   END\n</ul>\n%% END\n\nOutline tags aren't enabled by default. There are a numbers of ways you can enable them. The\nfirst is to use the \"TAGS\" directive to set the tag style to \"outline\" in any templates where\nyou want to use them. This will enable outline tags from that point on.\n\n[% TAGS outline -%]\n%% INCLUDE header\n\nYou can set the \"TAGS\" back to the \"default\" value at some point later in the template if you\nwant to disable them:\n\n[% TAGS default -%]\n\nYou can set the \"TAGSTYLE\" configuration option if you want then enabled in all templates by\ndefault. You can always use the \"[% TAGS default %]\" directive to disable them in any templates\nor parts of templates if necessary.\n\nmy $tt = Template->new({\nTAGSTYLE => 'outline',\n});\n\nThe \"OUTLINETAG\" option allows you to set the outline tag marker to something else if you're\nnot a fan of percent signs. Setting this option will automatically enable outline tags.\n\nmy $tt = Template->new({\nOUTLINETAG => '>>',\n});\n\nYou can also use the \"TAGS\" directive to define your own custom tags (start, end and now\noptionally, outline) for a template or part of a template.\n\n[% TAGS <* *> >> %]\n>> INCLUDE header       # outline tag\nHello <* name *>        # inline tag\n\nIf you only specify a start and end tag then outline tags will be disabled.\n\n[% TAGS <* *> %]        # no outline tags\n",
                "subsections": []
            },
            "Comments": {
                "content": "The \"#\" character is used to indicate comments within a directive. When placed immediately\ninside the opening directive tag, it causes the entire directive to be ignored.\n\n[%# this entire directive is ignored no\nmatter how many lines it wraps onto\n%]\n\nIn any other position, it causes the remainder of the current line to be treated as a comment.\n\n[% # this is a comment\ntheta = 20      # so is this\nrho   = 30      # <aol>me too!</aol>\n%]\n",
                "subsections": []
            },
            "Chomping Whitespace": {
                "content": "You can add \"-\" or \"+\" to the immediate start or end of a directive tag to control the\nwhitespace chomping options. See the \"PRECHOMP\" and \"POSTCHOMP\" options for further details.\n\n[% BLOCK foo -%]    # remove trailing newline\nThis is block foo\n[%- END %]          # remove leading newline\n",
                "subsections": []
            },
            "Implicit Directives: GET and SET": {
                "content": "The simplest directives are \"GET\" and \"SET\" which retrieve and update variable values\nrespectively. The \"GET\" and \"SET\" keywords are actually optional as the parser is smart enough\nto see them for what they really are (but note the caveat below on using side-effect notation).\nThus, you'll generally see:\n\n[% SET foo = 10 %]\n[% GET foo %]\n\nwritten as:\n\n[% foo = 10 %]\n[% foo %]\n\nYou can also express simple logical statements as implicit \"GET\" directives:\n\n[% title or template.title or 'Default Title' %]\n\n[% mode == 'graphics' ? \"Graphics Mode Enabled\" : \"Text Mode\" %]\n\nAll other directives should start with a keyword specified in UPPER CASE (but see the \"ANYCASE\"\noption). All directives keywords are in UPPER CASE to make them visually distinctive and to\ndistinguish them from variables of the same name but different case. It is perfectly valid, for\nexample, to define a variable called \"stop\" which is entirely separate from the \"STOP\"\ndirective.\n\n[% stop = 'Clackett Lane Bus Depot' %]\n\nThe bus will next stop at [% stop %]    # variable\n\n[% STOP %]                              # directive\n",
                "subsections": []
            },
            "Block Directives": {
                "content": "Directives such as \"FOREACH\", \"WHILE\", \"BLOCK\", \"FILTER\", etc., mark the start of a block which\nmay contain text or other directives up to the matching \"END\" directive. Blocks may be nested\nindefinitely. The \"IF\", \"UNLESS\", \"ELSIF\" and \"ELSE\" directives also define blocks and may be\ngrouped together in the usual manner.\n\n[% FOREACH item = [ 'foo' 'bar' 'baz' ] %]\n* Item: [% item %]\n[% END %]\n\n[% BLOCK footer %]\nCopyright 2000 [% me %]\n[% INCLUDE company/logo %]\n[% END %]\n\n[% IF foo %]\n[% FOREACH thing = foo.things %]\n[% thing %]\n[% END %]\n[% ELSIF bar %]\n[% INCLUDE barinfo %]\n[% ELSE %]\ndo nothing...\n[% END %]\n\nBlock directives can also be used in a convenient side-effect notation.\n\n[% INCLUDE userinfo FOREACH user = userlist %]\n\n[% INCLUDE debugtxt msg=\"file: $error.info\"\nIF debugging %]\n\n[% \"Danger Will Robinson\" IF atrisk %]\n\nversus:\n\n[% FOREACH user = userlist %]\n[% INCLUDE userinfo %]\n[% END %]\n\n[% IF debugging %]\n[% INCLUDE debugtxt msg=\"file: $error.info\" %]\n[% END %]\n\n[% IF atrisk %]\nDanger Will Robinson\n[% END %]\n",
                "subsections": []
            },
            "Capturing Block Output": {
                "content": "The output of a directive can be captured by simply assigning the directive to a variable.\n\n[% headtext = PROCESS header title=\"Hello World\" %]\n\n[% people = PROCESS userinfo FOREACH user = userlist %]\n\nThis can be used in conjunction with the \"BLOCK\" directive for defining large blocks of text or\nother content.\n\n[% poem = BLOCK %]\nThe boy stood on the burning deck,\nHis fleece was white as snow.\nA rolling stone gathers no moss,\nAnd Keith is sure to follow.\n[% END %]\n\nNote one important caveat of using this syntax in conjunction with side-effect notation. The\nfollowing directive does not behave as might be expected:\n\n[% var = 'value' IF somecondition %]   # does not work\n\nIn this case, the directive is interpreted as (spacing added for clarity)\n\n[% var = IF somecondition %]\nvalue\n[% END %]\n\nrather than\n\n[% IF somecondition %]\n[% var = 'value' %]\n[% END %]\n\nThe variable is assigned the output of the \"IF\" block which returns 'value' if true, but nothing\nif false. In other words, the following directive will always cause 'var' to be cleared.\n\n[% var = 'value' IF 0 %]\n\nTo achieve the expected behaviour, the directive should be written as:\n\n[% SET var = 'value' IF somecondition %]\n",
                "subsections": []
            },
            "Chaining Filters": {
                "content": "Multiple \"FILTER\" directives can be chained together in sequence. They are called in the order\ndefined, piping the output of one into the input of the next.\n\n[% PROCESS somefile FILTER truncate(100) FILTER html %]\n\nThe pipe character, \"|\", can also be used as an alias for \"FILTER\".\n\n[% PROCESS somefile | truncate(100) | html %]\n",
                "subsections": []
            },
            "Multiple Directive Blocks": {
                "content": "Multiple directives can be included within a single tag when delimited by semi-colons. Note\nhowever that the \"TAGS\" directive must always be specified in a tag by itself.\n\n[% IF title;\nINCLUDE header;\nELSE;\nINCLUDE other/header  title=\"Some Other Title\";\nEND\n%]\n\nversus\n\n[% IF title %]\n[% INCLUDE header %]\n[% ELSE %]\n[% INCLUDE other/header  title=\"Some Other Title\" %]\n[% END %]\n",
                "subsections": []
            }
        }
    }
}