The eco Reference Manual

This is the eco Reference Manual, version 0.1, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:43:59 2018 GMT+0.

1 Introduction

Eco - Fast, flexible, designer-friendly templates.

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:

<% 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 %>
            <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")

To execute the template:

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

Note: Eco is designed to be output-agnostic, so by default it will not autoescape HTML. Use the e function for that. You have been warned.

Options

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

Reference

`deftemplate`

Syntax:

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

Defines a template.

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

Licensed under the MIT License.

2 Systems

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

2.1 `eco`

Author

Fernando Borretti

Home Page

https://github.com/eudoxia0/eco

License

MIT

Description

Fast, flexible, designer-friendly templates.

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 %>
<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")
“‘

To execute the template:

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

**Note:** Eco is designed to be output-agnostic, so by default it will **not**
autoescape HTML. Use the ‘e‘ function for that. You have been warned.

# Tags

- ‘<%= <expr> %>‘ becomes ‘<expr>‘.
- ‘<% <code> %><body><% end %>‘ becomes ‘(<code> <body>)‘.

# 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.

# 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

Licensed under the MIT License.

Version

0.1

Dependencies

esrap
split-sequence
cl-who

Source

eco.asd (file)

Component

src (module)

3 Modules

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

3.1 `eco/src`

Parent

eco (system)

Location

src/

Components

parser.lisp (file)
compiler.lisp (file)
asdf.lisp (file)
eco.lisp (file)

4 Files

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

4.1 Lisp

4.1.1 `eco.asd`

Location: eco.asd
Systems: eco (system)

4.1.2 `eco/src/parser.lisp`

Parent

src (module)

Location

src/parser.lisp

Packages

eco.parser

Exported Definitions

<block> (class)
<else-tag> (class)
<expr-tag> (class)
body (method)
code (method)
code (method)
code (method)
parse-pathname (function)
parse-template (function)

Internal Definitions

+whitespace+ (special variable)
<block-tag> (class)
<end-tag> (class)
<tag> (class)
parse-tokens (function)
slurp-file (function)
trim-whitespace (function)
whitespacep (function)

4.1.3 `eco/src/compiler.lisp`

Dependency

parser.lisp (file)

Parent

src (module)

Location

src/compiler.lisp

Packages

eco-template
eco.compiler

Exported Definitions

compile-template (function)
deftemplate (macro)
e (function)

Internal Definitions

emit (method)
emit (method)
emit (method)
emit (method)
emit (method)
emit-toplevel (function)
read-string-in-package (function)

4.1.4 `eco/src/asdf.lisp`

Dependency: compiler.lisp (file)
Parent: src (module)
Location: src/asdf.lisp

4.1.5 `eco/src/eco.lisp`

Dependency

asdf.lisp (file)

Parent

src (module)

Location

src/eco.lisp

Packages

eco

Exported Definitions

compile-pathname (function)
compile-string (function)

Internal Definitions

generic-compile (function)

5 Packages

Packages are listed by definition order.

5.1 `eco.parser`

Source

parser.lisp (file)

Use List

esrap
common-lisp

Used By List

eco.compiler

Exported Definitions

<block> (class)
<else-tag> (class)
<expr-tag> (class)
body (generic function)
body (method)
code (generic function)
code (method)
code (method)
code (method)
parse-pathname (function)
parse-template (function)

Internal Definitions

+whitespace+ (special variable)
<block-tag> (class)
<end-tag> (class)
<tag> (class)
parse-tokens (function)
slurp-file (function)
trim-whitespace (function)
whitespacep (function)

5.2 `eco-template`

Source

compiler.lisp (file)

Use List

common-lisp

Exported Definitions

deftemplate (macro)
e (function)

5.3 `eco.compiler`

Source

compiler.lisp (file)

Use List

eco.parser
common-lisp

Exported Definitions

compile-template (function)

Internal Definitions

emit (generic function)
emit (method)
emit (method)
emit (method)
emit (method)
emit (method)
emit-toplevel (function)
read-string-in-package (function)

