more cleanups & docs

org/apt-notes.org

@@ -0,0 +1,19 @@
+#+title: Apt Notes
+* ideas
+** state
+state is a global hashmap.
+top keys are references, which uniquely identify an idea.
+top values are the content of the ideas.
+** fields
+ideas have stuff in _meta field
+notably [:_meta :_properties] and [:meta :_reference]
+there is also _parent.
+*** TODO _parent and _meta need getters
+** uid-of
+uses property system to deref ideas
+should be used rather than prtc/value
+
+* properties
+** in state
+state has a top-level _property key
+below that is a hierarchical map of the different property keys (like :foo into :bar into :baz) that finally has a :_node key, which is a set of all idea references for that property

src/cljs/emptyhead/idea/memtag.cljs

@@ -1,5 +1,7 @@
 (ns emptyhead.idea.memtag
   (:require [emptyhead.idea.protocol :as prtc]))
 
-(defn uid-of [idea]
+(defn uid-of
+  "Returns the property containing the idea's reference."
+  [idea]
   [:emptyhead :memtag :uid (prtc/ref-fn keyword idea)])

src/cljs/emptyhead/idea/property.cljs

@@ -33,10 +33,12 @@
         iref (prtc/reference idea)]
     (when property
       (reduce
-       (fn [acc property]
+       ; iterate over each segment in the property. e.g. for [:foo :bar :baz] => first foo, then bar, then baz
-         (swap! state/state update-in (conj acc property :_node) (fnil conj #{}) iref)
+       ; acc grows iteratively into (conj [:_properties] property) by the end
-         (swap! state/state update-in [iref :_meta :_properties] (fnil conj #{}) (conj (vec (rest acc)) property))
+       (fn [acc property-segment]
-         (conj acc property))
+         (swap! state/state update-in (conj acc property-segment :_node) (fnil conj #{}) iref)
+         (swap! state/state update-in [iref :_meta :_properties] (fnil conj #{}) (conj (vec (rest acc)) property-segment))
+         (conj acc property-segment))
        [:_properties] property))
     (when tail
       (run! #(register-property! idea %) tail))

src/cljs/emptyhead/idea/protocol.cljs

@@ -44,7 +44,7 @@
   [idea]
   (assoc-in (value idea) [:_meta :_stale-reference] true))
 
-(defn non-copy [idea] (assoc-in (value idea) [:_meta :_stale-reference] false))
+(defn- non-copy [idea] (assoc-in (value idea) [:_meta :_stale-reference] false))
 
 (defn uncopy!
   "Takes a copied idea and 'uncopies' it, making its reference active again

src/cljs/emptyhead/lib/core.cljs

@@ -13,7 +13,7 @@
 
 (def/define! [:emptyhead :core :get-data]
   (fn [thought parent]
-    [parent (prtc/val-fn :data parent)]))
+    [parent (thought/data parent)]))
 
 (def/define! [:emptyhead :core :return]
   (fn [thought parent]

src/cljs/emptyhead/repl/core.cljs

@@ -5,7 +5,6 @@
             [emptyhead.idea.property :as prop]
             [emptyhead.util.magic :as magic]
             [emptyhead.idea.protocol :as prtc]
-            [emptyhead.idea.crud :as idea]
             [emptyhead.idea.memtag :as memtag]
             [emptyhead.thought.define :as def]
             [emptyhead.thought.crud :as thought]
@@ -71,8 +70,7 @@
   (clear-context)
   (run! #(eval! % context) (apply read input))
   (pprint-tos context)
-  (prtc/reference (teval/execute! context context))
+  (prtc/reference (teval/execute! context context)))
-  )
 
 ;; XXX an annoying class of bug is eg  forgetting the return value here, which yields just
 ;; >No protocol method Idea.value defined for type null:
@@ -82,13 +80,12 @@
 (def/define! [:emptyhead :debug :track]
   (fn [thought parent]
     (let [ctx (:_parent (prtc/value parent))]
-      (print "RUNNING " (:operator (prtc/value parent)) " ON ")
+      (print "RUNNING " (thought/operator parent) " ON ")
       (print "CONTEXT " ctx " WITH \n")
       (print "STACK: ")
       (print (:return ctx))
       (print "\n\n")
-      [parent nil]
+      [parent nil])))
-      )))
 
 (def sample (thought/register-thought! [:foo]))
 
@@ -115,7 +112,7 @@
 
 (defn deref-name
   [self name]
-  (or (and (= (prtc/val-fn :operator self) [:emptyhead :core :context])
+  (or (and (= (thought/operator self) [:emptyhead :core :context])
            (resolve-name self name))
       (and (prtc/val-fn :_parent self)
            (deref-name (prtc/val-fn :_parent self) name))))
@@ -182,5 +179,4 @@
 
     [:meme]
     emptyhead.core.deref-name
-    emptyhead.core.execute
+    emptyhead.core.execute))
-    ))

src/cljs/emptyhead/thought/crud.cljs

@@ -8,15 +8,13 @@
 (defn make-thought
   "Helper function to make thought object.
   You may want `register-thought!` instead."
-  [operator & {:keys [data ext-contract ext-stages]
+  [operator & {:keys [data ext-stages]
-               :or {data {} ext-contract {}
+               :or {data {}
                     ext-stages [[:PRE-EXECUTE] [:EXECUTE] [:POST-EXECUTE]]}}]
   (hash-map :operator operator
             :data data
-            :ext-contract ext-contract
             :ext-stages ext-stages
-            :return []
+            :return []))
-            :transient nil))
 
 (defn register-thought!
   "Create a thought and register it in the state.

src/cljs/emptyhead/thought/define.cljs

@@ -6,7 +6,7 @@
             [emptyhead.idea.memtag :as memtag]
             [emptyhead.idea.protocol :as prtc]))
 
-(defn register-implementation!
+(defn- register-implementation!
   [operator impl]
   (let [impl-prop (magic/thought-impl-prop operator)]
     (idea/have-idea! :prefix (str "impl_thought#" (magic/symbolize-ns operator))
@@ -14,7 +14,8 @@
                      :shadowing [impl-prop]
                      :data {:implementation impl})))
 
-(defn register-constructor!
+; TODO add documentation / elaborate on this whole constr-fn stuff
+(defn- register-constructor!
   [operator & {:keys [constr-fn defaults]
                :or {constr-fn (fn [thought parent] {})
                     defaults {}}}]
@@ -34,6 +35,8 @@
                    (constr-fn thought parent))))])))))
 
 (defn define!
+  "Define a new kind of thought, with its operator name and implementation.
+   TODO explain what constr-fn and defaults does"
   [operator impl & {:keys [constr-fn defaults]
                     :as constr-args}]
   (register-implementation! operator impl)

src/cljs/emptyhead/thought/extend.cljs

@@ -1,6 +1,5 @@
 (ns emptyhead.thought.extend
-  (:require [emptyhead.contract.eval :as contract]
+  (:require [emptyhead.idea.property :as prop]
-            [emptyhead.idea.property :as prop]
             [emptyhead.idea.protocol :as prtc]
             [emptyhead.thought.crud :as thought]
             [emptyhead.util.magic :as magic]

src/cljs/emptyhead/util/logging.cljs

@@ -0,0 +1,10 @@
+(ns emptyhead.util.logging)
+
+(defn error [message & data]
+  (throw (ex-info message {:data data})))
+
+(defn warn [message & data]
+  (error message data))
+
+(defn message [message & data]
+  (println message {:data data}))