EEditor Manual

1. Getting Started

When you first launch EEditor you see an empty editor with a sidebar. Three steps to begin:

1. Open a folder — press ⌘O or tap the folder icon. EEditor scans the directory and displays all files in the sidebar tree.
2. Select a file — click any file in the sidebar to open it in a new tab.
3. Start writing — edits are auto-saved after 1 second of inactivity. Press ⌘S to save immediately.

Opening individual files

Use ⌘⇧O to open a single file from anywhere on disk. The file’s parent directory becomes the active folder.

2. The Editor

EEditor provides a distraction-free writing environment with real-time syntax highlighting for Markdown and 24+ programming languages.

• Syntax highlighting — headings, bold, italic, code blocks, links, and more are color-coded for Markdown. Code files get keyword, type, string, number, and comment highlighting.
• Find & Replace (⌘F) — search within the current document, replace single or all occurrences.
• Insert timestamp (⌘I) — inserts YYYY-MM-DD HH:mm at the cursor.
• Undo / Redo — ⌘Z / ⌘⇧Z.
• Language badge — the detected language is shown in the bottom-right corner.
• Wiki-links — place your cursor on [[filename]] and press ⌘O to open that file.
• Send to REPL (⌘R) — select text in the editor and press ⌘R to pre-fill the REPL input. Hit Enter to evaluate.

3. Sidebar & File Tree

The sidebar shows a hierarchical view of your folder. Directories sort first, then files alphabetically.

• Expand/collapse folders — click the disclosure triangle.
• Create a new file (⌘N) — enter a name like subfolder/file.md to create nested files.
• Create a new folder — use the folder + button in the toolbar.
• Delete — right-click → Delete (moved to Trash on macOS).
• Rename — right-click → Rename.
• Refresh (⌘⇧R) — rescan the directory while preserving expansion state.
• Run in REPL — right-click a .el or .lisp file to execute it.
• Reveal in Finder (macOS) — right-click to show in Finder.
• Dirty indicator — a dot appears next to files with unsaved changes.

The sidebar has three modes via the segmented toggle: Files, Calendar, and Agenda.

4. Tabs & Pinned Files

Each file opens as a tab at the top of the editor.

Pinned tabs show a pin icon, appear first (sorted alphabetically), and cannot be closed until unpinned. They are automatically restored on relaunch.

5. Search & Quick Open

Full-text search (⌘⇧F)

• Searches across all files in the workspace.
• Results grouped by file with line numbers and context.
• Toggle case-sensitive mode with the Aa button.
• Click a result to open the file at that location.

Quick Open (⌘P)

• Fuzzy file-name matching — results update as you type.
• Arrow keys to navigate, Enter to open, Escape to cancel.
• Prefix matches rank higher; shorter names break ties.
• Selection pre-fill: if text is selected in the editor, ⌘P pre-fills the search.

Wiki-links (⌘O)

Place your cursor on a [[filename]] link and press ⌘O to open that file directly.

6. Preview & PDF Export

Markdown preview (⌘⇧P)

• Renders your document as styled HTML with dark/light mode support.
• On macOS the preview opens in a frame; on iOS it appears as a sheet.

PDF export (⌘⇧E)

• Generates a print-ready A4 document (595 × 842 pt) with clean typography.
• macOS: save dialog with suggested filename. iOS: share sheet.

7. Daily Notes & Weekly Planner

Daily note (⌘D)

• Creates YYYY-MM-DD.md in the project root, pre-filled with a date heading.
• Opens the existing file if it already exists.

Weekly planner (⌘⇧W)

• Creates Week of YYYY-MM-DD.md (Monday of the current week).
• Pre-filled with a structured template: Monday–Sunday, Morning/Afternoon/Evening sections.

8. Calendar View

Toggle the sidebar to Calendar mode using the segmented control.

• A month grid shows the current month (Monday-first, ISO 8601).
• Dual dot indicators: blue dot = file activity, orange dot = agenda items.
• Navigate months with < / > buttons. Today jumps to the current month.
• Click a day to see files modified that day and agenda items scheduled for that date.

9. Agenda Sidebar

Toggle to Agenda mode via the clipboard icon. The panel shows your upcoming schedule in three sections:

• Overdue — items with a :when date before today.
• Today — items scheduled for today.
• Next 7 Days — upcoming items within the week.