5.4 `eco`

Source

eco.lisp (file)

Use List

common-lisp

Exported Definitions

compile-pathname (function)
compile-string (function)

Internal Definitions

generic-compile (function)

6 Definitions

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

6.1 Exported definitions

6.1.1 Macros

Macro: deftemplate NAME ARGS (&key ESCAPE-HTML) &rest BODY

Package: eco-template
Source: compiler.lisp (file)

6.1.2 Functions

Function: compile-pathname PATHNAME

Package: eco
Source: eco.lisp (file)

Function: compile-string STRING

Package: eco
Source: eco.lisp (file)

Function: compile-template ELEMENT &optional PACKAGE-NAME

Package: eco.compiler
Source: compiler.lisp (file)

Function: e STRING

Escape a string.

Package: eco-template
Source: compiler.lisp (file)

Function: parse-pathname TEMPLATE-PATHNAME

Package: eco.parser
Source: parser.lisp (file)

Function: parse-template TEMPLATE-STRING

Package: eco.parser
Source: parser.lisp (file)

6.1.3 Generic functions

Generic Function: body OBJECT

Package

eco.parser

Methods

Method: body (<BLOCK> <block>)

automatically generated reader method

Source: parser.lisp (file)

Generic Function: code OBJECT

Package

eco.parser

Methods

Method: code (<BLOCK> <block>)

automatically generated reader method

Source: parser.lisp (file)

Method: code (<BLOCK-TAG> <block-tag>)

automatically generated reader method

Source: parser.lisp (file)

Method: code (<EXPR-TAG> <expr-tag>)

automatically generated reader method

Source: parser.lisp (file)

6.1.4 Classes

Class: <block> ()

Package

eco.parser

Source

parser.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

emit (method)
body (method)
code (method)

Direct slots

Slot: code

Initargs: :code
Readers: code (generic function)

Slot: body

Initargs: :body
Readers: body (generic function)

Class: <else-tag> ()

Package: eco.parser
Source: parser.lisp (file)
Direct superclasses: <tag> (class)
Direct methods: emit (method)

Class: <expr-tag> ()

Package

eco.parser

Source

parser.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

emit (method)
code (method)

Direct slots

Slot: code

Initargs: :code
Readers: code (generic function)

6.2 Internal definitions

6.2.1 Special variables

Special Variable: +whitespace+

Package: eco.parser
Source: parser.lisp (file)

6.2.2 Functions

Function: emit-toplevel CODE

Package: eco.compiler
Source: compiler.lisp (file)

Function: generic-compile AST

Package: eco
Source: eco.lisp (file)

Function: parse-tokens TOKENS

Package: eco.parser
Source: parser.lisp (file)

Function: read-string-in-package STRING PACKAGE-NAME

Package: eco.compiler
Source: compiler.lisp (file)

Function: slurp-file PATH

Package: eco.parser
Source: parser.lisp (file)

Function: trim-whitespace STR

Package: eco.parser
Source: parser.lisp (file)

Function: whitespacep CHAR

Package: eco.parser
Source: parser.lisp (file)

6.2.3 Generic functions

Generic Function: emit STR

Package

eco.compiler

Methods

Method: emit (BLOCK <block>)

Source: compiler.lisp (file)

Method: emit (ELSE <else-tag>)

Source: compiler.lisp (file)

Method: emit (EXPR <expr-tag>)

Source: compiler.lisp (file)

Method: emit (VEC vector)

Source: compiler.lisp (file)

Method: emit (STR string)

Source: compiler.lisp (file)

6.2.4 Classes

Class: <block-tag> ()

Package

eco.parser

Source

parser.lisp (file)

Direct superclasses

<tag> (class)

Direct methods

code (method)

Direct slots

Slot: code

Initargs: :code
Readers: code (generic function)

Class: <end-tag> ()

Package: eco.parser
Source: parser.lisp (file)
Direct superclasses: <tag> (class)

Class: <tag> ()

Package

