Types and Data Structures

Back to Index

Table of Contents

User-Facing Types Example
Literals 123, "bang", x, nil
Hiccup [:float 3 [:msg "bang"]]
Internal Types Example
Node {:args ["bang"], :type :node, :op "msg", :unique-id 76, :options {}}
Connection {:type :connection, :from-node {:outlet 0, :id 1}, :to-node {:id 0, :inlet 0}}
Lines [<Node> \| <Connection>, ...]
Context  
File "#N canvas 0 0 450 300 10;\n#X obj 5 5 +;"

Literals

Numbers, Strings, Chars and NIL are considered literals. When literals are used as arguments in Nodes, they are passed (mostly) unchanged into PureData file format. Exception: nil is used to skip a positional argument. Strings are escaped (notably the characters $, ; and ,) by to-string.

Predicate
(or (number? arg)
    (string? arg)
    (char? arg)
    (nil? arg))

back to top

Hiccup

Hiccup markup is used to create PureData nodes using pd. The syntax is [operator options? arguments*]:

position type example how many
operator keyword :+ exactly 1
options? map {:x 10 :y 10} 1 or none
arguments literal or more hiccup 123, "bang", [:- 3 4] any number

Or, shown differently:

<hiccup> ::= "[" <operator> " " <options-maybe> <arguments-maybe> "]"
<options-maybe> ::= <options> | ""
<options> ::= "{" <key-value-pair-maybe> "}"
<key-value-pair-maybe> ::= <key-value-pair> | <key-value-pair> <key-value-pair-maybe> | ""
<key-value-pair> ::= <key> " " <value>
<key> ::= ":" <string>
<value> ::= <literal>
<arguments-maybe> ::= <argument> | <argument> <arguments-maybe> | ""
<argument> ::= <hiccup> | <literal>
Predicate
(and (vector? form)
     (or (keyword? (first form))
         (string? (first form))))
Example
(pd [:float {:x 0 :y 0} 3 [:msg "bang"]])

=> {:args
    [3
      {:args ["bang"],
       :type :node,
       :op "msg",
       :unique-id 76,
       :options {}}],
     :type :node,
     :op "float",
     :unique-id 75,
     :options {:x 0, :y 0}}

back to top

Node

Nodes are created from hiccup markup by pd. They are further processed by lines.

Predicate
(and (map? arg)
     (= (:type arg) :node))
Content
{
    :type :node    ;; <keyword>
    :op "+"        ;; <string>
    :id 1          ;; <int>, assigned by `walk-node!` during contextualization by `in-context`
    :unique-id 123 ;; <int>, generated from global counter when `pd`
    :options {}    ;; <hashmap>
    :args []       ;; vector of node arguments, either literals or other nodes
}
Example
(pd [:float])

=> {:args [], :type :node, :op "float", :unique-id 71, :options {}}

back to top

Connection

Connections are created by walk-node-args! and added to output of lines whenever two nodes that are connected are found during parsing.

Content
{
    :type :connection
    :from-node {
        :id <int>
        :outlet <int>
    }
    :to-node {
        :id <int>
        :inlet <int>
    }
}
Example
(last (lines (pd [:float [:msg]])))
    
=> {:type :connection,
    :from-node {:outlet 0, :id 1},
    :to-node {:id 0, :inlet 0}}

back to top

Lines

Lines are a sorted vector consisting of Nodes and Connections. They are produced by lines and consumed by patch.

Example
(lines (pd [:+ [:-]]))

=> [{:args [], :type :node, :op "+", :col 0, :id 0, :unique-id 1, :options {:y 45, :x 5}, :auto-layout true, :row 1}
    {:args [], :type :node, :op "-", :col 0, :id 1, :unique-id 2, :options {:y 5, :x 5}, :auto-layout true, :row 0}
    {:type :connection, :from-node {:outlet 0, :id 1}, :to-node {:id 0, :inlet 0}}]

back to top

Context

Context is created temporarily by lines, and discarded after it has finished. It might see future use when supporting subpatches (e.g. nested patches).

Content
{
    :current-node-id 0     ;; <int>
    :lines []              ;; <vector> of type Node and Connection
    :processed-node-ids {} ;; keys are <int> (`:unique-id` of Node), values are <int> (`:id` of Node)
}

back to top

Patch

Example

A patch is represented internally as the list of Strings that make up the File describing the patch when concatenated.

(patch "example.pd" {} (lines (pd [:+])))

=> ("#N canvas 0 0 450 300 10;" "#X obj 5 5 +;")

back to top

File

File is the actual file on disk, and also the return value of write, write-patch and write-patch-reload. As a return value, it is just the file contents as a single String.

Example
(write "example.pd" (patch "example.pd" {} (lines (pd [:+]))))

=> "#N canvas 0 0 450 300 10;\n#X obj 5 5 +;"

back to top