The caramel Reference Manual

Table of Contents

The caramel Reference Manual

This is the caramel Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 14:19:31 2021 GMT+0.

1 Introduction

Caramel

Enlive like css selector-based template system in Common Lisp

Installation

(ql:quickload :caramel)

Usage

html-resource

build dom from html file

(html-resource #p"/path/to/your/html/file")

select

search node by css selector

(select "#id" dom-node)
=> Matching node list 

Translator

Every translator returns a function which takes a node and return translated node or nodes.

set-attr

Set attributes to node

(set-attr :foo "baz" :bar "wow")

remove-attr

Remove attributes from node

(remove-attr :foo :bar)

add-class

Add css classes to node

(add-class "cls-foo" "cls-bar")

remove-class

Remove css classes from node

(remove-class "cls-foo" "cls-bar")

content

Set content of node

(content "foo" a-node "foo")

html-content

Build html from specified string and set

(html-content "<p>Foo</p>")

wrap

Wrap node with specified tag

(wrap "p")

unwrap

Get content of node

(unwrap)

do->

Cascade transform to node

(do-> (content "foo") (set-attr :color "green") (add-class "cls-foo"))

before

Insert nodes before node

(before "foo" a-node "baz")

after

Insert nodes after node

(after "foo" a-node "baz")

substitute

Replace node with nodes

(substitute "foo" a-node "baz")

move

Move matched node

(move src-selector dst-selector)

clone-for

Clone nodes

(clone-for x '(1 2 3) (content x))

(clone-for x '(1 2 3)
 "p" (content x)
 "h1" (content "foo"))

Snippet & Template

defsnippet

Define snippet from file.

(defsnippet bar #p"/path/to/your/file" "div#baz" ()
  "p" (content "foo"))

(bar)
=> node-list

deftemplate

Define template from file.

(deftemplate foo #p"/path/to/your/base/file" (&optional foo)
  "#bar" (do-> 
          (content "fuge") 
          (set-attr :color "green") 
          (add-class "cls-foo"))
  "p#para" (if foo
             (content foo)
             (content "defaul")))

Scraping

get-attr

Get attribute value of node

(get-attr node name)

get-attrs

Get attribute alist of node

(get-attrs node)

get-content

Get content of node

(get-content text-node)
=> content string
(get-content document-or-element)
=> children-list

example

    (defun -> (&rest fns)
     (lambda (init)
      (loop with citem = init
       for fn in fns
       do
       (setf citem (funcall fn citem))
       finally (return citem))))

    (defun google-search (word)
       (let* ((query (list (cons "q" word)))
              (str (drakma:http-request "http://www.google.com/search"
                                  :parameters query))
              (dom (html-resource str)))
            (loop 
               for node in (select "h3.r" dom)
               collect (get-attr (funcall (-> (unwrap) #'first) node) "href"))))

    (google-search "foo")
    =>
    ("/url?q=http://en.wikipedia.org/wiki/Foobar&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CBgQFjAA&usg=AFQjCNENNqcYY0yw8Y9RKmzildDpcRlcSg"
     "/url?q=http://www.foo.com/&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CCEQFjAB&usg=AFQjCNEi6s8gBpsT6sK5Em5Rq-zpL6v01w"
     "/url?q=http://www.urbandictionary.com/define.php%3Fterm%3Dfoo&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CCUQFjAC&usg=AFQjCNFC3xe17h6LLn86ZXUtY4CXfCcOwQ"
     "/url?q=http://catb.org/jargon/html/F/foo.html&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CCkQFjAD&usg=AFQjCNFmr2ssHlV9Sjrrq833Rz8TjsDSFQ"
     "/url?q=http://foofood.ca/&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CCwQFjAE&usg=AFQjCNFVHsem3EcurfHqsByEIR70wJ0vNA"
     "/url?q=http://www.foofighters.com/&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CC8QFjAF&usg=AFQjCNFgY5a73m8zvOltlo1SeHm3h0asUw"
     "/url?q=http://www.forgetfoo.com/&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CDMQFjAG&usg=AFQjCNFHZEG0pjLC-fwDNKPOv6MZu4Y4qQ"
     "/url?q=http://www.foo-apartment.com/&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CDgQFjAH&usg=AFQjCNHkIFr_2j-KtvcHPxWd-XMhLudjcQ"
     "/url?q=http://www.facebook.com/foofighters&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CDwQFjAI&usg=AFQjCNE-mJsSRMzQUdMOXjPToJljjmVeFg"
     "/url?q=http://www.ietf.org/rfc/rfc3092.txt&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CEAQFjAJ&usg=AFQjCNFYfQd6aQqdZy9M5W4lzgTkosaniA")

Author

• Masato Sogame (poketo7878@gmail.com)

Copyright

Copyright (c) 2013 Masato Sogame (poketo7878@gmail.com)

License

    Licensed under the LLGPL License.

2 Systems

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

2.1 caramel

Author

Masato Sogame

License

LLGPL

Description

CSS selector-based template engine for Common Lisp

Long Description

# Caramel

Enlive like css selector-based template system in Common Lisp

## Installation

(ql:quickload :caramel)

## Usage

### html-resource

build dom from html file

(html-resource #p"/path/to/your/html/file")

### select

search node by css selector

(select "#id" dom-node)
=> Matching node list

### Translator

Every translator returns a function
which takes a node and return translated node or nodes.

#### set-attr

Set attributes to node

(set-attr :foo "baz" :bar "wow")

#### remove-attr

Remove attributes from node

(remove-attr :foo :bar)

#### add-class

Add css classes to node

(add-class "cls-foo" "cls-bar")

#### remove-class

Remove css classes from node

(remove-class "cls-foo" "cls-bar")

#### content

Set content of node

(content "foo" a-node "foo")

#### html-content

Build html from specified string and set

(html-content "<p>Foo</p>")

#### wrap

Wrap node with specified tag

(wrap "p")

#### unwrap

Get content of node

(unwrap)

#### do->

Cascade transform to node

(do-> (content "foo") (set-attr :color "green") (add-class "cls-foo"))

#### before

Insert nodes before node

(before "foo" a-node "baz")

#### after

Insert nodes after node

(after "foo" a-node "baz")

#### substitute

Replace node with nodes

(substitute "foo" a-node "baz")

#### move

Move matched node

(move src-selector dst-selector)

#### clone-for

Clone nodes

(clone-for x ’(1 2 3) (content x))

(clone-for x ’(1 2 3)
"p" (content x)
"h1" (content "foo"))

## Snippet & Template

### defsnippet

Define snippet from file.

(defsnippet bar #p"/path/to/your/file" "div#baz" ()
"p" (content "foo"))

(bar)
=> node-list

### deftemplate

Define template from file.

(deftemplate foo #p"/path/to/your/base/file" (&optional foo)
"#bar" (do->
(content "fuge")
(set-attr :color "green")
(add-class "cls-foo"))
"p#para" (if foo
(content foo)
(content "defaul")))

## Scraping

### get-attr

Get attribute value of node

(get-attr node name)

### get-attrs

Get attribute alist of node

(get-attrs node)

### get-content

Get content of node

(get-content text-node)
=> content string
(get-content document-or-element)
=> children-list

#### example

(defun -> (&rest fns)
(lambda (init)
(loop with citem = init
for fn in fns
do
(setf citem (funcall fn citem))
finally (return citem))))

(defun google-search (word)
(let* ((query (list (cons "q" word)))
(str (drakma:http-request "http://www.google.com/search"
:parameters query))
(dom (html-resource str)))
(loop
for node in (select "h3.r" dom)
collect (get-attr (funcall (-> (unwrap) #’first) node) "href"))))

(google-search "foo")
=>
("/url?q=http://en.wikipedia.org/wiki/Foobar&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CBgQFjAA&usg=AFQjCNENNqcYY0yw8Y9RKmzildDpcRlcSg" "/url?q=http://www.foo.com/&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CCEQFjAB&usg=AFQjCNEi6s8gBpsT6sK5Em5Rq-zpL6v01w" "/url?q=http://www.urbandictionary.com/define.php%3Fterm%3Dfoo&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CCUQFjAC&usg=AFQjCNFC3xe17h6LLn86ZXUtY4CXfCcOwQ" "/url?q=http://catb.org/jargon/html/F/foo.html&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CCkQFjAD&usg=AFQjCNFmr2ssHlV9Sjrrq833Rz8TjsDSFQ" "/url?q=http://foofood.ca/&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CCwQFjAE&usg=AFQjCNFVHsem3EcurfHqsByEIR70wJ0vNA" "/url?q=http://www.foofighters.com/&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CC8QFjAF&usg=AFQjCNFgY5a73m8zvOltlo1SeHm3h0asUw" "/url?q=http://www.forgetfoo.com/&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CDMQFjAG&usg=AFQjCNFHZEG0pjLC-fwDNKPOv6MZu4Y4qQ" "/url?q=http://www.foo-apartment.com/&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CDgQFjAH&usg=AFQjCNHkIFr_2j-KtvcHPxWd-XMhLudjcQ" "/url?q=http://www.facebook.com/foofighters&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CDwQFjAI&usg=AFQjCNE-mJsSRMzQUdMOXjPToJljjmVeFg" "/url?q=http://www.ietf.org/rfc/rfc3092.txt&sa=U&ei=Oas2UZrOFoyIkwXot4C4Cw&ved=0CEAQFjAJ&usg=AFQjCNFYfQd6aQqdZy9M5W4lzgTkosaniA")

## Author

* Masato Sogame (poketo7878@gmail.com)

## Copyright

Copyright (c) 2013 Masato Sogame (poketo7878@gmail.com)

# License

Licensed under the LLGPL License.

Version

0.1

Dependencies

• cxml
• alexandria
• iterate
• cxml-dom
• closure-html
• css-selectors
• buildnode

Source

caramel.asd (file)

Component

src (module)

3 Modules

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

3.1 caramel/src

Parent

caramel (system)

Location

src/

Component

caramel.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 caramel.asd

Location

caramel.asd

Systems

caramel (system)

Packages

caramel-asd

4.1.2 caramel/src/caramel.lisp

Parent

src (module)

Location

src/caramel.lisp

Packages

caramel

Exported Definitions

• add-class (function)
• after (function)
• append (function)
• before (function)
• clone-for (macro)
• content (function)
• defsnippet (macro)
• deftemplate (macro)
• do-> (function)
• get-attr (function)
• get-attrs (function)
• get-content (function)
• html-content (function)
• html-resource (function)
• move (function)
• prepend (function)
• remove-attr (function)
• remove-class (function)
• select (function)
• set-attr (function)
• substitute (function)

Internal Definitions

• apply-select-trans (macro)
• dom-to-html-string (function)
• flatmap (function)
• group (function)
• replace-node-with (method)
• treat-node-list (function)
• unwrap (function)
• with-clone-node (macro)
• wrap (function)

5 Packages

Packages are listed by definition order.

5.1 caramel-asd

Source

caramel.asd

Use List

• asdf/interface
• common-lisp

5.2 caramel

Source

caramel.lisp (file)

Use List

• iterate
• net.acceleration.buildnode
• css-selectors
• alexandria
• common-lisp

Exported Definitions

• add-class (function)
• after (function)
• append (function)
• before (function)
• clone-for (macro)
• content (function)
• defsnippet (macro)
• deftemplate (macro)
• do-> (function)
• get-attr (function)
• get-attrs (function)
• get-content (function)
• html-content (function)
• html-resource (function)
• move (function)
• prepend (function)
• remove-attr (function)
• remove-class (function)
• select (function)
• set-attr (function)
• substitute (function)

Internal Definitions

• apply-select-trans (macro)
• dom-to-html-string (function)
• flatmap (function)
• group (function)
• replace-node-with (generic function)
• replace-node-with (method)
• treat-node-list (function)
• unwrap (function)
• with-clone-node (macro)
• wrap (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: clone-for VAR LST &rest TRANS

Package

caramel

Source

caramel.lisp (file)

Macro: defsnippet NAME FILE-PATH SELECTOR ARGS &rest SELECT-TRANS-PAIR

Package

caramel

Source

caramel.lisp (file)

Macro: deftemplate NAME FILE-PATH ARGS &rest SELECT-BODY-PAIR

Package

caramel

Source

caramel.lisp (file)

6.1.2 Functions

Function: add-class &rest CLASS

Package

caramel

Source

caramel.lisp (file)

Function: after &rest NODES

Package

caramel

Source

caramel.lisp (file)

Function: append &rest NODES

Package

caramel

Source

caramel.lisp (file)

Function: before &rest NODES

Package

caramel

Source

caramel.lisp (file)

Function: content &rest VALUE

Package

caramel

Source

caramel.lisp (file)

Function: do-> &rest FNS

Package

caramel

Source

caramel.lisp (file)

Function: get-attr NODE NAME

Package

caramel

Source

caramel.lisp (file)

Function: get-attrs NODE

Package

caramel

Source

caramel.lisp (file)

Function: get-content NODE

Package

caramel

Source

caramel.lisp (file)

Function: html-content HTML-STR

Package

caramel

Source

caramel.lisp (file)

Function: html-resource INPUT

Package

caramel

Source

caramel.lisp (file)

Function: move SRC-SELECTOR DST-SELECTOR

Package

caramel

Source

caramel.lisp (file)

Function: prepend &rest NODES

Package

caramel

Source

caramel.lisp (file)

Function: remove-attr &rest ATTERS

Package

caramel

Source

caramel.lisp (file)

Function: remove-class &rest CLASS

Package

caramel

Source

caramel.lisp (file)

Function: select SELECTOR NODE

Package

caramel

Source

caramel.lisp (file)

Function: set-attr &rest ATTERS

Package

caramel

Source

caramel.lisp (file)

Function: substitute &rest NODES

Package

caramel

Source

caramel.lisp (file)

6.2 Internal definitions

6.2.1 Macros

Macro: apply-select-trans NODE SELECT TRANS

Package

caramel

Source

caramel.lisp (file)

Macro: with-clone-node VAR NODE &body BODY

Package

caramel

Source

caramel.lisp (file)

6.2.2 Functions

Function: dom-to-html-string DOM

Package

caramel

Source

caramel.lisp (file)

Function: flatmap FN NODE-OR-NODES

Package

caramel

Source

caramel.lisp (file)

Function: group LIST

Package

caramel

Source

caramel.lisp (file)

Function: treat-node-list DOC NODE-LIST

Package

caramel

Source

caramel.lisp (file)

Function: unwrap ()

Package

caramel

Source

caramel.lisp (file)

Function: wrap TAG

Package

caramel

Source

caramel.lisp (file)

6.2.3 Generic functions

Generic Function: replace-node-with OLD-NODE NODE-OR-NODES

Package

caramel

Methods

Method: replace-node-with (OLD-NODE node) NODE-OR-NODES

Source

caramel.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types