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
#	User	Rev	Content
1	yakumo_izuru	1.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