eco.parser

Source

parser.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

<block-tag> (class)
<end-tag> (class)
<else-tag> (class)

Appendix A Indexes

A.1 Concepts

Jump to:	E F L M

	Index Entry	Section

E
	`eco.asd`:	The eco<dot>asd file
	`eco/src`:	The eco/src module
	`eco/src/asdf.lisp`:	The eco/src/asdf<dot>lisp file
	`eco/src/compiler.lisp`:	The eco/src/compiler<dot>lisp file
	`eco/src/eco.lisp`:	The eco/src/eco<dot>lisp file
	`eco/src/parser.lisp`:	The eco/src/parser<dot>lisp file

F
	File, Lisp, `eco.asd`:	The eco<dot>asd file
	File, Lisp, `eco/src/asdf.lisp`:	The eco/src/asdf<dot>lisp file
	File, Lisp, `eco/src/compiler.lisp`:	The eco/src/compiler<dot>lisp file
	File, Lisp, `eco/src/eco.lisp`:	The eco/src/eco<dot>lisp file
	File, Lisp, `eco/src/parser.lisp`:	The eco/src/parser<dot>lisp file

L
	Lisp File, `eco.asd`:	The eco<dot>asd file
	Lisp File, `eco/src/asdf.lisp`:	The eco/src/asdf<dot>lisp file
	Lisp File, `eco/src/compiler.lisp`:	The eco/src/compiler<dot>lisp file
	Lisp File, `eco/src/eco.lisp`:	The eco/src/eco<dot>lisp file
	Lisp File, `eco/src/parser.lisp`:	The eco/src/parser<dot>lisp file

M
	Module, `eco/src`:	The eco/src module

Jump to:	E F L M

A.2 Functions

Jump to:	B C D E F G M P R S T W

	Index Entry	Section

B
	`body`:	Exported generic functions
	`body`:	Exported generic functions

C
	`code`:	Exported generic functions
	`code`:	Exported generic functions
	`code`:	Exported generic functions
	`code`:	Exported generic functions
	`compile-pathname`:	Exported functions
	`compile-string`:	Exported functions
	`compile-template`:	Exported functions

D
	`deftemplate`:	Exported macros

E
	`e`:	Exported functions
	`emit`:	Internal generic functions
	`emit`:	Internal generic functions
	`emit`:	Internal generic functions
	`emit`:	Internal generic functions
	`emit`:	Internal generic functions
	`emit`:	Internal generic functions
	`emit-toplevel`:	Internal functions

F
	`Function, compile-pathname`:	Exported functions
	`Function, compile-string`:	Exported functions
	`Function, compile-template`:	Exported functions
	`Function, e`:	Exported functions
	`Function, emit-toplevel`:	Internal functions
	`Function, generic-compile`:	Internal functions
	`Function, parse-pathname`:	Exported functions
	`Function, parse-template`:	Exported functions
	`Function, parse-tokens`:	Internal functions
	`Function, read-string-in-package`:	Internal functions
	`Function, slurp-file`:	Internal functions
	`Function, trim-whitespace`:	Internal functions
	`Function, whitespacep`:	Internal functions

G
	`Generic Function, body`:	Exported generic functions
	`Generic Function, code`:	Exported generic functions
	`Generic Function, emit`:	Internal generic functions
	`generic-compile`:	Internal functions

M
	`Macro, deftemplate`:	Exported macros
	`Method, body`:	Exported generic functions
	`Method, code`:	Exported generic functions
	`Method, code`:	Exported generic functions
	`Method, code`:	Exported generic functions
	`Method, emit`:	Internal generic functions
	`Method, emit`:	Internal generic functions
	`Method, emit`:	Internal generic functions
	`Method, emit`:	Internal generic functions
	`Method, emit`:	Internal generic functions

P
	`parse-pathname`:	Exported functions
	`parse-template`:	Exported functions
	`parse-tokens`:	Internal functions

R
	`read-string-in-package`:	Internal functions

S
	`slurp-file`:	Internal functions

