The eco Reference Manual

Table of Contents

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

The eco Reference Manual

This is the eco Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Apr 28 11:44:21 2020 GMT+0.


Next: , Previous: , Up: Top   [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: Top   [Contents][Index]

2 Systems

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


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

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 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
Source

eco.asd (file)

Component

src (module)


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

3 Modules

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


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

3.1 eco/src

Parent

eco (system)

Location

src/

Components

Next: , Previous: , Up: Top   [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 files   [Contents][Index]

4.1.1 eco.asd

Location

eco.asd

Systems

eco (system)


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

4.1.2 eco/src/parser.lisp

Parent

src (module)

Location

src/parser.lisp

Packages

eco.parser

Exported Definitions
Internal Definitions

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

4.1.3 eco/src/compiler.lisp

Dependency

parser.lisp (file)

Parent

src (module)

Location

src/compiler.lisp

Packages
Exported Definitions
Internal Definitions

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

4.1.4 eco/src/asdf.lisp

Dependency

compiler.lisp (file)

Parent

src (module)

Location

src/asdf.lisp


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

4.1.5 eco/src/eco.lisp

Dependency

asdf.lisp (file)

Parent

src (module)

Location

src/eco.lisp

Packages

eco

Exported Definitions
Internal Definitions

generic-compile (function)


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

5 Packages

Packages are listed by definition order.


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

5.1 eco.parser

Source

parser.lisp (file)

Use List
Used By List

eco.compiler

Exported Definitions
Internal Definitions

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

5.2 eco-template

Source

compiler.lisp (file)

Use List

common-lisp

Used By List

eco.compiler

Exported Definitions

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

5.3 eco.compiler

Source

compiler.lisp (file)

Use List
Exported Definitions

compile-template (function)

Internal Definitions

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

5.4 eco

Source

eco.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

generic-compile (function)


Next: , Previous: , Up: Top   [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 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Macros

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

eco-template

Source

compiler.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Previous: , Up: Exported definitions   [Contents][Index]

6.1.4 Classes

Class: <block> ()
Package

eco.parser

Source

parser.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

<call> (class)

Direct methods
Direct slots
Slot: code
Initargs

:code

Readers

code (generic function)

Slot: body
Initargs

:body

Readers

body (generic function)

Class: <call> ()
Package

eco.parser

Source

parser.lisp (file)

Direct superclasses

<block> (class)

Direct methods

emit (method)

Class: <else-tag> ()
Package

eco.parser

Source

parser.lisp (file)

Direct superclasses

<tag> (class)

Class: <expr-tag> ()
Package

eco.parser

Source

parser.lisp (file)

Direct superclasses

<tag> (class)

Direct methods
Direct slots
Slot: code
Initargs

:code

Readers

code (generic function)


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

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Special variables

Special Variable: *template-package*
Package

eco.compiler

Source

compiler.lisp (file)

Special Variable: +whitespace+
Package

eco.parser

Source

parser.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Functions

Function: else-tag-p ELEMENT
Package

eco.compiler

Source

compiler.lisp (file)

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-template-expressions STRING
Package

eco.compiler

Source

compiler.lisp (file)

Function: slurp-file PATH
Package

eco.parser

Source

parser.lisp (file)

Function: template-element-p ELEMENT
Package

eco.compiler

Source

compiler.lisp (file)

Function: trim-whitespace STR
Package

eco.parser

Source

parser.lisp (file)

Function: whitespacep CHAR
Package

eco.parser

Source

parser.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.3 Generic functions

Generic Function: emit STR
Package

eco.compiler

Methods
Method: emit (CALL <call>)
Source

compiler.lisp (file)

Method: emit (BLOCK <block>)
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)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.4 Classes

Class: <block-tag> ()
Package

eco.parser

Source

parser.lisp (file)

Direct superclasses

<tag> (class)

Direct subclasses

<call-tag> (class)

Direct methods

code (method)

Direct slots
Slot: code
Initargs

:code

Readers

code (generic function)

Class: <call-tag> ()
Package

eco.parser

Source

parser.lisp (file)

Direct superclasses

<block-tag> (class)

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

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

Appendix A Indexes


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

A.1 Concepts

Jump to:   E   F   L   M  
Index Entry  Section

E
eco.asd: The eco․asd file
eco/src: The eco/src module
eco/src/asdf.lisp: The eco/src/asdf․lisp file
eco/src/compiler.lisp: The eco/src/compiler․lisp file
eco/src/eco.lisp: The eco/src/eco․lisp file
eco/src/parser.lisp: The eco/src/parser․lisp file

F
File, Lisp, eco.asd: The eco․asd file
File, Lisp, eco/src/asdf.lisp: The eco/src/asdf․lisp file
File, Lisp, eco/src/compiler.lisp: The eco/src/compiler․lisp file
File, Lisp, eco/src/eco.lisp: The eco/src/eco․lisp file
File, Lisp, eco/src/parser.lisp: The eco/src/parser․lisp file

L
Lisp File, eco.asd: The eco․asd file
Lisp File, eco/src/asdf.lisp: The eco/src/asdf․lisp file
Lisp File, eco/src/compiler.lisp: The eco/src/compiler․lisp file
Lisp File, eco/src/eco.lisp: The eco/src/eco․lisp file
Lisp File, eco/src/parser.lisp: The eco/src/parser․lisp file

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

Jump to:   E   F   L   M  

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: 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
else-tag-p: Internal 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, else-tag-p: Internal 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-template-expressions: Internal functions
Function, slurp-file: Internal functions
Function, template-element-p: 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-template-expressions: Internal functions

S
slurp-file: Internal functions

T
template-element-p: Internal functions
trim-whitespace: Internal functions

W
whitespacep: Internal functions

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

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

A.3 Variables

Jump to:   *   +  
B   C   S  
Index Entry  Section

*
*template-package*: Internal special variables

+
+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, *template-package*: Internal special variables
Special Variable, +whitespace+: Internal special variables

Jump to:   *   +  
B   C   S  

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

A.4 Data types

Jump to:   <  
C   E   P   S  
Index Entry  Section

<
<block-tag>: Internal classes
<block>: Exported classes
<call-tag>: Internal classes
<call>: 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, <call-tag>: Internal classes
Class, <call>: 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․compiler package
eco.parser: The eco․parser package

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

S
System, eco: The eco system

Jump to:   <  
C   E   P   S