lkn
/
orkmode
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
orkmode/README.md

272 lines
8.7 KiB
Markdown
Raw Permalink Blame History

# Orkmode
A standalone org-mode implementation for KDE, built with Rust (parser/core) and C++ (Qt UI).
## Project Structure
```
orkmode/
├── Cargo.toml # Workspace root
├── crates/
│ ├── org-ast/ # AST type definitions
│ │ └── src/
│ │ ├── lib.rs # Module exports
│ │ ├── document.rs # Document, settings
│ │ ├── headline.rs # Section, Headline, Planning
│ │ ├── elements.rs # Block elements (paragraph, list, table, etc.)
│ │ ├── objects.rs # Inline objects (markup, links, etc.)
│ │ ├── timestamp.rs # Timestamp types
│ │ └── span.rs # Source location tracking
│ ├── org-parser/ # Tree-sitter based parser
│ │ ├── build.rs # Compiles tree-sitter-org grammar
│ │ ├── tree-sitter-org/ # Git submodule: nvim-orgmode/tree-sitter-org
│ │ └── src/
│ │ ├── lib.rs # Parser API
│ │ ├── convert.rs # Tree-sitter → AST conversion
│ │ ├── ts.rs # Tree-sitter language bindings
│ │ └── error.rs # Error types
│ ├── ork-cli/ # Command-line interface (9P client)
│ │ └── src/
│ │ ├── main.rs # CLI commands (base + friendly verbs)
│ │ └── client.rs # 9P2000 client
│ └── ork-server/ # 9P server exposing org files
│ └── src/
│ ├── bin/ork-server.rs # Server entry point
│ ├── state.rs # Document state, section ops, ctl verbs
│ ├── namespace.rs # 9P namespace (docs, sections, agenda, query)
│ ├── p9.rs # 9P protocol handling
│ └── virtfs.rs # Virtual filesystem tree
└── ui/ # Qt6/QML GUI (9P client, no FFI)
├── CMakeLists.txt # Qt6 build (Core/Gui/Qml/Quick/Network)
├── src/
│ ├── main.cpp # Entry point; --addr, --selftest
│ ├── p9client.{h,cpp} # Minimal synchronous 9P2000 client
│ ├── orkclient.{h,cpp} # QML-facing façade over the 9P client
│ └── documentmodel.{h,cpp} # Lazy QAbstractItemModel section tree
└── qml/
├── Main.qml # Window, document sidebar, outline
└── OutlineView.qml # Folding TreeView with structural styling
```
## Features
### Supported Org Syntax
- [x] Headlines with nesting levels
- [x] TODO keywords (customizable via #+TODO:)
- [x] Priority cookies ([#A], [#B], [#C])
- [x] Tags
- [x] Property drawers
- [x] Planning lines (SCHEDULED, DEADLINE, CLOSED)
- [x] Timestamps (active, inactive, ranges, repeaters)
- [x] Paragraphs
- [x] Plain lists (unordered, ordered, checkboxes)
- [x] Source blocks
- [x] Tables
- [x] Drawers
- [x] Keywords/directives
- [x] Comments
- [x] LaTeX environments
- [ ] Inline markup (bold, italic, etc.) - AST types ready, parsing TODO
- [ ] Links - AST types ready, parsing TODO
- [ ] Footnotes
- [ ] Citations
### Document Settings
Parses common #+KEYWORD directives:
- TITLE, AUTHOR, EMAIL, DATE
- TODO, SEQ_TODO, TYP_TODO
- PROPERTY, STARTUP, OPTIONS
- FILETAGS, CATEGORY, ARCHIVE
## Building
### Prerequisites
- Rust 1.70+
- C compiler (for tree-sitter grammar)
- Qt 6.3+ and CMake 3.21+ (for the GUI)
### Build
```bash
# Build all crates
cargo build
# Run tests
cargo test
# Build release
cargo build --release
```
#### GUI
The GUI is a separate Qt6/CMake project that talks to `ork-server` over 9P.
```bash
cmake -S ui -B ui/build -DCMAKE_BUILD_TYPE=Release
cmake --build ui/build -j
# Run against a running ork-server (see below)
./ui/build/bin/orkmode -a unix:///tmp/ork.sock
```
## Usage
### Server
Start the 9P server to expose an org directory:
```bash
# Unix socket (preferred for local use)
ork-server -a unix:///tmp/ork.sock -d ~/org
# TCP socket
ork-server -a tcp://localhost:5640 -d ~/org
```
### CLI (ork)
`ork` is a 9P client that talks to `ork-server`. All org-mode intelligence lives in the server.
```bash
# Set the server address (or use -a on each call)
export ORK_ADDR=unix:///tmp/ork.sock
# Base 9P operations
ork ls / # List root namespace
ork read /idx # Read a file
ork write /work/task/keyword DONE # Write a value
# Friendly verbs (compositions of 9P ops)
ork docs # List documents (name + title)
ork sections work # Top-level sections in work.org
ork tree work # Full section outline
ork todos # All TODO items across docs
ork todos work # TODOs in work.org only
# Section details
ork get work my-task # Show section fields
ork set work my-task keyword DONE # Set a field
ork set work my-task tags work:urgent # Set tags (colon-separated)
# Create sections
ork mkdoc notes # Create notes.org
ork add work "* TODO New task :work:" # Add top-level section
ork add work "* Subtask" -p parent-id # Add child section
# TODO management
ork todo work my-task # Cycle to next state
ork todo work my-task DONE # Set explicit state
ork tag work my-task urgent # Add tag
ork tag work my-task urgent -r # Remove tag
# Structural operations
ork mv work my-task up # Reorder among siblings
ork promote work my-task # Decrease level
ork demote work my-task # Increase level
ork rm work my-task # Delete section and subtree
ork refile work my-task archive # Move to another doc
ork refile work my-task archive -p done # As child of 'done' section
ork archive work my-task # Move to work.org_archive
# Properties
ork prop work my-task CUSTOM_ID # Get property
ork prop work my-task EFFORT 2h # Set property
ork prop work my-task EFFORT -d # Delete property
# Agenda views
ork agenda todos # All TODOs
ork agenda today # Items scheduled/due today
ork agenda week # Next 7 days
# Query
ork query 'tag:work' # Match sections by tag
ork query 'tag:work+todo:TODO' # Compound query
ork query 'priority:A' # By priority
# Maintenance
ork reload # Rescan files from disk
ork lint # Validate all documents
ork lint work # Validate one document
```
Any 9P client works (e.g., plan9port `9p`):
```bash
9p -a 'unix!/tmp/ork.sock' ls /
9p -a 'unix!/tmp/ork.sock' read /idx
9p -a 'unix!/tmp/ork.sock' write /work/task/keyword DONE
```
## Architecture
### Parser Design
The parser uses [tree-sitter](https://tree-sitter.github.io/) with the
[nvim-orgmode/tree-sitter-org](https://github.com/nvim-orgmode/tree-sitter-org) grammar.
Benefits:
- **Incremental parsing**: Only re-parses changed regions
- **Error recovery**: Produces partial AST even with syntax errors
- **Performance**: O(n) parsing, minimal memory allocation
- **Battle-tested**: Used by Neovim's org-mode plugin
### AST Design
The AST follows the [org-element specification](https://orgmode.org/worg/dev/org-syntax.html):
- **Document**: Root node with settings and sections
- **Section**: Headline + content + children
- **Elements**: Block-level constructs (paragraphs, lists, blocks)
- **Objects**: Inline constructs (markup, links, timestamps)
All nodes include source span information for editor integration.
## Roadmap
### Phase 1: Parser ✓
- [x] Tree-sitter integration
- [x] Core AST types
- [x] Headline/section parsing
- [x] Block element parsing
- [ ] Complete inline object parsing
### Phase 2: 9P Server ✓
- [x] Document state with locking
- [x] Read/write section fields (keyword, priority, title, tags, timestamps, body)
- [x] Create documents and sections
- [x] Structural ops (delete, move, promote, demote, refile, archive)
- [x] Agenda views (todos, today, week)
- [x] Query interface (tag, todo, priority)
- [x] ctl verbs (reload, lint)
### Phase 3: Qt UI (Current)
- [x] Document rendering (read-only)
- [x] Structural styling (keywords, priorities, tags, timestamps)
- [x] Folding/cycling (TreeView)
- [x] Navigation
- [ ] Inline editing
- [ ] TODO state cycling (click to toggle)
- [ ] Tag/property editing
- [ ] Syntax highlighting for bodies
### Phase 4: Agenda
- [ ] Dedicated agenda view panel
- [ ] Day/week/month views
- [ ] Filtering and sorting
- [ ] Custom views
### Phase 5: Advanced Features
- [ ] Code block execution
- [ ] Diagram rendering (mermaid, plantuml)
- [ ] Capture templates
- [ ] Clock/time tracking
## License
GPL-3.0-or-later
Reference in New Issue View Git Blame Copy Permalink