T
	`trim-whitespace`:	Internal functions

W
	`whitespacep`:	Internal functions

Jump to:	B C D E F G M P R S T W

A.3 Variables

Jump to:	+ B C S

	Index Entry	Section

+
	`+whitespace+`:	Internal special variables

B
	`body`:	Exported classes

C
	`code`:	Exported classes
	`code`:	Exported classes
	`code`:	Internal classes

S
	`Slot, body`:	Exported classes
	`Slot, code`:	Exported classes
	`Slot, code`:	Exported classes
	`Slot, code`:	Internal classes
	`Special Variable, +whitespace+`:	Internal special variables

Jump to:	+ B C S

A.4 Data types

Jump to:	< C E P S

	Index Entry	Section

<
	`<block-tag>`:	Internal classes
	`<block>`:	Exported classes
	`<else-tag>`:	Exported classes
	`<end-tag>`:	Internal classes
	`<expr-tag>`:	Exported classes
	`<tag>`:	Internal classes

C
	`Class, <block-tag>`:	Internal classes
	`Class, <block>`:	Exported classes
	`Class, <else-tag>`:	Exported classes
	`Class, <end-tag>`:	Internal classes
	`Class, <expr-tag>`:	Exported classes
	`Class, <tag>`:	Internal classes

E
	`eco`:	The eco system
	`eco`:	The eco package
	`eco-template`:	The eco-template package
	`eco.compiler`:	The eco<dot>compiler package
	`eco.parser`:	The eco<dot>parser package

P
	`Package, eco`:	The eco package
	`Package, eco-template`:	The eco-template package
	`Package, eco.compiler`:	The eco<dot>compiler package
	`Package, eco.parser`:	The eco<dot>parser package

S
	`System, eco`:	The eco system

Jump to:	< C E P S

• Introduction:		What eco is all about
• Systems:		The systems documentation
• Modules:		The modules documentation
• Files:		The files documentation
• Packages:		The packages documentation
• Definitions:		The symbols documentation
• Indexes:		Concepts, functions, variables and data types

• The eco.asd file:
• The eco/src/parser.lisp file:
• The eco/src/compiler.lisp file:
• The eco/src/asdf.lisp file:
• The eco/src/eco.lisp file:

• The eco.parser package:
• The eco-template package:
• The eco.compiler package:
• The eco package:

• Exported macros:
• Exported functions:
• Exported generic functions:
• Exported classes:

• Internal special variables:
• Internal functions:
• Internal generic functions:
• Internal classes:

• Concept index:
• Function index:
• Variable index:
• Data type index:

The eco Reference Manual

Table of Contents

The eco Reference Manual

1 Introduction

Eco - Fast, flexible, designer-friendly templates.

Goals

Usage

Tags

Options

Reference

deftemplate

Examples

if

Implementation

License

2 Systems

2.1 eco

3 Modules

3.1 eco/src

4 Files

4.1 Lisp

4.1.1 eco.asd

4.1.2 eco/src/parser.lisp

4.1.3 eco/src/compiler.lisp

4.1.4 eco/src/asdf.lisp

4.1.5 eco/src/eco.lisp

5 Packages

5.1 eco.parser

5.2 eco-template

5.3 eco.compiler

5.4 eco

6 Definitions

6.1 Exported definitions

6.1.1 Macros

6.1.2 Functions

6.1.3 Generic functions

6.1.4 Classes

6.2 Internal definitions

6.2.1 Special variables

6.2.2 Functions

6.2.3 Generic functions

6.2.4 Classes

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types

`deftemplate`

`if`

2.1 `eco`

3.1 `eco/src`

4.1.1 `eco.asd`

4.1.2 `eco/src/parser.lisp`

4.1.3 `eco/src/compiler.lisp`

4.1.4 `eco/src/asdf.lisp`

4.1.5 `eco/src/eco.lisp`

5.1 `eco.parser`

5.2 `eco-template`

5.3 `eco.compiler`

5.4 `eco`