Data Formats

After this page you can read and write Phel data as text, for config files or to exchange it with Clojure, Java, or JavaScript. Phel ships two modules for this:

• phel.edn: EDN, the data subset of Clojure syntax.
• phel.transit: Transit, rich types encoded as JSON.

Neither calls eval, so both are safe on untrusted input. Plain JSON goes through phel.json instead (see the Cookbook). Use EDN or Transit when keywords, sets, symbols, or tagged values must survive the round trip.

phel.edn#

The main use: read a config file into a Phel map, and write data back out.

(ns my-app.config
  (:require phel.edn :as edn))

(edn/read-string "{:host \"localhost\" :port 4000 :tags #{:web} ; the web node\n}")
; => {:host "localhost", :port 4000, :tags #{:web}}

(edn/write-string {:users [{:name "Alice"} {:name "Bob"}]})
; => "{:users [{:name \"Alice\"} {:name \"Bob\"}]}"

(edn/read-string "(+ 1 2)")
; => (+ 1 2)

The last line returns a list, not 3: reading never evaluates. For a file, read its contents first: (edn/read-string (php/file_get_contents "config.edn")).

Functions#

Options#

(ns my-app.edn-tags
  (:require phel.edn :as edn))

(edn/read-string "#my.app/Point [1 2]"
                 {:readers {'my.app/Point (fn [[x y]] {:x x :y y})}})
; => {:x 1, :y 2}

(edn/read-string-all "1 2 3")      ; => [1 2 3]
(edn/read-string "" {:eof :no-data}) ; => :no-data

What round-trips#

phel.edn reads with Phel's own reader and writes with its readable printer, so every value Phel prints readably comes back equal: nil, booleans, numbers, strings, characters, keywords, symbols, lists, vectors, maps, sets, and the built-in tags #uuid, #inst, and #regex. Namespaced tags such as #my.app/Person read as one tag.

phel.transit#

The main use: send Phel data to a Clojure or JavaScript service over HTTP and read its answer, with keywords and sets intact.

(ns my-app.api
  (:require phel.transit :as transit))

(def wire (transit/write-string {:status :ok :tags #{:a}}))
wire
; => "[\"~#cmap\",[\"~:status\",\"~:ok\",\"~:tags\",[\"~#set\",[\"~:a\"]]]]"

(transit/read-string wire)
; => {:status :ok, :tags #{:a}}

(transit/write-string {"name" "Alice"})
; => "{\"name\":\"Alice\"}"

A map with only string keys becomes a plain JSON object. Any other map, including one with keyword keys, becomes a ~#cmap array.

Functions#

Options#

(ns my-app.transit-tags
  (:require phel.transit :as transit))

(transit/read-string "[\"~#point\",[1,2]]"
                     {:handlers {"point" (fn [[x y]] {:x x :y y})}})
; => {:x 1, :y 2}

(transit/read-string "[\"~#myapp/Foo\",[1,2]]"
                     {:default-handler (fn [tag rep] [:unknown tag rep])})
; => [:unknown "myapp/Foo" [1 2]]

Type mapping#

Limits#

• Only JSON-Verbose. The cached-key encoding (^ markers) and Transit+MessagePack are not supported.
• write-string has no :handlers option. Convert custom types to supported values before you write them.

Every function and its signature: edn API reference.