From 0134e486e26b10bbaa9512725e8aa5fc8e4040cd Mon Sep 17 00:00:00 2001
From: Grant Shoshin Shangreaux <shoshin@cicadas.surf>
Date: Sat, 19 Nov 2022 09:29:44 -0600
Subject: Add: notes about parse/modify/insert org-data

---
 annotations       |  2 +-
 coorgi-client.org | 51 +++++++++++++++++++++++++++++++++++++++------------
 2 files changed, 40 insertions(+), 13 deletions(-)

diff --git a/annotations b/annotations
index 653332b..be098d8 100644
--- a/annotations
+++ b/annotations
@@ -1 +1 @@
-(("~/projects/coorgi-client/coorgi-client.org" ((804 805 "trying again -g" "*") (582 584 "these were some of the sync features we chatted about -g" "**") (122 191 "So just trying this out -colin" "If you evaluate the following block, it will effecively \"eval-buffer\"")) "f6ceb154c242ada8a71f34feb75213fb"))
\ No newline at end of file
+(("~/projects/coorgi-client/coorgi-client.org" ((383 452 "So just trying this out -colin" "If you evaluate the following block, it will effecively \"eval-buffer\"") (1232 1235 "find a simple example of modifying the org-data structure -g" "***") (1488 1490 "these were some of the sync features we chatted about -g" "**") (1710 1711 "trying again -g" "*")) "17fa2b5715c813dadcb07ca0b6ec4ec3"))
\ No newline at end of file
diff --git a/coorgi-client.org b/coorgi-client.org
index 80d7429..6860ca0 100644
--- a/coorgi-client.org
+++ b/coorgi-client.org
@@ -1,9 +1,16 @@
 #+PROPERTY: header-args:emacs-lisp :lexical t
 
+#+name: test-trivial-example-cursor-in-body
+#+begin_src emacs-lisp :var org-doc=trivial-example()
+  (let ((subject (with-temp-buffer (insert org-doc) (org-element-parse-buffer))))
+    (print subject)
+    (print (org-element-interpret-data subject)))
+#+end_src
+
+
 * Coorgi Client - A collaborative org document sync client.
 ** Overview
 
-
 If you evaluate the following block, it will effecively "eval-buffer"
 on the whole shebang.
 
@@ -27,6 +34,25 @@ on the whole shebang.
   ;;; coorgi-client.el ends here
 #+end_src
 
+** Parsing, modifying, and re-inserting org data
+
+~org-element-parse-buffer~ will turn any org document into a parsed
+data tree. ~org-element-interpret-data~ will turn any (valid) parsed
+org-data structure back into a string.
+
+therefore, we /should/ be able to act upon the parsed data with Coorgi
+functions to update the document, rather than mucking with live buffer
+edits and updates.
+
+*** TODO example proof of concept
+
+For example:
+
+#+begin_src emacs-lisp :var org-doc=trivial-example() :results verbatim
+  (let ((subject (with-temp-buffer (insert org-doc) (org-element-parse-buffer))))
+    (org-element-interpret-data subject))
+#+end_src
+
 ** Syncing Coorgi documents with collaborators
 *** TODO ~coorgi-initialize~ creates the document on the server
 *** TODO Coorgi syncs on the ~after-save-hook~
@@ -88,7 +114,6 @@ Converts the current org outline section into a coorgi-node data structure.
 #+end_src
 
 *** Testing
-
 **** Trivial Org Example
 
 Given this org document:
@@ -139,16 +164,18 @@ No matter where the cursor is in the buffer (there's only one coorgi node)
 #+end_src
 
 #+RESULTS: test-trivial-example-cursor-in-body
-#+begin_src emacs-lisp
-((actual
-  (type entry headline "MOO" version 1 last-modified-by "colin/123" last-modified "123" key "101" properties
-	(:FOO "bar")
-	contents "hello\n"))
- (expected
-  (type entry headline "MOO" version 1 last-modified-by "colin/123" last-modified "123" key "101" properties
-	(:FOO "bar")
-	content "\nhello\n\n" children nil)))
-#+end_src
+#+begin_example
+,* MOO
+:PROPERTIES:
+:coorgi-version: 1
+:coorgi-last-modified-by: colin/123
+:coorgi-last-modified: 123
+:coorgi-key: 101
+:foo:      bar
+:END:
+
+hello
+#+end_example
 
 ***** TODO When the cursor at the top of the document
 
-- 
cgit v1.2.3