eknkc/amber/doc.go

/*
Package amber is an elegant templating engine for Go Programming Language.
It is inspired from HAML and Jade.

Tags

A tag is simply a word:

    html

is converted to

    <html></html>

It is possible to add ID and CLASS attributes to tags:

    div#main
    span.time

are converted to

    <div id="main"></div>
    <span class="time"></span>

Any arbitrary attribute name / value pair can be added this way:

    a[href="http://www.google.com"]

You can mix multiple attributes together

    a#someid[href="/"][title="Main Page"].main.link Click Link

gets converted to

    <a id="someid" class="main link" href="/" title="Main Page">Click Link</a>

It is also possible to define these attributes within the block of a tag

    a
        #someid
        [href="/"]
        [title="Main Page"]
        .main
        .link
        | Click Link

Doctypes

To add a doctype, use `!!!` or `doctype` keywords:

    !!! transitional
    // <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

or use `doctype`

    doctype 5
    // <!DOCTYPE html>

Available options: `5`, `default`, `xml`, `transitional`, `strict`, `frameset`, `1.1`, `basic`, `mobile`

Tag Content

For single line tag text, you can just append the text after tag name:

    p Testing!

would yield

    <p>Testing!</p>

For multi line tag text, or nested tags, use indentation:

    html
        head
            title Page Title
        body
            div#content
                p
                    | This is a long page content
                    | These lines are all part of the parent p

                    a[href="/"] Go To Main Page

Data

Input template data can be reached by key names directly. For example, assuming the template has been
executed with following JSON data:

    {
        "Name": "Ekin",
        "LastName": "Koc",
        "Repositories": [
            "amber",
            "dateformat"
        ],
        "Avatar": "/images/ekin.jpg",
        "Friends": 17
    }

It is possible to interpolate fields using `#{}`

    p Welcome #{Name}!

would print

    <p>Welcome Ekin!</p>

Attributes can have field names as well

    a[title=Name][href="/ekin.koc"]

would print

    <a title="Ekin" href="/ekin.koc"></a>

Expressions

Amber can expand basic expressions. For example, it is possible to concatenate strings with + operator:

    p Welcome #{Name + " " + LastName}

Arithmetic expressions are also supported:

    p You need #{50 - Friends} more friends to reach 50!

Expressions can be used within attributes

    img[alt=Name + " " + LastName][src=Avatar]

Variables

It is possible to define dynamic variables within templates,
all variables must start with a $ character and can be assigned as in the following example:

    div
        $fullname = Name + " " + LastName
        p Welcome #{$fullname}

If you need to access the supplied data itself (i.e. the object containing Name, LastName etc fields.) you can use `$` variable

    p $.Name

Conditions

For conditional blocks, it is possible to use `if <expression>`

    div
        if Friends > 10
            p You have more than 10 friends
        else if Friends > 5
            p You have more than 5 friends
        else
            p You need more friends

Again, it is possible to use arithmetic and boolean operators

    div
        if Name == "Ekin" && LastName == "Koc"
            p Hey! I know you..

There is a special syntax for conditional attributes. Only block attributes can have conditions;

    div
        .hasfriends ? Friends > 0

This would yield a div with `hasfriends` class only if the `Friends > 0` condition holds. It is
perfectly fine to use the same method for other types of attributes:

    div
        #foo ? Name == "Ekin"
        [bar=baz] ? len(Repositories) > 0

Iterations

It is possible to iterate over arrays and maps using `each`:

    each $repo in Repositories
        p #{$repo}

would print

    p amber
    p dateformat

It is also possible to iterate over values and indexes at the same time

    each $i, $repo in Repositories
        p
            .even ? $i % 2 == 0
            .odd ? $i % 2 == 1

Includes

A template can include other templates using `include`:

    a.amber
        p this is template a

    b.amber
        p this is template b

    c.amber
        div
            include a
            include b

gets compiled to

    div
        p this is template a
        p this is template b

Inheritance

A template can inherit other templates. In order to inherit another template, an `extends` keyword should be used.
Parent template can define several named blocks and child template can modify the blocks.

    master.amber
        !!! 5
        html
            head
                block meta
                    meta[name="description"][content="This is a great website"]

                title
                    block title
                        | Default title
            body
                block content

    subpage.amber
        extends master

        block title
            | Some sub page!

        block append meta
            // This will be added after the description meta tag. It is also possible
            // to prepend something to an existing block
            meta[name="keywords"][content="foo bar"]

        block content
            div#main
                p Some content here

License
(The MIT License)

Copyright (c) 2012 Ekin Koc <ekin@eknkc.com>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package amber
Revision:	1.1
Committed:	Mon Sep 30 00:42:06 2024 UTC (6 weeks, 4 days ago) by yakumo_izuru
Branch:	MAIN
CVS Tags:	HEAD
Log Message:	Mirrored from https://git.chaotic.ninja/git/yakumo_izuru/aya
#	Content
1	/*
2	Package amber is an elegant templating engine for Go Programming Language.
3	It is inspired from HAML and Jade.
4
5	Tags
6
7	A tag is simply a word:
8
9	html
10
11	is converted to
12
13	<html></html>
14
15	It is possible to add ID and CLASS attributes to tags:
16
17	div#main
18	span.time
19
20	are converted to
21
22	<div id="main"></div>
23	<span class="time"></span>
24
25	Any arbitrary attribute name / value pair can be added this way:
26
27	a[href="http://www.google.com"]
28
29	You can mix multiple attributes together
30
31	a#someid[href="/"][title="Main Page"].main.link Click Link
32
33	gets converted to
34
35	<a id="someid" class="main link" href="/" title="Main Page">Click Link</a>
36
37	It is also possible to define these attributes within the block of a tag
38
39	a
40	#someid
41	[href="/"]
42	[title="Main Page"]
43	.main
44	.link
45	\| Click Link
46
47	Doctypes
48
49	To add a doctype, use `!!!` or `doctype` keywords:
50
51	!!! transitional
52	// <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
53
54	or use `doctype`
55
56	doctype 5
57	// <!DOCTYPE html>
58
59	Available options: `5`, `default`, `xml`, `transitional`, `strict`, `frameset`, `1.1`, `basic`, `mobile`
60
61	Tag Content
62
63	For single line tag text, you can just append the text after tag name:
64
65	p Testing!
66
67	would yield
68
69	<p>Testing!</p>
70
71	For multi line tag text, or nested tags, use indentation:
72
73	html
74	head
75	title Page Title
76	body
77	div#content
78	p
79	\| This is a long page content
80	\| These lines are all part of the parent p
81
82	a[href="/"] Go To Main Page
83
84	Data
85
86	Input template data can be reached by key names directly. For example, assuming the template has been
87	executed with following JSON data:
88
89	{
90	"Name": "Ekin",
91	"LastName": "Koc",
92	"Repositories": [
93	"amber",
94	"dateformat"
95	],
96	"Avatar": "/images/ekin.jpg",
97	"Friends": 17
98	}
99
100	It is possible to interpolate fields using `#{}`
101
102	p Welcome #{Name}!
103
104	would print
105
106	<p>Welcome Ekin!</p>
107
108	Attributes can have field names as well
109
110	a[title=Name][href="/ekin.koc"]
111
112	would print
113
114	<a title="Ekin" href="/ekin.koc"></a>
115
116	Expressions
117
118	Amber can expand basic expressions. For example, it is possible to concatenate strings with + operator:
119
120	p Welcome #{Name + " " + LastName}
121
122	Arithmetic expressions are also supported:
123
124	p You need #{50 - Friends} more friends to reach 50!
125
126	Expressions can be used within attributes
127
128	img[alt=Name + " " + LastName][src=Avatar]
129
130	Variables
131
132	It is possible to define dynamic variables within templates,
133	all variables must start with a $ character and can be assigned as in the following example:
134
135	div
136	$fullname = Name + " " + LastName
137	p Welcome #{$fullname}
138
139	If you need to access the supplied data itself (i.e. the object containing Name, LastName etc fields.) you can use `$` variable
140
141	p $.Name
142
143	Conditions
144
145	For conditional blocks, it is possible to use `if <expression>`
146
147	div
148	if Friends > 10
149	p You have more than 10 friends
150	else if Friends > 5
151	p You have more than 5 friends
152	else
153	p You need more friends
154
155	Again, it is possible to use arithmetic and boolean operators
156
157	div
158	if Name == "Ekin" && LastName == "Koc"
159	p Hey! I know you..
160
161	There is a special syntax for conditional attributes. Only block attributes can have conditions;
162
163	div
164	.hasfriends ? Friends > 0
165
166	This would yield a div with `hasfriends` class only if the `Friends > 0` condition holds. It is
167	perfectly fine to use the same method for other types of attributes:
168
169	div
170	#foo ? Name == "Ekin"
171	[bar=baz] ? len(Repositories) > 0
172
173	Iterations
174
175	It is possible to iterate over arrays and maps using `each`:
176
177	each $repo in Repositories
178	p #{$repo}
179
180	would print
181
182	p amber
183	p dateformat
184
185	It is also possible to iterate over values and indexes at the same time
186
187	each $i, $repo in Repositories
188	p
189	.even ? $i % 2 == 0
190	.odd ? $i % 2 == 1
191
192	Includes
193
194	A template can include other templates using `include`:
195
196	a.amber
197	p this is template a
198
199	b.amber
200	p this is template b
201
202	c.amber
203	div
204	include a
205	include b
206
207	gets compiled to
208
209	div
210	p this is template a
211	p this is template b
212
213	Inheritance
214
215	A template can inherit other templates. In order to inherit another template, an `extends` keyword should be used.
216	Parent template can define several named blocks and child template can modify the blocks.
217
218	master.amber
219	!!! 5
220	html
221	head
222	block meta
223	meta[name="description"][content="This is a great website"]
224
225	title
226	block title
227	\| Default title
228	body
229	block content
230
231	subpage.amber
232	extends master
233
234	block title
235	\| Some sub page!
236
237	block append meta
238	// This will be added after the description meta tag. It is also possible
239	// to prepend something to an existing block
240	meta[name="keywords"][content="foo bar"]
241
242	block content
243	div#main
244	p Some content here
245
246	License
247	(The MIT License)
248
249	Copyright (c) 2012 Ekin Koc <ekin@eknkc.com>
250
251	Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
252
253	The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
254
255	THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
256	*/
257	package amber