The eco Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The eco Reference Manual

This is the eco Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed Jun 15 04:29:00 2022 GMT+0.

Table of Contents

Next: , Previous: , Up: The eco Reference Manual   [Contents][Index]

1 Introduction

Eco - Fast, flexible, designer-friendly templates.

Build Status

Goals

Usage

A basic template (.eco extension) looks like this:

<% deftemplate index (title &optional posts) () %>
  <!DOCTYPE html>
  <html>
    <head>
      <title><%= title %></title>
    </head>
    <body>
      <% if posts %>
        <h1>Recent Posts</h1>
        <ul id="post-list">
          <% loop for (title . snippet) in posts do %>
            <li><%= title %> - <%= snippet %></li>
          <% end %>
        </ul>
      <% else %>
        <span>No recent posts.</span>
      <% end %>
    </body>
  </html>
<% end %>

To load this template, put this in your system definition file:

(:eco-template "filename")

For interactive or quick tests on the REPL, templates can be loaded using ECO:COMPILE-STRING,

(eco:compile-string "<% deftemplate inline-test () () %>This is a test.<% end %>")

All templates are eventually compiled into Lisp functions. To get their outputs, call the templates like any Lisp function:

(eco-template:index "My Blog" nil)

Eco is designed to be output-agnostic, however, by default it will autoescape HTML for convenience. Specify :ESCAPE-HTML NIL when defining each template to disable this behaviour individually for each template.

<% deftemplate output-js-logger (module) (:escape-html nil) %>
   function logDebug (message) {
       console.log("<%= module %>: " + message);
   }
<% end %>

Tags

There are three types of tags in Eco:

Blocks are used to specify Lisp code "inline" in the template, and tend to contain imperative code, their return values are ignored. Expressions and calls are more functional as they return values to be interpolated into their templates. The function called by the CALL construct may be another templates, or any arbitrary Lisp function.

The if tag is a special case: it supports using an else tag to separate the true and false branches. For example:

<% if posts %>
  <h1>Recent Posts</h1>
  ... loop over posts ...
<% else %>
  No recent posts.
<% end %>

Options

Reference

deftemplate

Syntax:

<% deftemplate name (&rest args) (&rest options) %>
  <body>
<% end %>

Defines a template. The only option that is currently defined is :ESCAPE-HTML (default T)

Examples

if

Syntax:

<% if cond %>
  true branch
<% else %>
  false branch
<% end %>

Implementation

Eco uses esrap to parse templates, which it then compiles down to Common Lisp code.

License

Copyright (c) 2014-2019 Fernando Borretti (fernando@borretti.me)

Licensed under the MIT License.

Next: , Previous: , Up: The eco Reference Manual   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.

Previous: , Up: Systems   [Contents][Index]

2.1 eco

Fast, flexible, designer-friendly templates.

Author

Fernando Borretti

Home Page

https://github.com/eudoxia0/eco

License

MIT

Long Description

# Eco - Fast, flexible, designer-friendly templates.

