Metadata-Version: 2.1
Name: cacamacs
Version: 0.0.7
Summary: cacamacs — a small terminal text editor with Emacs key bindings
Home-page: https://github.com/stricaud/ccm
License: Unlicense
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console :: Curses
Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
Classifier: Programming Language :: C
Classifier: Topic :: Text Editors
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# ccm — cacamacs

A small terminal text editor with Emacs key bindings, built on the
[gtcaca](https://github.com/stricaud/gtcaca) libcaca TUI toolkit and its
`editor` widget. It shows off the widget's colourization, folding, annotations,
autocompletion, search/replace and a VSCode-style language-extension model.

```sh
ccm [file | directory] [language-configuration.json]
```

- A **file** opens in the editor.
- A **directory** opens the file browser (also `C-x d`).
- An optional explicit `language-configuration.json` forces that config.

It also has a **diagram mode** (`M-x diagram`): a drag-and-drop canvas for ASCII
diagrams. Pick a shape from the pane on the left — box, rounded, diamond,
circle, ellipse, cloud, cylinder, hexagon, actor or free text — drop it on the
canvas with the mouse or the keyboard, link any two by clicking one then the
other, rub out single characters with the eraser. Leaving drops the finished
art into your document at the cursor — plain characters, saved with `C-x C-s`
like anything else.

```
                         +-------+              .-----------.
     O                  /         \             |'---------'|
    /|\        +------>+   ok?     +----------->|   store   |
    / \   -----+        \         /             |           |
   user                  +-------+              '-----------'
```

See [docs/README-cacamacs.md](https://github.com/stricaud/ccm/blob/main/docs/README-cacamacs.md) for the full key-binding
reference and feature tour.

> **History.** ccm started life as `apps/cacamacs` inside the gtcaca repo, where
> a copy remains as a worked example of building an app on the toolkit. Active
> development now happens here, against gtcaca as an ordinary external
> dependency.

## Install with pip

Prebuilt binaries are published to PyPI for macOS (Apple Silicon), Linux
(x86_64) and Windows (x86_64) — no compiler or Homebrew needed:

```sh
pip install cacamacs
ccm            # or: cacamacs
```

PyPI is used purely as a binary channel (as `ruff`/`cmake`/`ninja` do): the
wheel carries the compiled `ccm` and the `libgtcaca`/`libcaca`/`oniguruma`
libraries it needs, made relocatable, plus the sample language extensions so
syntax highlighting works out of the box. See [packaging/](packaging/) for how
the per-platform wheels are built (`packaging/build.sh` → `packaging/wheel.py`,
wired up in `.github/workflows/release.yml`, which publishes on a `v*` tag).

## Building

ccm consumes gtcaca like any third party would: install gtcaca first, then
build ccm against it. gtcaca ships a `gtcaca.pc`, so pkg-config finds it.

```sh
# 1. install gtcaca (any one of these):
brew install stricaud/tap/gtcaca         # Homebrew tap
#   …or from a gtcaca checkout:  cmake -S . -B build && cmake --build build && sudo cmake --install build

# 2. build ccm
cmake -S . -B build
cmake --build build

# 3. run it
./run.sh              # builds if needed, then runs build/ccm
./run.sh path/to/file
```

Requirements: a C compiler, CMake ≥ 3.20, pkg-config, and an installed
`gtcaca` (which pulls in `libcaca`).

## Installing

```sh
sudo cmake --install build        # → /usr/local/bin/ccm, share/ccm/ccm-theme.example
```

### Self-contained macOS package

`scripts/package-macos.sh` builds a `.pkg` that bundles `libgtcaca` and
`libcaca` alongside `ccm` (rewritten to `@rpath`), so the installed editor needs
neither Homebrew nor a system gtcaca:

```sh
scripts/package-macos.sh          # → ccm-<version>.pkg
```

Its postinstall seeds `~/.ccm/theme` from the bundled sample (never clobbering
an existing one).

## Configuration

- **Colour theme** — copy [docs/ccm-theme.example](https://github.com/stricaud/ccm/blob/main/docs/ccm-theme.example) to
  `~/.ccm/theme`. Comments in the file explain every key.
- **Editor config** — copy [examples/config.json](https://github.com/stricaud/ccm/blob/main/examples/config.json) to
  `~/.cacamacs/config.json` for tab size, indent, per-language overrides.
- **Language extensions** — the VSCode-style grammar/config bundles under
  [examples/extensions/](https://github.com/stricaud/ccm/blob/main/examples/extensions/) drive syntax colourization.

## Layout

```
src/            editor sources (cacamacs.c, ui.c, edit.c, search.c, …)
                diagram.c / diagram_model.c — M-x diagram (mode / document)
docs/           feature docs + the colour-theme sample
examples/       config sample and language extensions
packaging/      cross-platform bundles + pip wheels (build.sh → wheel.py)
scripts/        macOS packaging
CMakeLists.txt  standalone build (finds gtcaca via pkg-config)
run.sh          build-and-run helper
```

## License

Released into the public domain under [the Unlicense](LICENSE) — do whatever you
want with it.