Each item shows a priority dot (red = urgent, orange = high, yellow = medium, gray = normal), text, categories, and formatted date. Tap refresh to reload after adding items in the REPL.

REPL Sidebar

Toggle to REPL mode via the terminal icon in the sidebar segmented control. This embeds a full EELisp REPL directly in the sidebar panel, so you can evaluate expressions while keeping your editor visible.

• Same functionality as the REPL tab: input prompt, multi-line support, history, forms, and tables.
• Useful for quick calculations, querying data, or running scripts without leaving your document.
• The sidebar REPL shares the same interpreter instance as the REPL tab — definitions and database state are shared.

EELisp Code Blocks in Markdown

Embed executable EELisp code directly in your Markdown files using fenced code blocks:

```eelisp
(+ 1 2 3)
```

Running a code block

1. Place your cursor anywhere inside a ```eelisp block.
2. Press ⌘⇧Return (or use the menu: View → Run EELisp Block).
3. The result appears as a ```result block immediately below.

```eelisp
(+ 1 2 3)
```
```result
6
```

Re-running replaces the existing result. Use cases include inline calculations, adding agenda items from journal entries, querying data, and file operations:

```eelisp
(add-item (smart-parse "tomorrow review quarterly report !!"))
```

```eelisp
(write-file "todo.txt" "Buy groceries\nCall dentist")
```

10. Keyboard Shortcuts

Press ⌘? in the app to see the full shortcut sheet. Here is the complete reference:

Files

Navigation

Tabs

Editing

View & Export

11. Using the REPL

EEditor includes a built-in Lisp interpreter called EELisp — designed for personal data management, calculations, and scripting.

Opening the REPL

• Press ⌘⇧L, or tap the terminal icon in the actions bar.
• The REPL opens as a tab alongside your file tabs.
• Right-click the REPL tab to Pin it (persists across sessions).

Evaluating expressions

• Type an expression at the > prompt and press Enter.
• Multi-line input — if parentheses are unbalanced, the prompt changes to .. and waits for more. Press Escape or the × button to cancel.
• History — press Up/Down arrow to navigate previous commands.
• Select & copy — output text is selectable. Right-click → Copy All Output.

Send to REPL (⌘R)

Select text in the editor and press ⌘R. The REPL opens with your selection pre-filled in the input field, ready for you to press Enter to evaluate.

Loading files

Use :load path/to/file.el to load and evaluate an EELisp script. On iOS, tap the Load button in the toolbar or right-click a .el file in the sidebar.

iOS toolbar

On iOS/iPadOS, a toolbar appears with: history navigation (↑/↓), quick snippets (query, deftable, defn), Load File, and Clear.

12. REPL Commands

Colon-prefixed commands control the REPL itself (not EELisp expressions):

13. Arithmetic & Math

All arithmetic operators are variadic (accept multiple arguments) and work with integers and floats.

;; Arithmetic examples
(+ 1 2 3 4)            ; → 10
(* 6 7)                ; → 42
(/ 100 3)              ; → 33.333...
(pow 2 10)             ; → 1024
(round 3.14159 2)     ; → 3.14

;; Nesting
(+ (* 3 4) (- 10 5))    ; → 17

14. Comparison & Logic

Logical operators

These are special forms (short-circuit evaluation):

(and true false)        ; → false
(or  false true)        ; → true
(not true)              ; → false

;; Short-circuit: (or) returns first truthy value
(or nil false 42 99)    ; → 42

15. Variables & Functions

Defining variables

(def x 42)
(def greeting "Hello, world!")
(def pi 3.14159)

Defining functions

(defn square (x)
  (* x x))

(square 5)  ; → 25

;; Multi-expression body (last value returned)
(defn greet (name)
  (def msg (str "Hello, " name "!"))
  (println msg)
  msg)

Anonymous functions