[![Build Status](https://travis-ci.org/eudoxia0/eco.svg?branch=master)](https://travis-ci.org/eudoxia0/eco)

# Goals

- **Simple:** Eco is essentially just a string concatenator. It introduces no
constructs of its own: Every tag is pure Common Lisp code, plain and simple.
- **Easy to Use:** Proper use of Eco should not require more than a
cursory read of this README from time to time.
- **Designer-friendly:** Lispers have written template engine after template
engine that turns S-expressions into HTML. Which is great, if you’re a
lisper. Eco is meant to be used for more than HTML and also to be usable to
the many designers and programmers who don’t know the language and should not
be expected to learn an obscure template syntax to be able to contribute.
- **Performance:** Eco uses the many performance advantages of Common
Lisp. Templates are not interpreted or run in a VM, but compiled to Common
Lisp, which is then compiled down to efficient machine code. By making each
template a function that takes an (Optionally typed) argument list rather than
passing an environment hash table like most other template engines, one can
leverage the type inference features of modern Common Lisp implementations to
create performant templates.

# Usage

A basic template (‘.eco‘ extension) looks like this:

“‘erb
<% deftemplate index (title &optional posts) () %>
<!DOCTYPE html>
<html>
<head>
<title><%= title %></title>
</head>
<body>
<% if posts %>
<h1>Recent Posts</h1>
<ul id="post-list">
<% loop for (title . snippet) in posts do %>
<li><%= title %> - <%= snippet %></li>
<% end %>
</ul>
<% else %>
<span>No recent posts.</span>
<% end %>
</body>
</html>
<% end %>
“‘

To load this template, put this in your system definition file:

“‘lisp
(:eco-template "filename")
“‘

For interactive or quick tests on the REPL, templates can be loaded
using ECO:COMPILE-STRING,

“‘lisp
(eco:compile-string "<% deftemplate inline-test () () %>This is a test.<% end %>")
“‘

All templates are eventually compiled into Lisp functions. To get
their outputs, call the templates like any Lisp function:

“‘lisp
(eco-template:index "My Blog" nil)
“‘

Eco is designed to be output-agnostic, however, by default it will
autoescape HTML for convenience. Specify :ESCAPE-HTML NIL when
defining each template to disable this behaviour individually for each
template.

“‘erb
<% deftemplate output-js-logger (module) (:escape-html nil) %>
function logDebug (message) {
console.log("<%= module %>: " + message);
}
<% end %>
“‘

# Tags

There are three types of tags in Eco:

- Expressions: ‘<%= <expr> %>‘ becomes ‘<expr>‘.
- Blocks: ‘<% <code> <arg1> <arg2> %><body><% end %>‘ becomes ‘(<code> <arg1> <arg2> <body>)‘.
- Calls: ‘<%- <fun> <arg1> <arg2> %><body><% end %>‘ becomes ‘(<fun> <arg1> <arg2> <body>)‘.

Blocks are used to specify Lisp code "inline" in the template, and
tend to contain imperative code, their return values are ignored.
Expressions and calls are more functional as they return values to be
interpolated into their templates. The function called by the CALL
construct may be another templates, or any arbitrary Lisp function.

The ‘if‘ tag is a special case: it supports using an ‘else‘ tag to separate the true and
false branches. For example:

“‘lisp
<% if posts %>
<h1>Recent Posts</h1>
... loop over posts ...
<% else %>
No recent posts.
<% end %>
“‘

# Options

- ‘*template-package*‘: The package the templates will be defined it. Defaults
to ‘:eco-template‘.

# Reference

## ‘deftemplate‘

**Syntax:**

“‘erb
<% deftemplate name (&rest args) (&rest options) %>
<body>
<% end %>
“‘

Defines a template. The only option that is currently defined is
:ESCAPE-HTML (default T)

# Examples

## ‘if‘

**Syntax:**

“‘erb
<% if cond %>
true branch
<% else %>
false branch
<% end %>
“‘

# Implementation

Eco uses esrap to parse templates, which it then compiles down to Common Lisp
code.

# License

Copyright (c) 2014-2019 Fernando Borretti (fernando@borretti.me)

Licensed under the MIT License.

Version

0.1

Dependencies
  • esrap (system).
  • alexandria (system).
  • split-sequence (system).
  • cl-who (system).
Source

eco.asd.

Child Component

src (module).

Next: , Previous: , Up: The eco Reference Manual   [Contents][Index]

3 Modules

Modules are listed depth-first from the system components tree.

Previous: , Up: Modules   [Contents][Index]

3.1 eco/src

Source

eco.asd.

Parent Component

eco (system).

Child Components

Next: , Previous: , Up: The eco Reference Manual   [Contents][Index]

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

Previous: , Up: Files   [Contents][Index]

4.1 Lisp

Next: , Previous: , Up: Lisp   [Contents][Index]

4.1.1 eco/eco.asd

Source

eco.asd.

Parent Component

eco (system).

ASDF Systems

eco.

Next: , Previous: , Up: Lisp   [Contents][Index]

4.1.2 eco/src/parser.lisp

Source

eco.asd.

Parent Component

src (module).

Packages

eco.parser.

Public Interface
Internals

Next: , Previous: , Up: Lisp   [Contents][Index]

4.1.3 eco/src/compiler.lisp

Dependency

parser.lisp (file).

Source

eco.asd.

Parent Component

src (module).

Packages
Public Interface
Internals

Next: , Previous: , Up: Lisp   [Contents][Index]

4.1.4 eco/src/asdf.lisp

Dependency

compiler.lisp (file).

Source

eco.asd.

Parent Component

src (module).

Previous: , Up: Lisp   [Contents][Index]

4.1.5 eco/src/eco.lisp

Dependency

asdf.lisp (file).

Source

eco.asd.

Parent Component

src (module).

Packages

eco.

Public Interface
Internals

generic-compile (function).

Next: , Previous: , Up: The eco Reference Manual   [Contents][Index]

5 Packages

Packages are listed by definition order.

Next: , Previous: , Up: Packages   [Contents][Index]

5.1 eco.parser

Source

parser.lisp.

Use List
  • common-lisp.
  • esrap.
Used By List

eco.compiler.

Public Interface
Internals

Next: , Previous: , Up: Packages   [Contents][Index]

5.2 eco.compiler

Source

compiler.lisp.

Use List
Public Interface

compile-template (function).

Internals

Next: , Previous: , Up: Packages   [Contents][Index]

5.3 eco

Source

eco.lisp.

Use List

common-lisp.

Public Interface
Internals

generic-compile (function).

Previous: , Up: Packages   [Contents][Index]

5.4 eco-template

Source

compiler.lisp.

Use List

common-lisp.

Used By List

eco.compiler.

Public Interface

Next: , Previous: , Up: The eco Reference Manual   [Contents][Index]

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Public Interface

Next: , Previous: , Up: Public Interface   [Contents][Index]

6.1.1 Macros

Macro: deftemplate (name args (&key escape-html) &rest body)
Package

eco-template.

Source

compiler.lisp.

Next: , Previous: , Up: Public Interface   [Contents][Index]

6.1.2 Ordinary functions

Function: compile-pathname (pathname)
Package

eco.

Source

eco.lisp.

Function: compile-string (string)
Package

eco.

Source

eco.lisp.

Function: compile-template (element &optional package-name)
Package

eco.compiler.

Source

compiler.lisp.

Function: e (string)

Escape a string.

Package

eco-template.

Source

compiler.lisp.

Function: parse-pathname (template-pathname)
Package

eco.parser.

Source

parser.lisp.

Function: parse-template (template-string)
Package

eco.parser.

Source

parser.lisp.

Next: , Previous: , Up: Public Interface   [Contents][Index]

6.1.3 Generic functions

Generic Reader: body (object)
Package

eco.parser.

Methods
Reader Method: body ((<block> <block>))

automatically generated reader method

Source

parser.lisp.

Target Slot

body.

Generic Reader: code (object)
Package

eco.parser.

Methods
Reader Method: code ((<block> <block>))

automatically generated reader method

Source

parser.lisp.

Target Slot

code.

Reader Method: code ((<block-tag> <block-tag>))

automatically generated reader method

Source

parser.lisp.

Target Slot

code.

Reader Method: code ((<expr-tag> <expr-tag>))

automatically generated reader method

Source

parser.lisp.

Target Slot

code.

Previous: , Up: Public Interface   [Contents][Index]

6.1.4 Classes

Class: <block>
Package

eco.parser.

Source

parser.lisp.

Direct subclasses

<call>.

Direct methods
Direct slots
Slot: code
Initargs

:code

Readers

code.

Writers

This slot is read-only.

Slot: body
Initargs

:body

Readers

body.

Writers

This slot is read-only.

Class: <call>
Package

eco.parser.

Source

parser.lisp.

Direct superclasses

<block>.

Direct methods

emit.

Class: <else-tag>
Package

eco.parser.

Source

parser.lisp.

Direct superclasses

<tag>.

Class: <expr-tag>
Package

eco.parser.

Source

parser.lisp.

Direct superclasses

<tag>.

Direct methods
Direct slots
Slot: code
Initargs

:code

Readers

code.

Writers

This slot is read-only.

Previous: , Up: Definitions   [Contents][Index]

6.2 Internals

Next: , Previous: , Up: Internals   [Contents][Index]

6.2.1 Special variables

Special Variable: *template-package*
Package

eco.compiler.

Source

compiler.lisp.

Special Variable: +whitespace+
Package

eco.parser.

Source

parser.lisp.

Next: , Previous: , Up: Internals   [Contents][Index]

6.2.2 Ordinary functions

Function: else-tag-p (element)
Package

eco.compiler.

Source

compiler.lisp.

Function: emit-toplevel (code)
Package

eco.compiler.

Source

compiler.lisp.

Function: generic-compile (ast)
Package

eco.

Source

eco.lisp.

Function: parse-tokens (tokens)
Package

eco.parser.

Source

parser.lisp.

Function: read-template-expressions (string)
Package

eco.compiler.

Source

compiler.lisp.

Function: slurp-file (path)
Package

eco.parser.

Source

parser.lisp.

Function: template-element-p (element)
Package

eco.compiler.

Source

compiler.lisp.

Function: trim-whitespace (str)
Package

eco.parser.

Source

parser.lisp.

Function: whitespacep (char)
Package

eco.parser.

Source

parser.lisp.

Next: , Previous: , Up: Internals   [Contents][Index]

6.2.3 Generic functions

Generic Function: emit (str)
Package

eco.compiler.

Methods
Method: emit ((call <call>))
Source

compiler.lisp.

Method: emit ((block <block>))
Source

compiler.lisp.

Method: emit ((expr <expr-tag>))
Source

compiler.lisp.

Method: emit ((vec vector))
Source

compiler.lisp.

Method: emit ((str string))
Source

compiler.lisp.

Previous: , Up: Internals   [Contents][Index]

6.2.4 Classes

Class: <block-tag>
Package

eco.parser.

Source

parser.lisp.

Direct superclasses

<tag>.

Direct subclasses

<call-tag>.

Direct methods

code.

Direct slots
Slot: code
Initargs

:code

Readers

code.

Writers

This slot is read-only.

Class: <call-tag>
Package

eco.parser.

Source

parser.lisp.

Direct superclasses

<block-tag>.

Class: <end-tag>
Package

eco.parser.

Source

parser.lisp.

Direct superclasses

<tag>.

Class: <tag>
Package

eco.parser.

Source

parser.lisp.

Direct subclasses

Previous: , Up: The eco Reference Manual   [Contents][Index]

Appendix A Indexes

Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   B   C   D   E   F   G   M   P   R   S   T   W  
Index Entry  Section
B
body: Public generic functions
body: Public generic functions
C
code: Public generic functions
code: Public generic functions
code: Public generic functions
code: Public generic functions
compile-pathname: Public ordinary functions
compile-string: Public ordinary functions
compile-template: Public ordinary functions
D
deftemplate: Public macros
E
e: Public ordinary functions
else-tag-p: Private ordinary functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit-toplevel: Private ordinary functions
F
Function, compile-pathname: Public ordinary functions
Function, compile-string: Public ordinary functions
Function, compile-template: Public ordinary functions
Function, e: Public ordinary functions
Function, else-tag-p: Private ordinary functions
Function, emit-toplevel: Private ordinary functions
Function, generic-compile: Private ordinary functions
Function, parse-pathname: Public ordinary functions
Function, parse-template: Public ordinary functions
Function, parse-tokens: Private ordinary functions
Function, read-template-expressions: Private ordinary functions
Function, slurp-file: Private ordinary functions
Function, template-element-p: Private ordinary functions
Function, trim-whitespace: Private ordinary functions
Function, whitespacep: Private ordinary functions
G
Generic Function, body: Public generic functions
Generic Function, code: Public generic functions
Generic Function, emit: Private generic functions
generic-compile: Private ordinary functions
M
Macro, deftemplate: Public macros
Method, body: Public generic functions
Method, code: Public generic functions
Method, code: Public generic functions
Method, code: Public generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
P
parse-pathname: Public ordinary functions
parse-template: Public ordinary functions
parse-tokens: Private ordinary functions
R
read-template-expressions: Private ordinary functions
S
slurp-file: Private ordinary functions
T
template-element-p: Private ordinary functions
trim-whitespace: Private ordinary functions
W
whitespacep: Private ordinary functions
Jump to:   B   C   D   E   F   G   M   P   R   S   T   W  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   <  
A   C   E   F   M   P   S  
Index Entry  Section
<
<block-tag>: Private classes
<block>: Public classes
<call-tag>: Private classes
<call>: Public classes
<else-tag>: Public classes
<end-tag>: Private classes
<expr-tag>: Public classes
<tag>: Private classes
A
asdf.lisp: The eco/src/asdf․lisp file
C
Class, <block-tag>: Private classes
Class, <block>: Public classes
Class, <call-tag>: Private classes
Class, <call>: Public classes
Class, <else-tag>: Public classes
Class, <end-tag>: Private classes
Class, <expr-tag>: Public classes
Class, <tag>: Private classes
compiler.lisp: The eco/src/compiler․lisp file
E
eco: The eco system
eco: The eco package
eco-template: The eco-template package
eco.asd: The eco/eco․asd file
eco.compiler: The eco․compiler package
eco.lisp: The eco/src/eco․lisp file
eco.parser: The eco․parser package
F
File, asdf.lisp: The eco/src/asdf․lisp file
File, compiler.lisp: The eco/src/compiler․lisp file
File, eco.asd: The eco/eco․asd file
File, eco.lisp: The eco/src/eco․lisp file
File, parser.lisp: The eco/src/parser․lisp file
M
Module, src: The eco/src module
P
Package, eco: The eco package
Package, eco-template: The eco-template package
Package, eco.compiler: The eco․compiler package
Package, eco.parser: The eco․parser package
parser.lisp: The eco/src/parser․lisp file
S
src: The eco/src module
System, eco: The eco system
Jump to:   <  
A   C   E   F   M   P   S