Patchwork [1,of,2] templater: add brief doc about internal data types

login
register
mail settings
Submitter Yuya Nishihara
Date March 19, 2018, 1:46 p.m.
Message ID <cb8ab2dddf79e4ff203e.1521467175@mimosa>
Download mbox | patch
Permalink /patch/29621/
State Accepted
Headers show

Comments

Yuya Nishihara - March 19, 2018, 1:46 p.m.
# HG changeset patch
# User Yuya Nishihara <yuya@tcha.org>
# Date 1521464102 -32400
#      Mon Mar 19 21:55:02 2018 +0900
# Node ID cb8ab2dddf79e4ff203e22b4130ceca5b88bb14b
# Parent  cc058f8ed3d6ea8ee9d9a49263ea133c5adff587
templater: add brief doc about internal data types

Hopefully this will help reviewing upcoming my series. Start small.
Pulkit Goyal - March 20, 2018, 6:41 a.m.
On Mon, Mar 19, 2018 at 7:16 PM, Yuya Nishihara <yuya@tcha.org> wrote:
> # HG changeset patch
> # User Yuya Nishihara <yuya@tcha.org>
> # Date 1521464102 -32400
> #      Mon Mar 19 21:55:02 2018 +0900
> # Node ID cb8ab2dddf79e4ff203e22b4130ceca5b88bb14b
> # Parent  cc058f8ed3d6ea8ee9d9a49263ea133c5adff587
> templater: add brief doc about internal data types
>
> Hopefully this will help reviewing upcoming my series. Start small.

Queued this series. Many thanks, especially for adding doc.

Patch

diff --git a/mercurial/templater.py b/mercurial/templater.py
--- a/mercurial/templater.py
+++ b/mercurial/templater.py
@@ -5,6 +5,47 @@ 
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2 or any later version.
 
+"""Slightly complicated template engine for commands and hgweb
+
+This module provides low-level interface to the template engine. See the
+formatter and cmdutil modules if you are looking for high-level functions
+such as ``cmdutil.rendertemplate(ctx, tmpl)``.
+
+Internal Data Types
+-------------------
+
+Template keywords and functions take a dictionary of current symbols and
+resources (a "mapping") and return result. Inputs and outputs must be one
+of the following data types:
+
+bytes
+    a byte string, which is generally a human-readable text in local encoding.
+
+generator
+    a lazily-evaluated byte string, which is a possibly nested generator of
+    values of any printable types, and  will be folded by ``stringify()``
+    or ``flatten()``.
+
+    BUG: hgweb overloads this type for mappings (i.e. some hgweb keywords
+    returns a generator of dicts.)
+
+None
+    sometimes represents an empty value, which can be stringified to ''.
+
+True, False, int, float
+    can be stringified as such.
+
+date tuple
+    a (unixtime, offset) tuple, which produces no meaningful output by itself.
+
+hybrid
+    represents a list/dict of printable values, which can also be converted
+    to mappings by % operator.
+
+mappable
+    represents a scalar printable value, also supports % operator.
+"""
+
 from __future__ import absolute_import, print_function
 
 import os