ACandy

KO | EN

gitlite — search

#react #ai #machine-learning #rust #deep-learning #java #awesome #vue #awesome-list #security #pytorch #ios #mcp #open-source

(★ 13)

A sugary Lua module to write HTML

ACandy Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ACandy: a sugary Lua module for building HTML

<div align="center">
<p>🌏 <strong>English</strong> | <a href="docs/README.zh.md">中文</a></p>

<p>
This work uses <a href="https://semver.org/">Semantic Versioning</a>
</p>
</div>

ACandy is a pure Lua module for building HTML. Taking advantage of Lua’s syntactic sugar and metatable, it provides an intuitive DSL to build HTML from Lua.

ACandy 是一个构建 HTML 的纯 Lua 模块。利用 Lua 的语法糖和元表，ACandy 提供了一个易用的 DSL 来从 Lua 构建 HTML。

> [!NOTE]
>
> This module even has a specialized version for [Scribunto](https://www.mediawiki.org/wiki/Extension:Scribunto) (i.e., the Lua module environment used by MediaWiki’s “Module” namespace). See the branch “[scribunto](https://github.com/AmeroHan/ACandy/tree/scribunto)” for details.
>
> 本模块还有 [Scribunto](https://www.mediawiki.org/wiki/Extension:Scribunto)（即 MediaWiki “Module（模块）”命名空间的 Lua 模块所用环境）的特化版本，详见分支“[scribunto](https://github.com/AmeroHan/ACandy/tree/scribunto)”。

## Quick look

```lua
local acandy = require 'acandy'
local a, some, Fragment = acandy.a, acandy.some, acandy.Fragment

local example = Fragment {
   a.h1['#top heading heading-1'] 'Hello!',
   a.div { class="container", style="margin: 0 auto;",
      a.p {
         'My name is ', a.dfn('ACandy'), ', a module for building HTML.',
         a.br,
         'Thank you for your visit.',
      },
      a.p 'visitors:',
      a.ul / some.li('Alice', 'Bob', 'Carol', '...'),
   },
}
print(example)
```

Output (formatted):

```html
<h1 id="top" class="heading heading-1">Hello!</h1>
<div style="margin: 0 auto;" class="container">
   <p>
      My name is <dfn>ACandy</dfn>, a module for building HTML.<br>
      Thank you for your visit.
   </p>
   <p>visitors:</p>
   <ul>
      <li>Alice</li>
      <li>Bob</li>
      <li>Carol</li>
      <li>...</li>
   </ul>
</div>
```

In this documentation, strings related to attributes are enclosed in double quotation marks while others single. It's just my personal preference and you can decide for yourself.

## Getting started

### Install

ACandy is [available](https://luarocks.org/modules/amero/html) on [LuaRocks](https://luarocks.org) and can be installed with the following command:

```shell
luarocks install html
```

Or you can clone this repository and copy the [acandy](/acandy) folder to your Lua module path manually.

### Import

```lua
local acandy = require('acandy')
local a = acandy.a
```

`a` is the entry point for all elements, because:

- `a` is ACandy’s first letter;
- `a` is short to type;
- <code>a.*xxx*</code> can be understood as “a *xxx*” in English.

## Create elements

```lua
local elem = a.p {
   class="my-paragraph", style="color: #114514;",
   'This sentence is inside a ', a.code('<p>'), ' element.',
}
print(elem)
```

In this code, `a.p` is a function that returns an element. It takes a table as its argument, in which key-value pairs and sequences represent attributes and children of the element respectively, and the same applies to other elements. If there is only one child and no attributes need to be set, the child can be passed directly as the argument of the function, so `a.code('...')` is equivalent to `a.code({ '...' })`.

The output of this code, formatted (the same below), is as follows.

```html
<p class="my-paragraph" style="color: #114514;">
   This sentence is inside a <code>&lt;p&gt;</code> element.
</p>
```

> [!TIP]
>
> - You don’t need to handle HTML escaping in strings. If you don't want automatic escaping, you can put the content in [`acandy.Raw`](#acandyraw).
> - Child nodes do not have to be elements or strings—although only these two types are shown here, any value that can be `tostring` is capable of a child node.

<code>a.*xxx*</code> is [ASCII case-insensitive](https://infra.spec.whatwg.org/#ascii-case-insensitive), thus `a.div`, `a.Div`, `a.DIV`, etc., are the same value (i.e., `rawequal(a.div, a.Div) == true` and `rawequal(a.div, a.DIV) == true`) and will all become `<div></div>`.

### Attributes

Attributes are provided to elements through key-value pairs in the table. The attribute values can be:

- `nil` and `false` indicate no such attribute;
- `true` indicates a boolean attribute, e.g., `a.script { async=true }` means `<script async></script>`;
- for any other value, try `tostring` on it, then escape `&`, `<`, `>` and NBSP.

### Children

Child nodes are provided to elements through the sequence part of the table. Any value other than `nil` can be a child node. When serializing, they follow the following rules.

#### Default case

Elements, strings, numbers, booleans, and all other values not mentioned later are applicable to the following rules.

When serializing, `tostring` will be tried on these values and then escape `&`, `<`, `>` and NBSP. If you don't want automatic escaping, you can put the content in [`acandy.Raw`](#acandyraw).

In the following example, we use three elements (`<p>`) as child nodes of `<article>`, and use strings, numbers, and booleans as elements of `<p>`. It is trivial to guess the result.

```lua
local elem = a.article {
   a.p 'Lorem ipsum...',  -- or `a.p { 'Lorem ipsum...' }`
   a.p(2),  -- or `a.p { 2 }`
   a.p(true),  -- or `a.p { true }`
}
print(elem)
```

```html
<article>
   <p>Lorem ipsum...</p>
   <p>2</p>
   <p>true</p>
</article>
```

#### Lists

When serializing, if a node is [list-like](#list-like-values), ACandy will recursively serialize the child nodes inside it.

By the way, tables returned by [`acandy.Fragment`](#acandyfragment) (e.g., `Fragment { 1, 2, 3 }`) are list-like, as their metatable has the `'__acandy_list_like'` field set to `true`.

Particularly, if a node has a table type but not considered list-like (e.g., table returned by `a.p { 1, 2, 3 }`), it will be directly converted to string according to the [default rule](#default-case), so make sure `__tostring` metamethod is implemented.

```lua
local list1 = { '3', '4' }
local list2 = { '2', list1 }
local elem = a.div { '1', list2 }
print(elem)
```

```html
<p>1234</p>
```

#### Functions

Functions can be used as child nodes, which is equivalent to calling the function and using the return value as a child node, with the only difference being that the function will be deferred until `tostring` is called.

```lua
local elem = a.ul {
   a.li 'item 1',
   a.li {
      function ()  -- returns string
         return 'item 2'
      end,
   },
   function ()  -- returns element
      return a.li 'item 3'
   end,
   function ()  -- returns list
      local list = {}
      for i = 4, 6 do
         list[#list+1] = a.li('item '..i)
      end
      return list
   end,
}
print(elem)
```

```html
<ul>
   <li>item 1</li>
   <li>item 2</li>
   <li>item 3</li>
   <li>item 4</li>
   <li>item 5</li>
   <li>item 6</li>
</ul>
```

> [!TIP]
>
> Child nodes are processed recursively, so you can return functions within functions.

### Bracket syntax (setting element attributes)

Placing a string in brackets can quickly set `id` and `class`.

```lua
local elem = a.div['#my-id my-class-1 my-class-2'] {
   a.p 'You know what it is.',
}
print(elem)
```

Placing a [table-like value](#table-like-values) in brackets can set element attributes, not limited to `id` and `class`. This makes reusing attributes more convenient.

```lua
local attr = {
   id="my-id",
   class="my-class-1 my-class-2",
}
local elem = a.div[attr] {
   a.p 'You know what it is.',
}
print(elem)
```

Both of the above code snippets output:

```html
<div id="my-id" class="my-class-1 my-class-2">
   <p>You know what it is.</p>
</div>
```

### Slash syntax (breadcrumbs)

```lua
elem1 / elem2 / ... / elemN / tail_value
```

is equivalent to:

```lua
elem1(
   elem2(
      ...(
         elemN(tail_value)
      )
   )
)
```

Kind of like CSS’s [child combinator](https://developer.mozilla.org/docs/Web/CSS/Child_combinator) `>`, except that it is used to compose elements rather than select elements.

The premise is that `elem1`..`elemN` are not [void elements](https://developer.mozilla.org/docs/Glossary/Void_element) or [constructed elements](#element-instance-properties).

Example:

```lua
local link_item = a.li / a.a
local text = 'More coming soon...'
local elem = (
   a.header['site-header'] / a.nav / a.ul {
      link_item { href="/home", 'Home' },
      link_item { href="/posts", 'Posts' },
      link_item { href="/about", 'About' },
      a.li / text,
   }
)
print(elem)
```

```html
<header class="site-header">
   <nav>
      <ul>
         <li><a href="/home">Home</a></li>
         <li><a href="/posts">Posts</a></li>
         <li><a href="/about">About</a></li>
         <li>More coming soon...</li>
      </ul>
   </nav>
</header>
```

> [!TIP]
>
> breadcrumbs can be cached, just like `link_item` in the above example.

### `acandy.some`

```lua
local frag1 = some.xxx(arg1, arg2, ...)
local frag2 = some.xxx[attr](arg1, arg2, ...)
```

is equivalent to:

```lua
local frag1 = Fragment {
   a.xxx(arg1),
   a.xxx(arg2),
   ...,
}
local frag2 = Fragment {
   a.xxx[attr](arg1),
   a.xxx[attr](arg2),
   ...,
}
```

Example:

```lua
local some = acandy.some
local items = a.ul {
   some.li['my-li']('item 1', 'item 2'),
   some.li('item 3', 'item 4'),
}
print(items)
```

```html
<ul>
   <li class="my-li">item 1</li>
   <li class="my-li">item 2</li>
   <li>item 3</li>
   <li>item 4</li>
</ul>
```

## Element instance

If an element is obtained by calling functions like `a.div(...)`, `a.div[...](...)`, it is called (tentatively) a "**constructed element**"; when a constructed element is the end of a breadcrumb, the breadcrumb also returns a constructed element; while `a.div`, `a.div[...]` are not constructed elements.

A constructed element `elem` has the following properties:

- `elem.tag_name`: the tag name of the element, reassignable.
- `elem.attributes`: a table that stores all the attributes of the element, changes to this table will take effect on the element itself; cannot be reassigned.
- `elem.children`: a [`Fragment`](#acandyfragment) that stores all the child nodes of the element, changes to this table will take effect on the element itself; cannot be reassigned.
- <code>elem.*some_attribute*</code> (<code>*some_attribute*</code> is a string): equivalent to <code>elem.attributes.*some_attribute*</code>.
- <code>elem[*n*]</code> (<code>*n*</code> is an integer): equivalent to <code>elem.children[*n*]</code>.

Example:

```lua
local elem = a.ol { id="my-id",
   a.li 'item 1',
}

-- get
elem.tag_name  --> 'ol'

elem.children[1]  --> a.li 'item 1'
elem[1] == elem.children[1]  --> true

elem.attributes.id  --> 'my-id'
elem.id == elem.attributes.id  --> true

-- set
elem.tag_name = 'ul'

elem.children:insert(a.li 'item 2')
elem[3] = a.li 'item 3'

elem.attributes.id = 'new-id'
elem.style = 'color: blue;'

print(elem)
```

```html
<ul id="new-id" style="color: blue;">
   <li>item 1</li>
   <li>item 2</li>
   <li>item 3</li>
</ul>
```

## Node constructors

### `acandy.Fragment`

`Fragment` holds multiple elements. The only differences between `Fragment` and a regular table are:

- It has `__tostring` set, so you can get the HTML string;
- It has `__index` set, so you can call all methods in the `table` library which take a table as the first parameter (e.g., `table.insert`, `table.remove`) in an object-oriented manner.

You can create an empty Fragment with `Fragment()` or `Fragment({})`.

When there is only one element, `Fragment(<child>)` is equivalent to `Fragment({ <child> })`.

Example:

```lua
local Fragment = acandy.Fragment
local frag = Fragment {
   a.p 'First paragraph.',
   a.p 'Second paragraph.',
}
frag:insert(a.p('Third paragraph.'))
print(frag)
```

```html
<p>First paragraph.</p>
<p>Second paragraph.</p>
<p>Third paragraph.</p>
```

### `acandy.Raw`

`Raw` prevents strings from being escaped in the final output. It accepts any type of value, calls `tostring`, and stores it internally.

- It has `__tostring` set, so you can get the corresponding string with `tostring`;
- It has `__concat` set, so you can concatenate two objects obtained by `Raw` with `..`.

Example:

```lua
local Raw = acandy.Raw
local elem = a.ul {
   a.li 'foo <br> bar',
   a.li(Raw 'foo <br> bar'),
   a.li(Raw('foo <b')..Raw('r> bar')),
   a.li { Raw('foo <b'), Raw('r> bar') },
}
```

```html
<ul>
   <li>foo &lt;br&gt; bar</li>
   <li>foo <br> bar</li>
   <li>foo <br> bar</li>
   <li>foo <br> bar</li>
</ul>
```

### `acandy.Comment`

`Comment` creates a comment node.

```lua
local elem = a.p {
   'Hello, ',
   acandy.Comment 'This is a comment.',
   'world!',
   acandy.Comment(),
}
print(elem)
```

```html
<p>Hello, world!</p>
```

### `acandy.Doctype`

Currently only the HTML5 doctype is supported. It is accessed by `Doctype.HTML`.

```lua
tostring(acandy.Doctype.HTML)  --> '<!DOCTYPE html>'
```

## Environmental methods

### `acandy.extend_env`

```lua
function acandy.extend_env(env: table): ()
```

Extend the environment in place with `acandy.a` as `__index`, e.g., `_ENV`. This makes it possible to directly use the tag name rather than tediously type `a.`, unless there is a naming conflict with local variables or global variables.

> [!WARNING]
>
> It is not recommended to use this method on the global environment, as it may cause hard-to-detect naming conflicts.

```lua
local acandy = require 'acandy'
local a = acandy.a
acandy.extend_env(_ENV)

print(
   -- normally you can access an element without `a.`
   div {
      -- use `a.table` to avoid the naming conflict with Lua's `table` module (a global value)
      a.table {
         tr { td 'foo' },
      },
      -- or use a different case
      TABLE {
         tr { td 'bar' },
      }
      ul {
         -- use `a.a` to avoid the naming conflict with `a` from `acandy` (a local value)
         li / a.a { href="/home", 'Home' },
         -- or use a different case
         li / A { href="/about", 'About' },
      }
   }
)
```

```html
<div>
   <table>
      <tr><td>foo</td></tr>
   </table>
   <table>
      <tr><td>bar</td></tr>
   </table>
   <ul>
      <li><a href="/home">Home</a></li>
      <li><a href="/about">About</a></li>
   </ul>
</div>
```

### `acandy.to_extended_env`

```lua
function acandy.to_extended_env(env: table): table
```

Similar to `acandy.extend_env`, but returns a new table instead of modifying the original table.

```lua
-- on Lua 5.2+
local function get_article()
   local _ENV = acandy.to_extended_env(_ENV)
   return (
      article {
         header / h2 'Title',
         main {
            p 'Paragraph 1',
            p 'Paragraph 2',
         }
      }
   )
end
-- on Lua 5.1
local get_article = setfenv(function ()
   return (
      article {
         header / h2 'Title',
         main {
            p 'Paragraph 1',
            p 'Paragraph 2',
         }
      }
   )
end, acandy.to_extended_env(_G))

print(get_article())
```

```html
<article>
   <header>
      <h2>Title</h2>
   </header>
   <main>
      <p>Paragraph 1</p>
      <p>Paragraph 2</p>
   </main>
</article>
```

## Configuration

ACandy defaults to HTML mode (currently only HTML mode, XML will be supported in the future), and has predefined some HTML void elements and raw text elements (see [config.lua](/config.lua)).

ACandy does not support modifying global configuration. To modify the configuration, create a new configured `ACandy` instance. The function signature is as follows.

```lua
type Config = {
   void_elements: { [string]: true },
   raw_text_elements: { [string]: true },
}
function acandy.ACandy(output_type: 'html', modify_config?: (config: Config) -> ()): table
```

The `output_type` parameter currently only accepts `'html'`. The `modify_config` parameter (optional) is a function that takes a table as a parameter and has no return value. The table passed to this function is the basis of the new configuration, and you can modify this value in the function, for example:

```lua
local acandy = require('acandy').ACandy('html', function (config)
   -- add a void element
   config.void_elements['my-void-element'] = true
   -- remove `br` from void elements
   config.void_elements.br = nil
   -- add a raw text element
   config.raw_text_elements['my-raw-text-element'] = true
   -- remove `script` from raw text elements
   config.raw_text_elements.script = nil
end)
local a = acandy.a
print(
   acandy.Fragment {
      a['my-void-element'],
      a.br,
      a['my-raw-text-element'] '< > &',
      a.script 'let val = 2 > 1',
   }
)
```

```html
<my-void-element>
<br></br>
<my-raw-text-element>< > &</my-raw-text-element>
<script>let val = 2 &gt; 1</script>
```

To use this configuration throughout the project, you can export the configured `ACandy` instance and import it in other files.

```lua
-- my_acandy.lua
return require('acandy').ACandy('html', function (config)
   -- ...
end)

-- other files
local acandy = require('my_acandy')
```

## Concepts

### Table-like values

Table-like values are values that can be read as tables. A value `t` is considered a table-like value if and only if it satisfies the following conditions:

- Any of the following:

- `t` is a table and has no metatable.
  - The `'__acandy_table_like'` field of `t`’s metatable is `true` (can be set by `getmetatable(t).__acandy_table_like = true`). The user needs to ensure that `t` can:

- read content through `t[k]`;
    - get the sequence length through `#t`;
    - traverse keys and values through `pairs(t)` and `ipairs(t)`.

ACandy only checks the metatable’s `'__acandy_table_like'` field and does not check whether `t` meets the above conditions.

### List-like values

List-like values are values that can be read as sequences. A value `t` is considered a list-like value if and only if it satisfies the following conditions:

- Any of the following:

- `t` is a [table-like value](#table-like-values).
  - The `'__acandy_list_like'` field of `t`’s metatable is `true` (can be set by `getmetatable(t).__acandy_list_like = true`). The user needs to ensure that `t` can:

- read content through `t[k]`;
    - get the sequence length through `#t`;
    - traverse values through `ipairs(t)`.

ACandy only checks the metatable’s `'__acandy_list_like'` field and does not check whether `t` meets the above conditions.

## Contribute

Contributions of any form are welcomed, including bug reports, feature suggestions, documentation improvement, code optimization and so on!

ACandy

ACandy Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ACandy

ACandy Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README