docs and tasks

2026-01-24 13:44:20 +01:00
commit 3ca9c10678
16 changed files with 6704 additions and 0 deletions
--- a/docs/04-elixir-integration-strategies.md
+++ b/docs/04-elixir-integration-strategies.md
@@ -0,0 +1,644 @@
+# Elixir Integration Strategies
+
+This document covers strategies for integrating Elixir with Emacs and org-babel, including execution modes, data conversion, and Mix project support.
+
+## Table of Contents
+
+- [Execution Modes](#execution-modes)
+- [One-Shot Execution](#one-shot-execution)
+- [IEx Session Management](#iex-session-management)
+- [Mix Project Context](#mix-project-context)
+- [Remote Shell (remsh)](#remote-shell-remsh)
+- [Data Type Conversion](#data-type-conversion)
+- [Error Handling](#error-handling)
+- [elixir-mode Integration](#elixir-mode-integration)
+- [Performance Considerations](#performance-considerations)
+- [References](#references)
+
+---
+
+## Execution Modes
+
+### Overview of Execution Strategies
+
+| Mode         | Command           | Use Case       | Startup Time | State       |
+|--------------|-------------------|----------------|--------------|-------------|
+| One-shot     | `elixir -e`       | Simple scripts | ~500ms       | None        |
+| Script file  | `elixir file.exs` | Larger code    | ~500ms       | None        |
+| IEx session  | `iex`             | Interactive    | Once         | Persistent  |
+| Mix context  | `iex -S mix`      | Projects       | Slower       | Project     |
+| Remote shell | `iex --remsh`     | Production     | Fast         | Remote node |
+
+### Recommended Approach
+
+For org-babel, we recommend:
+
+1. **Default**: Script file execution (reliable, predictable)
+2. **With `:session`**: IEx via comint (persistent state)
+3. **With `:mix-project`**: Mix context execution
+
+---
+
+## One-Shot Execution
+
+### Using `elixir -e`
+
+For simple, single expressions:
+
+```elisp
+(defun ob-elixir--eval-simple (code)
+  "Evaluate CODE using elixir -e."
+  (shell-command-to-string
+   (format "elixir -e %s"
+           (shell-quote-argument code))))
+```
+
+**Pros**: Simple, no temp files
+**Cons**: Limited code size, quoting issues
+
+### Using Script Files (Recommended)
+
+More robust for complex code:
+
+```elisp
+(defun ob-elixir--eval-script (code)
+  "Evaluate CODE using a temporary script file."
+  (let ((script-file (org-babel-temp-file "elixir-" ".exs")))
+    (with-temp-file script-file
+      (insert code))
+    (org-babel-eval
+     (format "elixir %s" (org-babel-process-file-name script-file))
+     "")))
+```
+
+### Capturing Return Values vs Output
+
+```elisp
+;; For :results output - capture stdout
+(defun ob-elixir--eval-output (code)
+  "Execute CODE and capture stdout."
+  (ob-elixir--eval-script code))
+
+;; For :results value - wrap to capture return value
+(defconst ob-elixir--value-wrapper
+  "
+_result_ = (
+%s
+)
+IO.puts(inspect(_result_, limit: :infinity, printable_limit: :infinity, charlists: :as_lists))
+"
+  "Wrapper to capture the return value of code.")
+
+(defun ob-elixir--eval-value (code)
+  "Execute CODE and return its value."
+  (let ((wrapped (format ob-elixir--value-wrapper code)))
+    (string-trim (ob-elixir--eval-script wrapped))))
+```
+
+### Handling Multiline Output
+
+```elisp
+(defconst ob-elixir--value-wrapper-with-marker
+  "
+_result_ = (
+%s
+)
+IO.puts(\"__OB_ELIXIR_RESULT_START__\")
+IO.puts(inspect(_result_, limit: :infinity, printable_limit: :infinity))
+IO.puts(\"__OB_ELIXIR_RESULT_END__\")
+"
+  "Wrapper with markers for reliable output parsing.")
+
+(defun ob-elixir--extract-result (output)
+  "Extract result from OUTPUT between markers."
+  (when (string-match "__OB_ELIXIR_RESULT_START__\n\\(.*\\)\n__OB_ELIXIR_RESULT_END__"
+                      output)
+    (match-string 1 output)))
+```
+
+---
+
+## IEx Session Management
+
+### Starting an IEx Session
+
+```elisp
+(defvar ob-elixir-iex-buffer-name "*ob-elixir-iex*"
+  "Buffer name for the IEx process.")
+
+(defvar ob-elixir-prompt-regexp "^iex\\([0-9]+\\)> "
+  "Regexp matching the IEx prompt.")
+
+(defvar ob-elixir-continued-prompt-regexp "^\\.\\.\\.\\([0-9]+\\)> "
+  "Regexp matching the IEx continuation prompt.")
+
+(defun ob-elixir--start-iex-session (session-name &optional params)
+  "Start an IEx session named SESSION-NAME."
+  (let* ((buffer-name (format "*ob-elixir-%s*" session-name))
+         (buffer (get-buffer-create buffer-name))
+         (mix-project (when params (cdr (assq :mix-project params))))
+         (iex-args (when params (cdr (assq :iex-args params)))))
+
+    (unless (comint-check-proc buffer)
+      (with-current-buffer buffer
+        ;; Set up environment
+        (setenv "TERM" "dumb")
+        (setenv "IEX_WITH_WERL" nil)
+
+        ;; Start the process
+        (apply #'make-comint-in-buffer
+               (format "ob-elixir-%s" session-name)
+               buffer
+               "iex"
+               nil
+               (append
+                (when mix-project
+                  (list "-S" "mix"))
+                (when iex-args
+                  (split-string iex-args))))
+
+        ;; Wait for initial prompt
+        (ob-elixir--wait-for-prompt buffer 10)
+
+        ;; Configure IEx for programmatic use
+        (ob-elixir--configure-iex-session buffer)))
+    buffer))
+```
+
+### Configuring IEx for Non-Interactive Use
+
+```elisp
+(defun ob-elixir--configure-iex-session (buffer)
+  "Configure IEx in BUFFER for non-interactive use."
+  (with-current-buffer buffer
+    (let ((config-commands
+           '("IEx.configure(colors: [enabled: false])"
+             "IEx.configure(inspect: [limit: :infinity, printable_limit: :infinity])"
+             "Application.put_env(:elixir, :ansi_enabled, false)")))
+      (dolist (cmd config-commands)
+        (ob-elixir--send-to-iex buffer cmd)
+        (ob-elixir--wait-for-prompt buffer 5)))))
+```
+
+### Sending Code to IEx
+
+```elisp
+(defvar ob-elixir-eoe-marker "__OB_ELIXIR_EOE__"
+  "End-of-evaluation marker.")
+
+(defun ob-elixir--send-to-iex (buffer code)
+  "Send CODE to IEx process in BUFFER."
+  (with-current-buffer buffer
+    (goto-char (point-max))
+    (insert code)
+    (comint-send-input nil t)))
+
+(defun ob-elixir--eval-in-session (session code)
+  "Evaluate CODE in SESSION, return output."
+  (let* ((buffer (ob-elixir--get-or-create-session session))
+         (start-marker nil))
+    (with-current-buffer buffer
+      (goto-char (point-max))
+      (setq start-marker (point-marker))
+
+      ;; Send the code
+      (ob-elixir--send-to-iex buffer code)
+      (ob-elixir--wait-for-prompt buffer 30)
+
+      ;; Send EOE marker to clearly delineate output
+      (ob-elixir--send-to-iex buffer (format "\"%s\"" ob-elixir-eoe-marker))
+      (ob-elixir--wait-for-prompt buffer 5)
+
+      ;; Extract output
+      (ob-elixir--extract-session-output buffer start-marker))))
+
+(defun ob-elixir--wait-for-prompt (buffer timeout)
+  "Wait for IEx prompt in BUFFER with TIMEOUT seconds."
+  (with-current-buffer buffer
+    (let ((end-time (+ (float-time) timeout)))
+      (while (and (< (float-time) end-time)
+                  (not (ob-elixir--at-prompt-p)))
+        (accept-process-output (get-buffer-process buffer) 0.1)
+        (goto-char (point-max))))))
+
+(defun ob-elixir--at-prompt-p ()
+  "Return t if point is at an IEx prompt."
+  (save-excursion
+    (beginning-of-line)
+    (looking-at ob-elixir-prompt-regexp)))
+```
+
+### Cleaning Session Output
+
+```elisp
+(defun ob-elixir--clean-iex-output (output)
+  "Clean OUTPUT from IEx session."
+  (let ((cleaned output))
+    ;; Remove ANSI escape codes
+    (setq cleaned (ansi-color-filter-apply cleaned))
+    ;; Remove prompts
+    (setq cleaned (replace-regexp-in-string
+                   "^iex([0-9]+)> " "" cleaned))
+    (setq cleaned (replace-regexp-in-string
+                   "^\\.\\.\\.([0-9]+)> " "" cleaned))
+    ;; Remove EOE marker
+    (setq cleaned (replace-regexp-in-string
+                   (regexp-quote (format "\"%s\"" ob-elixir-eoe-marker))
+                   "" cleaned))
+    ;; Remove trailing whitespace
+    (string-trim cleaned)))
+```
+
+---
+
+## Mix Project Context
+
+### Detecting Mix Projects
+
+```elisp
+(defun ob-elixir--find-mix-project (dir)
+  "Find mix.exs file starting from DIR, searching up."
+  (let ((mix-file (locate-dominating-file dir "mix.exs")))
+    (when mix-file
+      (file-name-directory mix-file))))
+
+(defun ob-elixir--in-mix-project-p ()
+  "Return t if current buffer is in a Mix project."
+  (ob-elixir--find-mix-project default-directory))
+```
+
+### Executing in Mix Context
+
+```elisp
+(defun ob-elixir--eval-with-mix (code project-dir &optional mix-env)
+  "Evaluate CODE in the context of Mix project at PROJECT-DIR."
+  (let* ((default-directory project-dir)
+         (script-file (org-babel-temp-file "elixir-" ".exs"))
+         (env-vars (when mix-env
+                     (format "MIX_ENV=%s " mix-env))))
+    (with-temp-file script-file
+      (insert code))
+    (shell-command-to-string
+     (format "%smix run %s"
+             (or env-vars "")
+             (org-babel-process-file-name script-file)))))
+```
+
+### Compiling Before Execution
+
+```elisp
+(defun ob-elixir--ensure-compiled (project-dir)
+  "Ensure Mix project at PROJECT-DIR is compiled."
+  (let ((default-directory project-dir))
+    (shell-command-to-string "mix compile --force-check")))
+
+(defun ob-elixir--eval-with-compilation (code project-dir)
+  "Compile and evaluate CODE in PROJECT-DIR."
+  (ob-elixir--ensure-compiled project-dir)
+  (ob-elixir--eval-with-mix code project-dir))
+```
+
+### Using Mix Aliases
+
+```elisp
+(defun ob-elixir--run-mix-task (task project-dir &optional args)
+  "Run Mix TASK in PROJECT-DIR with ARGS."
+  (let ((default-directory project-dir))
+    (shell-command-to-string
+     (format "mix %s %s" task (or args "")))))
+```
+
+---
+
+## Remote Shell (remsh)
+
+### Connecting to Running Nodes
+
+```elisp
+(defun ob-elixir--start-remsh-session (node-name &optional cookie sname)
+  "Connect to remote Elixir node NODE-NAME.
+
+COOKIE is the Erlang cookie (optional).
+SNAME is the short name for the local node."
+  (let* ((local-name (or sname (format "ob_elixir_%d" (random 10000))))
+         (buffer-name (format "*ob-elixir-remsh-%s*" node-name))
+         (buffer (get-buffer-create buffer-name))
+         (args (append
+                (list "--sname" local-name)
+                (when cookie (list "--cookie" cookie))
+                (list "--remsh" node-name))))
+
+    (unless (comint-check-proc buffer)
+      (with-current-buffer buffer
+        (apply #'make-comint-in-buffer
+               (format "ob-elixir-remsh-%s" node-name)
+               buffer
+               "iex"
+               nil
+               args)
+        (ob-elixir--wait-for-prompt buffer 30)
+        (ob-elixir--configure-iex-session buffer)))
+    buffer))
+```
+
+### Remote Evaluation
+
+```elisp
+(defun ob-elixir--eval-remote (code node-name &optional cookie)
+  "Evaluate CODE on remote NODE-NAME."
+  (let ((session (ob-elixir--start-remsh-session node-name cookie)))
+    (ob-elixir--eval-in-session session code)))
+```
+
+---
+
+## Data Type Conversion
+
+### Elisp to Elixir
+
+```elisp
+(defun ob-elixir--elisp-to-elixir (value)
+  "Convert Elisp VALUE to Elixir literal syntax."
+  (pcase value
+    ('nil "nil")
+    ('t "true")
+    ((pred numberp) (number-to-string value))
+    ((pred stringp) (ob-elixir--format-string value))
+    ((pred symbolp) (ob-elixir--format-atom value))
+    ((pred vectorp) (ob-elixir--format-tuple value))
+    ((pred listp)
+     (cond
+      ((ob-elixir--alist-p value) (ob-elixir--format-keyword-list value))
+      ((ob-elixir--plist-p value) (ob-elixir--format-map value))
+      (t (ob-elixir--format-list value))))
+    (_ (format "%S" value))))
+
+(defun ob-elixir--format-string (str)
+  "Format STR as Elixir string."
+  (format "\"%s\""
+          (replace-regexp-in-string
+           "\\\\" "\\\\\\\\"
+           (replace-regexp-in-string
+            "\"" "\\\\\""
+            (replace-regexp-in-string
+             "\n" "\\\\n"
+             str)))))
+
+(defun ob-elixir--format-atom (sym)
+  "Format symbol SYM as Elixir atom."
+  (let ((name (symbol-name sym)))
+    (if (string-match-p "^[a-z_][a-zA-Z0-9_]*[?!]?$" name)
+        (format ":%s" name)
+      (format ":\"%s\"" name))))
+
+(defun ob-elixir--format-list (lst)
+  "Format LST as Elixir list."
+  (format "[%s]"
+          (mapconcat #'ob-elixir--elisp-to-elixir lst ", ")))
+
+(defun ob-elixir--format-tuple (vec)
+  "Format vector VEC as Elixir tuple."
+  (format "{%s}"
+          (mapconcat #'ob-elixir--elisp-to-elixir (append vec nil) ", ")))
+
+(defun ob-elixir--format-keyword-list (alist)
+  "Format ALIST as Elixir keyword list."
+  (format "[%s]"
+          (mapconcat
+           (lambda (pair)
+             (format "%s: %s"
+                     (car pair)
+                     (ob-elixir--elisp-to-elixir (cdr pair))))
+           alist ", ")))
+
+(defun ob-elixir--format-map (plist)
+  "Format PLIST as Elixir map."
+  (let ((pairs '()))
+    (while plist
+      (push (format "%s => %s"
+                    (ob-elixir--elisp-to-elixir (car plist))
+                    (ob-elixir--elisp-to-elixir (cadr plist)))
+            pairs)
+      (setq plist (cddr plist)))
+    (format "%%{%s}" (mapconcat #'identity (nreverse pairs) ", "))))
+```
+
+### Elixir to Elisp
+
+```elisp
+(defun ob-elixir--parse-result (output)
+  "Parse Elixir OUTPUT into Elisp value."
+  (let ((trimmed (string-trim output)))
+    (cond
+     ;; nil
+     ((string= trimmed "nil") nil)
+
+     ;; Booleans
+     ((string= trimmed "true") t)
+     ((string= trimmed "false") nil)
+
+     ;; Numbers
+     ((string-match-p "^-?[0-9]+$" trimmed)
+      (string-to-number trimmed))
+     ((string-match-p "^-?[0-9]+\\.[0-9]+\\(e[+-]?[0-9]+\\)?$" trimmed)
+      (string-to-number trimmed))
+
+     ;; Atoms (convert to symbols)
+     ((string-match "^:\\([a-zA-Z_][a-zA-Z0-9_]*\\)$" trimmed)
+      (intern (match-string 1 trimmed)))
+
+     ;; Strings
+     ((string-match "^\"\\(.*\\)\"$" trimmed)
+      (match-string 1 trimmed))
+
+     ;; Lists/tuples - use org-babel-script-escape
+     ((string-match-p "^\\[.*\\]$" trimmed)
+      (org-babel-script-escape trimmed))
+     ((string-match-p "^{.*}$" trimmed)
+      (org-babel-script-escape
+       (replace-regexp-in-string "^{\\(.*\\)}$" "[\\1]" trimmed)))
+
+     ;; Maps - convert to alist
+     ((string-match-p "^%{.*}$" trimmed)
+      (ob-elixir--parse-map trimmed))
+
+     ;; Default: return as string
+     (t trimmed))))
+
+(defun ob-elixir--parse-map (map-string)
+  "Parse Elixir MAP-STRING to alist."
+  ;; Simplified - for complex maps, use JSON encoding
+  (let ((content (substring map-string 2 -1))) ; Remove %{ and }
+    (mapcar
+     (lambda (pair)
+       (when (string-match "\\(.+?\\) => \\(.+\\)" pair)
+         (cons (ob-elixir--parse-result (match-string 1 pair))
+               (ob-elixir--parse-result (match-string 2 pair)))))
+     (split-string content ", "))))
+```
+
+### Using JSON for Complex Data
+
+For complex nested structures, JSON is more reliable:
+
+```elisp
+(defconst ob-elixir--json-wrapper
+  "
+_result_ = (
+%s
+)
+IO.puts(Jason.encode!(_result_))
+"
+  "Wrapper that outputs result as JSON.")
+
+(defun ob-elixir--eval-as-json (code)
+  "Evaluate CODE and parse result as JSON."
+  (let* ((wrapped (format ob-elixir--json-wrapper code))
+         (output (ob-elixir--eval-script wrapped)))
+    (json-read-from-string (string-trim output))))
+```
+
+---
+
+## Error Handling
+
+### Detecting Elixir Errors
+
+```elisp
+(defconst ob-elixir-error-patterns
+  '("^\\*\\* (\\(\\w+Error\\))"           ; ** (RuntimeError) ...
+    "^\\*\\* (\\(\\w+\\)) \\(.+\\)"        ; ** (exit) ...
+    "^\\(CompileError\\)"                   ; CompileError ...
+    "^\\(SyntaxError\\)")                   ; SyntaxError ...
+  "Patterns matching Elixir error output.")
+
+(defun ob-elixir--error-p (output)
+  "Return error info if OUTPUT contains an error, nil otherwise."
+  (catch 'found
+    (dolist (pattern ob-elixir-error-patterns)
+      (when (string-match pattern output)
+        (throw 'found (list :type (match-string 1 output)
+                            :message output))))))
+```
+
+### Signaling Errors to Org
+
+```elisp
+(define-error 'ob-elixir-error "Elixir evaluation error")
+(define-error 'ob-elixir-compile-error "Elixir compilation error" 'ob-elixir-error)
+(define-error 'ob-elixir-runtime-error "Elixir runtime error" 'ob-elixir-error)
+
+(defun ob-elixir--handle-error (output)
+  "Handle error in OUTPUT, signaling appropriate condition."
+  (when-let ((error-info (ob-elixir--error-p output)))
+    (let ((type (plist-get error-info :type))
+          (message (plist-get error-info :message)))
+      (cond
+       ((member type '("CompileError" "SyntaxError" "TokenMissingError"))
+        (signal 'ob-elixir-compile-error (list message)))
+       (t
+        (signal 'ob-elixir-runtime-error (list message)))))))
+```
+
+### Timeout Handling
+
+```elisp
+(defcustom ob-elixir-timeout 30
+  "Default timeout in seconds for Elixir evaluation."
+  :type 'integer
+  :group 'ob-elixir)
+
+(defun ob-elixir--eval-with-timeout (code timeout)
+  "Evaluate CODE with TIMEOUT seconds limit."
+  (with-timeout (timeout
+                 (error "Elixir evaluation timed out after %d seconds" timeout))
+    (ob-elixir--eval-script code)))
+```
+
+---
+
+## elixir-mode Integration
+
+### Syntax Highlighting
+
+```elisp
+;; Register with org-src for editing
+(add-to-list 'org-src-lang-modes '("elixir" . elixir))
+
+;; If elixir-mode isn't available, use a fallback
+(unless (fboundp 'elixir-mode)
+  (add-to-list 'org-src-lang-modes '("elixir" . prog)))
+```
+
+### Using elixir-mode Functions
+
+```elisp
+(defun ob-elixir--format-code (code)
+  "Format CODE using mix format if available."
+  (when (and (executable-find "mix")
+             (> (length code) 0))
+    (with-temp-buffer
+      (insert code)
+      (let ((temp-file (make-temp-file "elixir-format" nil ".ex")))
+        (unwind-protect
+            (progn
+              (write-region (point-min) (point-max) temp-file)
+              (when (= 0 (call-process "mix" nil nil nil
+                                       "format" temp-file))
+                (erase-buffer)
+                (insert-file-contents temp-file)
+                (buffer-string)))
+          (delete-file temp-file))))))
+```
+
+---
+
+## Performance Considerations
+
+### Caching Compilation
+
+```elisp
+(defvar ob-elixir--module-cache (make-hash-table :test 'equal)
+  "Cache of compiled Elixir modules.")
+
+(defun ob-elixir--get-cached-module (code)
+  "Get cached module for CODE, or compile and cache."
+  (let ((hash (md5 code)))
+    (or (gethash hash ob-elixir--module-cache)
+        (let ((module-name (format "ObElixir_%s" (substring hash 0 8))))
+          (ob-elixir--compile-module module-name code)
+          (puthash hash module-name ob-elixir--module-cache)
+          module-name))))
+```
+
+### Reusing Sessions
+
+```elisp
+(defcustom ob-elixir-reuse-sessions t
+  "Whether to reuse sessions between evaluations.
+When non-nil, sessions persist until explicitly killed."
+  :type 'boolean
+  :group 'ob-elixir)
+```
+
+### Startup Time Optimization
+
+```elisp
+;; Pre-start a session on package load (optional)
+(defun ob-elixir-warm-up ()
+  "Pre-start an IEx session for faster first evaluation."
+  (interactive)
+  (ob-elixir--start-iex-session "warmup"))
+```
+
+---
+
+## References
+
+- [Elixir Documentation](https://elixir-lang.org/docs.html)
+- [IEx Documentation](https://hexdocs.pm/iex/IEx.html)
+- [Mix Documentation](https://hexdocs.pm/mix/Mix.html)
+- [Erlang Distribution Protocol](https://www.erlang.org/doc/reference_manual/distributed.html)
+- [elixir-mode GitHub](https://github.com/elixir-editors/emacs-elixir)
+- [inf-elixir for REPL](https://github.com/J3RN/inf-elixir)
+- [Elixir LS (Language Server)](https://github.com/elixir-lsp/elixir-ls)