==============================
stpl(1) Version 1.13.6 \| stpl
==============================
.. To test man page:
..
.. pandoc README.rst -s -t man | /usr/bin/man -l -
..
.. The generate:
..
.. pandoc README.rst -s -t man -o man/stpl.1
NAME
====
**stpl** — simple template - Bottle SimpleTemplate in a separate command line tool.
SYNOPSIS
========
**stpl** <file>\|<string>\|- [<directory>\|-] [<python variable>]* [-I <include folder>]*
DESCRIPTION
===========
**stpl** is a little command line tool, that
- takes a `bottle <https://bottlepy.org/docs/dev/stpl.html>`__
SimpleTemplate file with extension **.stpl** and
- expands the template
- to **stdout** or
- to a directory, thereby dropping the **.stpl**
Parameters:
1) file or string or -
2) optional: directory or -
3) optionally several: python code defining variables. Enclose with ''.
4) optionally several: -I <include folder>
To install for user only, do::
pip install --user stpl
Usage from Python:
.. code:: python
>>> from stpl import SimpleTemplate
>>> tpl = SimpleTemplate('Hello {{name}}!')
>>> tpl.render(name='World')
u'Hello World!'
or
.. code:: python
>>> from bottle import template
>>> template('Hello {{name}}!', name='World')
u'Hello World!'
or
.. code:: python
>>> from bottle import template
>>> my_dict={'number': '123', 'street': 'Fake St.', 'city': 'Fakeville'}
>>> template('I live at {{number}} {{street}}, {{city}}', **my_dict)
u'I live at 123 Fake St., Fakeville'
SIMPLETEMPLATE
==============
Inline Expressions
------------------
``{{...}}``: any python expression is allowed within the curly brackets as long as it evaluates to a string or something that has a string representation:
.. code:: python
>>> template('Hello {{name}}!', name='World')
u'Hello World!'
>>> template('Hello {{name.title() if name else "stranger"}}!', name=None)
u'Hello stranger!'
>>> template('Hello {{name.title() if name else "stranger"}}!', name='mArC')
u'Hello Marc!'
You can start the expression with an exclamation mark to disable escaping::
.. code:: python
>>> template('Hello {{name}}!', name='<b>World</b>')
u'Hello <b>World</b>!'
>>> template('Hello {{!name}}!', name='<b>World</b>')
u'Hello <b>World</b>!'
Embedded python code
--------------------
Code lines start with ``%`` and code blocks are surrounded by ``<%`` and ``%>`` tokens::
% name = "Bob" # a line of python code
<p>Some plain text in between</p>
<%
# A block of python code
name = name.title().strip()
%>
<p>More plain text</p>
Embedded python code follows regular python syntax, but with two additional syntax rules:
* **Indentation is ignored.**
You can put as much whitespace in front of statements as you want.
This allows you to align your code with the surrounding markup and can greatly improve readability.
* Blocks that are normally indented have to be closed explicitly with an ``end`` keyword.
::
<ul>
% for item in basket:
<li>{{item}}</li>
% end
</ul>
Both the ``%`` and the ``<%`` tokens are only recognized if they are the first non-whitespace characters in a line.
You don't have to escape them if they appear mid-text in your template markup.
Only if a line of text starts with one of these tokens, you have to escape it with a backslash.
In the rare case where the backslash + token combination appears in your markup at the beginning of a line,
you can always help yourself with a string literal in an inline expression::
This line contains % and <% but no python code.
\% This text-line starts with the '%' token.
\<% Another line that starts with a token but is rendered as text.
{{'\\%'}} this line starts with an escaped token.
Whitespace Control
------------------
Code blocks and code lines always span the whole line.
Whitespace in front of after a code segment is stripped away.
You won't see empty lines or dangling whitespace in your template because of embedded code::
<div>
% if True:
<span>content</span>
% end
</div>
This snippet renders to clean and compact html::
<div>
<span>content</span>
</div>
But embedding code still requires you to start a new line, which may not what you want to see in your rendered template.
To skip the newline in front of a code segment, end the text line with a double-backslash::
<div>\\
%if True:
<span>content</span>\\
%end
</div>
This time the rendered template looks like this::
<div><span>content</span></div>
This only works directly in front of code segments.
In all other places you can control the whitespace yourself and don't need any special syntax.
Template Functions
==================
Each template is preloaded with a bunch of functions that help with the most common use cases.
These functions are always available.
You don't have to import or provide them yourself.
For everything not covered here there are probably good python libraries available.
Remember that you can ``import`` anything you want within your templates.
They are python programs after all.
*include(sub_template, \*\*variables)*
Render a sub-template with the specified variables and insert the resulting text into the current template.
The function returns a dictionary containing the local variables passed to or defined within the sub-template::
% include('header.tpl', title='Page Title')
Page Content
% include('footer.tpl')
*rebase(name, \*\*variables)*
Mark the current template to be later included into a different template.
After the current template is rendered, its resulting text is stored in a variable named ``base`` and passed to the base-template, which is then rendered.
This can be used to ``wrap`` a template with surrounding text, or simulate the inheritance feature found in other template engines::
% rebase('base.tpl', title='Page Title')
<p>Page Content ...</p>
This can be combined with the following ``base.tpl``::
<html>
<head>
<title>{{title or 'No title'}}</title>
</head>
<body>
{{!base}}
</body>
</html>
Accessing undefined variables in a template raises ``NameError`` and stops rendering immediately.
This is standard python behavior and nothing new,
but vanilla python lacks an easy way to check the availability of a variable.
This quickly gets annoying if you want to support flexible inputs or use the
same template in different situations. These functions may help:
*env*
Parent environment.
*defined(name)*
Return True if the variable is defined in the current template namespace, False otherwise.
*get(name, default=None)*
Return the variable, or a default value.
*setdefault(name, default)*
If the variable is not defined, create it with the given default value.
Return the variable.
Here is an example that uses all three functions to implement optional template variables in different ways::
% setdefault('text', 'No Text')
<h1>{{get('title', 'No Title')}}</h1>
<p> {{ text }} </p>
% if defined('author'):
<p>By {{ author }}</p>
% end
EXAMPLES
========
Example file:
NAME="{{!full_name}}"
EMAIL="{{!default_email}}"
REPO="{{!repo}}"
To stdout::
stpl file.txt.stpl - 'full_name="Roland Puntaier"' 'default_email="roland.puntaier@gmail.com"' 'repo="https://github.com/rpuntaie/stpl"'
To file.txt::
stpl file.txt.stpl . 'full_name="Roland Puntaier"' 'default_email="roland.puntaier\@gmail.com"' 'repo="https://github.com/rpuntaie/stpl"'
Raw data
{
"_id": null,
"home_page": "https://github.com/rpuntaie/stpl",
"name": "stpl",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Duplicate, File",
"author": "Roland Puntaier",
"author_email": "roland.puntaier@gmail.com",
"download_url": "",
"platform": "",
"description": "==============================\nstpl(1) Version 1.13.6 \\| stpl\n==============================\n\n.. To test man page:\n..\n.. pandoc README.rst -s -t man | /usr/bin/man -l -\n..\n.. The generate:\n..\n.. pandoc README.rst -s -t man -o man/stpl.1\n\nNAME\n====\n\n**stpl** \u2014 simple template - Bottle SimpleTemplate in a separate command line tool.\n\nSYNOPSIS\n========\n\n**stpl** <file>\\|<string>\\|- [<directory>\\|-] [<python variable>]* [-I <include folder>]*\n\nDESCRIPTION\n===========\n\n**stpl** is a little command line tool, that\n\n- takes a `bottle <https://bottlepy.org/docs/dev/stpl.html>`__\n SimpleTemplate file with extension **.stpl** and\n- expands the template\n\n - to **stdout** or\n - to a directory, thereby dropping the **.stpl**\n\nParameters:\n\n1) file or string or -\n2) optional: directory or -\n3) optionally several: python code defining variables. Enclose with ''.\n4) optionally several: -I <include folder>\n\nTo install for user only, do::\n\n pip install --user stpl\n\nUsage from Python:\n\n.. code:: python\n\n >>> from stpl import SimpleTemplate\n >>> tpl = SimpleTemplate('Hello {{name}}!')\n >>> tpl.render(name='World')\n u'Hello World!'\n\nor\n\n.. code:: python\n\n >>> from bottle import template\n >>> template('Hello {{name}}!', name='World')\n u'Hello World!'\n\nor\n\n.. code:: python\n\n >>> from bottle import template\n >>> my_dict={'number': '123', 'street': 'Fake St.', 'city': 'Fakeville'}\n >>> template('I live at {{number}} {{street}}, {{city}}', **my_dict)\n u'I live at 123 Fake St., Fakeville'\n\n\nSIMPLETEMPLATE\n==============\n\nInline Expressions\n------------------\n\n``{{...}}``: any python expression is allowed within the curly brackets as long as it evaluates to a string or something that has a string representation:\n\n.. code:: python\n\n >>> template('Hello {{name}}!', name='World')\n u'Hello World!'\n >>> template('Hello {{name.title() if name else \"stranger\"}}!', name=None)\n u'Hello stranger!'\n >>> template('Hello {{name.title() if name else \"stranger\"}}!', name='mArC')\n u'Hello Marc!'\n\nYou can start the expression with an exclamation mark to disable escaping::\n\n.. code:: python\n\n >>> template('Hello {{name}}!', name='<b>World</b>')\n u'Hello <b>World</b>!'\n >>> template('Hello {{!name}}!', name='<b>World</b>')\n u'Hello <b>World</b>!'\n\nEmbedded python code\n--------------------\n\nCode lines start with ``%`` and code blocks are surrounded by ``<%`` and ``%>`` tokens::\n\n % name = \"Bob\" # a line of python code\n <p>Some plain text in between</p>\n <%\n # A block of python code\n name = name.title().strip()\n %>\n <p>More plain text</p>\n\nEmbedded python code follows regular python syntax, but with two additional syntax rules:\n\n* **Indentation is ignored.**\n You can put as much whitespace in front of statements as you want.\n This allows you to align your code with the surrounding markup and can greatly improve readability.\n\n* Blocks that are normally indented have to be closed explicitly with an ``end`` keyword.\n\n::\n\n <ul>\n % for item in basket:\n <li>{{item}}</li>\n % end\n </ul>\n\nBoth the ``%`` and the ``<%`` tokens are only recognized if they are the first non-whitespace characters in a line.\nYou don't have to escape them if they appear mid-text in your template markup.\nOnly if a line of text starts with one of these tokens, you have to escape it with a backslash.\nIn the rare case where the backslash + token combination appears in your markup at the beginning of a line,\nyou can always help yourself with a string literal in an inline expression::\n\n This line contains % and <% but no python code.\n \\% This text-line starts with the '%' token.\n \\<% Another line that starts with a token but is rendered as text.\n {{'\\\\%'}} this line starts with an escaped token.\n\nWhitespace Control\n------------------\n\nCode blocks and code lines always span the whole line.\nWhitespace in front of after a code segment is stripped away.\nYou won't see empty lines or dangling whitespace in your template because of embedded code::\n\n <div>\n % if True:\n <span>content</span>\n % end\n </div>\n\nThis snippet renders to clean and compact html::\n\n <div>\n <span>content</span>\n </div>\n\nBut embedding code still requires you to start a new line, which may not what you want to see in your rendered template.\nTo skip the newline in front of a code segment, end the text line with a double-backslash::\n\n <div>\\\\\n %if True:\n <span>content</span>\\\\\n %end\n </div>\n\nThis time the rendered template looks like this::\n\n <div><span>content</span></div>\n\nThis only works directly in front of code segments.\nIn all other places you can control the whitespace yourself and don't need any special syntax.\n\nTemplate Functions\n==================\n\nEach template is preloaded with a bunch of functions that help with the most common use cases.\nThese functions are always available.\nYou don't have to import or provide them yourself.\nFor everything not covered here there are probably good python libraries available.\nRemember that you can ``import`` anything you want within your templates.\nThey are python programs after all.\n\n\n*include(sub_template, \\*\\*variables)*\n\n\n Render a sub-template with the specified variables and insert the resulting text into the current template.\n The function returns a dictionary containing the local variables passed to or defined within the sub-template::\n\n % include('header.tpl', title='Page Title')\n Page Content\n % include('footer.tpl')\n\n\n*rebase(name, \\*\\*variables)*\n\n Mark the current template to be later included into a different template.\n After the current template is rendered, its resulting text is stored in a variable named ``base`` and passed to the base-template, which is then rendered.\n This can be used to ``wrap`` a template with surrounding text, or simulate the inheritance feature found in other template engines::\n\n % rebase('base.tpl', title='Page Title')\n <p>Page Content ...</p>\n\n This can be combined with the following ``base.tpl``::\n\n <html>\n <head>\n <title>{{title or 'No title'}}</title>\n </head>\n <body>\n {{!base}}\n </body>\n </html>\n\n\nAccessing undefined variables in a template raises ``NameError`` and stops rendering immediately.\nThis is standard python behavior and nothing new,\nbut vanilla python lacks an easy way to check the availability of a variable.\nThis quickly gets annoying if you want to support flexible inputs or use the\nsame template in different situations. These functions may help:\n\n*env*\n\n Parent environment.\n\n*defined(name)*\n\n Return True if the variable is defined in the current template namespace, False otherwise.\n\n\n*get(name, default=None)*\n\n Return the variable, or a default value.\n\n\n*setdefault(name, default)*\n\n If the variable is not defined, create it with the given default value.\n Return the variable.\n\n Here is an example that uses all three functions to implement optional template variables in different ways::\n\n % setdefault('text', 'No Text')\n <h1>{{get('title', 'No Title')}}</h1>\n <p> {{ text }} </p>\n % if defined('author'):\n <p>By {{ author }}</p>\n % end\n\n\nEXAMPLES\n========\n\nExample file:\n\n NAME=\"{{!full_name}}\"\n EMAIL=\"{{!default_email}}\"\n REPO=\"{{!repo}}\"\n\nTo stdout::\n\n stpl file.txt.stpl - 'full_name=\"Roland Puntaier\"' 'default_email=\"roland.puntaier@gmail.com\"' 'repo=\"https://github.com/rpuntaie/stpl\"'\n\nTo file.txt::\n\n stpl file.txt.stpl . 'full_name=\"Roland Puntaier\"' 'default_email=\"roland.puntaier\\@gmail.com\"' 'repo=\"https://github.com/rpuntaie/stpl\"'\n\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "stpl - expand bottle SimpleTemplate",
"version": "1.13.6",
"project_urls": {
"Homepage": "https://github.com/rpuntaie/stpl"
},
"split_keywords": [
"duplicate",
" file"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f4a01054e1cc09e6d84c104156a795352a8db3f7c4172f3b0696dbdb62b0cfbb",
"md5": "1d3f3ffb62e5afb098d9e8e4f5d67f45",
"sha256": "ef1c0d7fa3ab7bbeaccb595d958b60711ed7c6f25dd2d3ac60ba88691ef2884b"
},
"downloads": -1,
"filename": "stpl-1.13.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1d3f3ffb62e5afb098d9e8e4f5d67f45",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 15950,
"upload_time": "2020-12-31T12:20:51",
"upload_time_iso_8601": "2020-12-31T12:20:51.973885Z",
"url": "https://files.pythonhosted.org/packages/f4/a0/1054e1cc09e6d84c104156a795352a8db3f7c4172f3b0696dbdb62b0cfbb/stpl-1.13.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-12-31 12:20:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rpuntaie",
"github_project": "stpl",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "stpl"
}
JSON
