luis/ob-elixir
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
ob-elixir/docs/04-elixir-integration-strategies.md

645 lines
19 KiB
Markdown
Raw Permalink Blame History

# 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)
Reference in New Issue View Git Blame Copy Permalink