Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/mbhutton/emacsopen

Share files and links to daemon mode Emacs on macOS easily 🦄
https://github.com/mbhutton/emacsopen

emacs emacsclient

Last synced: 3 months ago
JSON representation

Share files and links to daemon mode Emacs on macOS easily 🦄

Awesome Lists containing this project

README 

        
#+title: EmacsOpen.app (Pre-Alpha, not ready for use)

* Main idea

Act as a share target for opening things in daemon mode Emacs, providing more macOS app-like behaviour:

- ensure the Emacs daemon is running

- ensure an Emacs frame is open

- open the given thing in Emacs

- raise the Emacs frame to the front



Handles files, web links, web page selection (Safari), and =org-protocol://= links.



Targeting macOS Emacs formulas which run in daemon mode via =brew service= communicating via =emacsclient=, initially [[https://github.com/d12frosted/homebrew-emacs-plus][Emacs Plus]].

* Why?

- To make opening things in Emacs and opening Emacs itself "Just Work", without having to think about what state Emacs is currently in, and without having to always leave an Emacs frame open.

- To be able to open more things in Emacs than is supported natively, including web links (for org-capture) and =org-protocol://= links, to support easier sharing from other apps to Emacs.

- To achieve the above in a single tool with minimal configuration.

* Status: Just starting

- Some initial skeleton code.

- Most of the CLI variants implemented, without daemon management.

- Expect frequent history rewrites.

- See roadmap below for rough plan.

- Not ready for public use.

* CLI command =emacsopen= structure

- Syntax: =emacsopen [OPTIONS] [FILE...]=

  - =OPTIONS: [--tty/-t] | [--eval/-e] | [--block/-b] [--create-frame/-c]=

    - =--tty/-t= Use Emacs in terminal mode.

    - =--eval/-e= Evaluate Emacs Lisp commands.

    - =--block/-b= Block (wait) until Emacs has finished handling the given file or link. Default is to not wait.

    - =--create-frame/-c= Always create a new frame rather than the default of reusing an existing one.

    - The =--tty/-t= and =--eval/-e= options are mutually exclusive, and incompatible with =--block/-b= and =--create-frame/-c=.

  - =FILE...= A set of files or an org-protocol link to open in Emacs.

- Examples:

  - To activate an Emacs frame, preferring to reuse an one:

    - =emacsopen=

  - To open a file or org-protocol link in the GUI:

    - =emacsopen file.org=

    - =emacsopen org-protocol://...=

  - To open a file in the terminal:

    - =emacsopen --tty README.org=

  - To just ensure that the Emacs daemon is ready for commands:

    - =emacsopen --eval nil=

- To just ensure that emacsclient is ready: =emacsopen --eval nil=

* Roadmap

- [ ] Address potential roadblocks to see if viable at all

  - [ ] Can an unsigned macOS app invoke =emacsclient= to connect to Emacs when running?

    - Potential issues with permissions, and environment variables. Fails within Shortcuts.app.

  - [ ] Can an unsigned macOS app start and stop a brew service? Potential permissions issues.

- [ ] Skeleton app

  - [ ] Use icon from [[https://github.com/emacsfodder/emacs-icons-project][emacsfodder/emacs-icons-project]]

  - [X] Skeleton =emacsopen= command

  - [ ] XCode project for app, using CLI/library as internal dependency

- [ ] Read config (see also 'Auto detection' below)

  - [ ] Location of =emacsclient=

    - Can rely on PATH for the terminal case.

  - [ ] Name of brew service to use for starting Emacs daemon

  - [ ] =org-protocol://= scheme config

    - Follow the most popular convention by default.

- [ ] Handle opening files via drag and drop and opening via Finder (with frame already open)

- [ ] Handle =org-protocol://= links (with frame already open)

  - [ ] To open an existing Org node by its Org ID

  - [ ] To capture a web page, with url, title, and optional selected text

  - [ ] To trigger =org-capture=, eg to add an inbox item

- [X] Always activate Emacs top window

- [X] Open frame if necessary

- [ ] Start daemon if necessary, waiting until ready for =emacsclient= commands

- [ ] =open -a EmacsOpen= should open Emacs, creating a frame if necessary, and activate Emacs

- [ ] Ensure useful for emacs restart

  - Eg support ~brew services stop emacs-plus@30; doom sync; emacsopen activate-frame~

- [ ] Act as a share target to invoke the command org-protocol convention of url, title, and text.

- [ ] Act as a Safari extension with support for sharing current page (including text selection) via =org-protocol=, including keyboard shortcut support

- [X] Add =eval= support (using =emacsclient -e=)

- Add a Homebrew formula, including shell completions

- [X] Support in-terminal case: =emacsclient --tty=

- [X] Shell autocompletion of CLI arguments using [[https://github.com/apple/swift-argument-parser][apple/swift-argument-parser]]

- [ ] Docs (expand this README)

- [ ] Tests

- [ ] CI (build, test, dependabot checks)

- [ ] Show visual feedback when getting Emacs ready (eg a HUD spinner) when taking too long (GUI case only)

- [ ] Companion project on iOS to route =org-protocol://= links to chosen iOS apps with their own URL schemes, such as =beorg://=

* Potential scope

** Auto detection instead of relying on config

- Auto-detect Emacs brew service name if not configured, eg using ~brew services list --json~

- Auto-detect emacsclient path if not configured if at =/opt/homebrew/bin/emacsclient=

** Limited Shortcuts.app support

Currently Shortcuts.app can't use =emacsclient= in Emacs Plus due to socket/env related issues.

Support some way of opening a file or link via EmacsOpen either via CLI or a Siri Shortcut action.

* Out of scope

- No GUI

  - All user interactions should be via a share action, or the =emacsopen= CLI command.

  - All configuration should be a text file, probably TOML format.

  - All responses should be via stdout (CLI), macOS error notification/alert, and maybe logging.

- No AppleScript support

  - Use Emacs lisp instead: ~emacsopen -e COMMAND~

* Background

This started as a discussion on an [[https://github.com/d12frosted/homebrew-emacs-plus/pull/783][Emacs Plus PR]] thread.