(map (fn (x) (* x x)) '(1 2 3))  ; → (1 4 9)

Rest parameters

(defn sum (first . rest)
  (reduce + first rest))

(sum 1 2 3 4 5)  ; → 15

Local bindings

(let ((x 1) (y 2))
  (+ x y))  ; → 3

16. Control Flow

if

(if (> x 0) "positive" "non-positive")

cond

(cond
  (< x 0)  "negative"
  (= x 0)  "zero"
  else     "positive")

when

;; Execute body only if condition is true
(when (> x 0)
  (println "positive!")
  x)

loop / recur

;; Sum from 0 to 10
(loop ((i 0) (acc 0))
  (> i 10)
  (recur (+ i 1) (+ acc i)))  ; → 55

begin

;; Evaluate multiple expressions, return last
(begin
  (def a 10)
  (def b 20)
  (+ a b))  ; → 30

17. Strings

18. Lists

;; Chaining list operations
(def nums (range 1 11))
(filter even? nums)            ; → (2 4 6 8 10)
(map (fn (x) (* x x))
     (filter even? nums))       ; → (4 16 36 64 100)
(reduce + 0 (range 1 101))   ; → 5050

19. Dictionaries

Dictionaries use keyword keys (:name) and are immutable — operations return new dicts.

(def person {:name "Alice" :age 30})
(dict-get person :name)          ; → "Alice"
(dict-set person :age 31)        ; → {:name "Alice" :age 31}
(dict-merge person {:city "NYC"}) ; → {:name "Alice" :age 30 :city "NYC"}

20. Types & Conversion

Type predicates

Type inspection

(type 42)          ; → "number"
(type "hello")     ; → "string"
(type '(1 2))      ; → "list"

Conversion functions

21. I/O & Dates

Output

Date functions

(today)                              ; → "2026-02-23"
(date-add (today) 7 :days)          ; → "2026-03-02"
(date-add "2026-01-31" 1 :months)   ; → "2026-02-28"
(date-diff "2026-01-01" "2026-12-31") ; → 364

22. Prelude Functions

These functions are defined in EELisp itself and loaded automatically at startup:

23. HTTP & JSON

;; Fetch data from an API
(def resp (http-get "https://api.example.com/data"))
(def data (json-parse (dict-get resp :body)))

;; Post JSON
(http-post "https://api.example.com/items"
  (json-stringify {:name "test"})
  :content-type "application/json")

Evaluation

File System

EELisp can read and write files in your open folder. All paths are relative to the current workspace directory.

;; Read a file
(def content (read-file "notes.md"))

;; Write results to a file
(write-file "output.txt" (str "Report: " (today)))

;; Append to a log
(append-file "log.txt" (str (today) " - Done\n"))

;; List workspace files
(list-files)       ; → ("README.md" "notes.md" ...)
(list-files "src") ; → ("main.el" "utils.el" ...)

Editor Integration

These builtins let EELisp code interact with the active editor buffer.

;; Insert text at the cursor
(insert-at (cursor-pos) (str "Updated: " (today)))

;; Get what's selected
(def sel (selection))

;; Read the entire buffer
(def text (buffer-text))
(println (str "Length: " (str-len text)))

Clipboard

;; Copy a result to clipboard
(clipboard-set (str "Total: $" (reduce + 0 '(10 20 30))))

;; Paste and process clipboard contents
(str-upper (clipboard-get))

24. Defining Tables

EELisp includes a built-in SQLite database engine. Tables are defined with typed schemas.

Basic syntax

(deftable contacts (name:string email:string age:number))

Field types

Table management

;; Full example
(deftable tasks (title:string priority:number done:bool due:date))
(tables)       ; → (tasks)
(describe tasks) ; → schema details

25. Records & Queries

Inserting records

(insert tasks {:title "Write docs" :priority 1 :done false})
(insert tasks {:title "Fix bug" :priority 2 :done false :due "2026-03-01"})

Querying

;; All records
(query tasks)

;; With WHERE clause
(query tasks :where "priority <= ?" :params (list 2))

;; Sorted and limited
(query tasks :order "priority" :limit 5)

;; Select specific columns
(query tasks :select "title, done")

;; Descending order
(query tasks :order "priority" :asc false)

Updating & deleting

;; Update by ID
(update tasks 1 {:done true})

;; Soft-delete (dBASE-style, can be recovered)
(delete tasks 1)

;; Permanently remove soft-deleted records
(pack tasks)

;; Count records
(count-records tasks)
(count-records tasks :where "done = ?" :params (list false))

Record access

;; Working with query results programmatically
(def results (query tasks :where "done = ?" :params (list false)))
(def recs (records results))
(map (fn (r) (field-get r :title)) recs)  ; → ("Write docs" "Fix bug")

26. Interactive Views

EELisp can render interactive UI components directly in the REPL output.

Browse (table view)

;; Browse all records in a scrollable grid
(browse tasks)

;; With filters and sorting
(browse tasks :where "done = ?" :params (list false) :order "priority")

Edit (CRUD form)

;; Open an interactive form for create/read/update/delete
(edit tasks)

;; With filters
(edit tasks :where "priority = ?" :params (list 1))

The form shows one record at a time with Prev/Next navigation, inline editing, Save, New, and Delete buttons.

Computed forms (defform)

;; Standalone calculator form with computed fields
(defform loan-calc
  (principal:number rate:number years:number)
  :computed (
    (monthly-payment
      (let ((r (/ rate 1200))
            (n (* years 12)))
        (round (/ (* principal r (pow (+ 1 r) n))
                  (- (pow (+ 1 r) n) 1)) 2)))
    (total-paid
      (round (* monthly-payment (* years 12)) 2))))

Computed fields update automatically when input fields change.

Choice fields (dropdown)

Use the (name:choice "opt1" "opt2" ...) syntax to create a dropdown picker:

(defform new-task
  (title:string
   (priority:choice "low" "medium" "high" "urgent")
   (status:choice "todo" "in-progress" "done")
   notes:memo))

Choice fields render as a dropdown menu in the form UI.

Table-backed forms (:source)

Link a form to an existing database table with :source to enable full CRUD:

;; Create a table first
(deftable projects (name:string status:string budget:number))
(insert projects {:name "Alpha" :status "active" :budget 50000})

;; Form backed by the table with dropdown for status
(defform project-editor
  (name:string
   (status:choice "planning" "active" "completed")
   budget:number)
  :source projects)

The form loads records from the source table with Prev/Next navigation, Save, New, and Delete buttons — like (edit table) but with custom field types.

27. Database Management

Automatic connection

• When you open a folder containing eelisp.db, the REPL auto-connects to it.
• If no database file exists, the REPL uses an in-memory database.

REPL database commands

28. Items

The agenda system is a Lotus Agenda-inspired personal information manager. Items are free-form text entries with optional metadata.

Adding items

(add-item "Finish quarterly report")

;; With metadata
(add-item "Call dentist" :when "2026-03-01" :priority 2)
(add-item "Buy groceries" :category "personal" :notes "milk, eggs")

;; Add with today's date
(add-item-today "Review pull requests" :priority 1)

Querying items

(items)                          ; all items (table view)
(items :category "work")        ; filter by category
(items :search "quarterly")     ; text search
(items :priority 1)             ; filter by priority
(items :when-before "2026-03-01") ; due before date

Managing items

29. Categories

Categories are hierarchical (use / separators) and optionally exclusive (item can be in only one child).

;; Hierarchical categories
(defcategory work)
(defcategory work/projects)
(defcategory work/meetings)
(defcategory personal)
(defcategory personal/errands)

;; Exclusive: item can only be in one child
(defcategory priority :exclusive true
  :children (high medium low))

;; Assign / unassign
(assign 1 "work/projects")
(assign 1 "priority/high")
(unassign 1 "personal")

;; View category tree
(categories)

30. Auto-Categorization Rules

Rules automatically categorize items based on their content — the signature feature of Lotus Agenda.

;; Text-matching rules
(defrule urgent-flag
  :when (str-contains text "URGENT")
  :assign "priority/high")

(defrule meeting-detect
  :when (or (str-contains text "meeting")
            (str-contains text "call with"))
  :assign "work/meetings")

;; Regex with date extraction
(defrule date-extract
  :when (str-matches text "\\b(\\d{4}-\\d{2}-\\d{2})\\b")
  :action (item-set id :when (match 1)))

;; Apply rules
(apply-rules)      ; batch-apply to all items
(apply-rules 42)   ; apply to item #42

;; Auto-apply on every add-item
(auto-categorize true)

Rule management

31. Views

Views are saved queries that filter, sort, and group items dynamically.

(defview work-board
  :source items
  :filter (has-category "work")
  :group-by category
  :sort-by when)

(defview urgent
  :source items
  :filter (= priority "1")
  :sort-by when)

(defview inbox
  :source items
  :filter (= (length categories) 0))

;; Show a view
(show work-board)
(show urgent)

32. Calendar Queries

;; Items for a specific date
(items-on "2026-02-24")

;; Items in a date range
(items-between "2026-02-24" "2026-02-28")

;; Using date helpers
(items-on (today))
(items-between (today) (date-add (today) 7 :days))

33. Smart Input

The add command parses natural language to extract dates, priorities, and people automatically.

(add "Meet Alice tomorrow for coffee !!")
; → :when = tomorrow, :priority 2, :who "Alice"

(add "Call Bob next Monday about the project")
; → :when = next Monday, :who "Bob"

(add "URGENT fix server crash")
; → :priority 1

;; Preview without creating
(smart-parse "email Sarah March 15 about renewal !!")
; → {:text "email Sarah about renewal" :when "2026-03-15" :priority 2 :who ("Sarah")}

Recognized patterns

• Dates: ISO dates, tomorrow/today/yesterday, next Monday, this weekend, in 3 days, end of week/month, March 15
• Priority: URGENT/ASAP, !!!/!!/!, high/low priority
• People: @name, with/for/from Name, call/email/meet Name

34. Recurring Items & Templates

Recurrence

;; Built-in intervals
(add-item "Team standup" :when (today) :recur :daily)
(add-item "Weekly review" :when (today) :recur :weekly)
(add-item "Monthly report" :when (today) :recur :monthly)

;; Custom interval
(add-item "Check filters" :when (today) :recur (every 3 :months))

;; When you mark done, the next occurrence is auto-created
(item-done 1)  ; creates next recurrence automatically

Templates

;; Define a reusable item blueprint
(deftemplate weekly-review
  :text "Weekly review"
  :category "work"
  :priority 2
  :recur :weekly)

;; Create from template with overrides
(from-template weekly-review :when "2026-03-01")

;; Manage templates
(templates)           ; list all
(drop-template weekly-review)  ; delete

35. Multiple Agendas

Open, switch between, and manage multiple agenda databases. Useful for separating work and personal agendas.

;; Open a new agenda
(open-agenda "work.db")
(open-agenda "personal.db")

;; Switch between agendas
(use-agenda "work")

;; List all open agendas
(agendas)  ; shows active marker (*)

;; Close an agenda
(close-agenda "personal")

Export & Import

;; Export for backup or migration
(export-agenda "work" :format :json :path "work-backup.json")

;; Import from a previous export
(import-agenda "work-backup.json")

36. GUI & EELisp Integration

The EEditor GUI integrates with EELisp through the interpreter’s eval() method. All data flows through EELisp expressions — the GUI never accesses SQLite directly.

Architecture

┌─────────────────────────┐
│  SwiftUI Views          │
│  (Sidebar, Calendar,    │
│   Agenda, REPL)         │
├─────────────────────────┤
│  ViewModels             │
│  (call interpreter.eval)│
├─────────────────────────┤
│  EELisp Interpreter     │
│  (builtins, prelude)    │
├─────────────────────────┤
│  SQLite Database        │
│  (eelisp.db)            │
└─────────────────────────┘

How it works

• REPL — user types expressions directly, results are rendered as text, tables, or forms.
• Agenda Sidebar — calls (items), (items-on), (items-between) to load items for display.
• Calendar — calls (items-between start end) to count agenda items per day.
• Interactive forms — browse and edit return .tableView / .formView values that the REPL renders as SwiftUI components.

Data flow example

;; 1. User adds items in the REPL
(add-item "Review PRs" :when (today) :priority 1)

;; 2. Switch to Agenda sidebar → GUI calls:
;;    interpreter.eval("(items-between startKey endKey)")
;;    Parses results into AgendaDisplayItem structs

;; 3. Switch to Calendar → GUI calls:
;;    interpreter.eval("(items-on \"2026-02-23\")")
;;    Counts items per day for dot indicators

iOS & iPadOS tips

• Actions bar — a horizontal toolbar above the editor provides one-tap access to Timestamp, Find, Daily, Weekly, Search, Quick Open, Preview, PDF, REPL, and Shortcuts.
• REPL toolbar — history navigation, quick snippets, Load File, and Clear.
• External keyboard — all ⌘ shortcuts work with a hardware keyboard on iPad.
• Context menus — long-press on files or tabs for rename, delete, pin, and other actions.
• Split View — EEditor works in iPadOS Split View and Slide Over.