Metadata-Version: 2.4
Name: pikslide
Version: 0.1.0
Summary: A text language for drawing diagrams as native, editable PowerPoint objects
Keywords: diagram,powerpoint,pptx,pic,pikchr,slides
Author: Miki Yutani
Author-email: Miki Yutani <mkyutani@gmail.com>
License-Expression: 0BSD
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Graphics :: Presentation
Requires-Dist: pillow>=12.3.0
Requires-Dist: python-pptx>=1.0.2
Requires-Python: >=3.12
Project-URL: Repository, https://github.com/mkyutani/pikslide
Project-URL: Issues, https://github.com/mkyutani/pikslide/issues
Project-URL: Documentation, https://github.com/mkyutani/pikslide/blob/main/src/pikslide/docs/spec.md
Description-Content-Type: text/markdown

# pikslide

A text language for drawing **diagrams that live inside Office slides**.

You don't write coordinates: you place objects one after another in a
direction, and refer to earlier objects by name. A diagram becomes
**native, editable PowerPoint objects** — shapes a person can select,
restyle and move afterwards.

The language is specified in [docs/spec.md](https://github.com/mkyutani/pikslide/blob/main/src/pikslide/docs/spec.md) and defined, in
BNF, in [docs/grammar.md](https://github.com/mkyutani/pikslide/blob/main/src/pikslide/docs/grammar.md). (pikslide's own design traces
back through two earlier languages; see Acknowledgments, below.)

## Status

v1 (docs/spec.md §1) is implemented: a parser, a layout stage, and
PowerPoint output; colors as a type of their own, with theme colors
(`theme "accent1"`, `lighter`/`darker`) rendered as real `schemeClr`,
never resolved to RGB; fonts the same way — text set in the theme's own
font by default, not a hard-coded family, with `major` selecting the
heading font and `typeface` overriding both with one literal family;
three fixed text sizes (`small`/`medium`/`large`); a prelude of built-in
names (CSS color names, built-in defaults, the theme-color names); preset
shapes (`shape roundRect`, any of the ~180 OOXML presets, matched
case-insensitively); images (PNG/JPEG/GIF, and SVG — embedded together
with a PNG fallback for older viewers, sized explicitly or by aspect
ratio, path resolved and contained under the source file's own
directory); `include "house.pik"` for shared definitions (contained the
same way, with cycle detection); object identity — a label becomes the
shape's real PowerPoint name (an unlabeled object gets a default `box
1`-style name), and `behind X` places an object immediately below `X`
in z-order — so the Selection Pane reads like the source (`[ ... ]`
blocks are a source-level grouping construct only, flattened rather than
turned into a PowerPoint group when written out); starting a new
standalone deck from another file's theme instead of the built-in Office
one (`--template`); a template's settings file (`<name>.theme.pik`, or
`--settings FILE`), for its slide layout, font, accent colors and text
sizes; and diagnostics — `file:line:column`, the source line and a caret
for a syntax error (naming the right file even inside a nested
`include`), "did you mean" suggestions for an unknown
color/preset/image name, `--strict`, `--check`, and `--format json`.

Deliberately out of v1 (docs/spec.md §7): inserting into an existing
deck's slide, ` ```pikslide ` blocks in Markdown, connectors, SVG *output*,
auto-layout, tables/charts/SmartArt, animation, multi-slide authoring,
true Bézier curves, shape adjustment handles, arithmetic on colors.

## How it works

1. **Parse** — source is tokenized and parsed into an AST
   (`pikslide.pik.ast.Document`).
2. **Layout** — the AST is resolved into concrete 2-D geometry (box positions,
   arrow paths, text placement).
3. **Render** — the resolved geometry is written out as PowerPoint objects.

## Requirements

- Python 3.12+

## Install

From PyPI, as a standalone `pikslide` command:

```sh
uv tool install pikslide
# or
pipx install pikslide
```

`pikslide --version` prints the version installed. To remove it later:
`uv tool uninstall pikslide` (or `pipx uninstall pikslide`).

### From source

To work on pikslide itself, clone the repository and use
[uv](https://docs.astral.sh/uv/). The examples below call an installed
`pikslide`; in a clone, `uv run pikslide ...` runs it with no install step.
To install the clone as a standalone command instead (placed in
`~/.local/bin`), from the project root:

```sh
uv tool install .
```

If `~/.local/bin` isn't on your `PATH` yet, run `uv tool update-shell`.

## Usage

Dump the parsed tree for a `.pik` file (useful for inspecting how a script was
understood, or for debugging):

```sh
pikslide diagram.pik
```

Render a `.pik` file straight to PowerPoint:

```sh
pikslide diagram.pik diagram.pptx
```

The result is a new one-slide deck sized to the diagram; an existing
OUTPUT is overwritten.

To draw on a real template's slide, in its theme and fonts, instead of
the built-in Office ones:

```sh
pikslide diagram.pik diagram.pptx --template corporate.potx
pikslide diagram.pik diagram.pptx --template corporate.potx --layout "Two Content"
```

(OUTPUT may be omitted when `--template` is given: it then defaults to
INPUT's own path with its extension changed to `.pptx`.) The slide is the
template's own size, and the diagram goes at the top left of its content
area, clear of the title and footer. Its layout is the template's Title
and Content layout (the first with one placeholder besides its title,
date, footer and slide number), unless `--layout` or the template's
settings file names another, by its name or, where two layouts share a
name, its id. `pikslide --help template` has the details: the content
area, the settings file, and the defaults a template sets.

`--check` parses and lays out a source without writing anything, and
`--format json` emits diagnostics as one JSON object instead of plain
text — see `pikslide --help` for every flag.

`pikslide --help TOPIC` is the language reference: a keyword (`--help box`
gives its synopsis, attributes and defaults), a list (`colors`, `shapes`,
`keywords`, …), a color or a preset shape (`--help accent1`, `--help
callout1`: what it looks like), or a manual (`grammar`, `spec`).
`pikslide --help` lists the topics.

With no arguments, `pikslide` prints its usage and points to
`pikslide --help intro`, the language in one page.

`--png` / `--pdf` also render the deck just written to a PNG or a PDF —
beside OUTPUT with the extension changed, or at an explicit path:

```sh
pikslide diagram.pik diagram.pptx --png --pdf
pikslide diagram.pik diagram.pptx --png images/diagram.png
```

(Give OUTPUT before `--png`/`--pdf`, since their PATH is optional.) This
uses PowerPoint itself, through COM automation (via `powershell.exe`),
when it's reachable — Windows, or WSL with a Windows PowerPoint install —
since that's the actual renderer pikslide's output is meant for; otherwise
it falls back to LibreOffice (`soffice`) and says so in a note: a
different rendering engine, good for a quick look but not for verifying
exact layout or text fit against real PowerPoint. `--renderer powerpoint`
or `--renderer libreoffice` uses only that one.
With no `--template`, pikslide sizes its slide exactly to the diagram, so
the PNG is an image of just the diagram, no separate cropping needed; with
one, it is the whole slide, as it will look in the deck. The PowerShell scripts
behind this (`src/pikslide/ps/*.ps1`) also run on their own from Windows
PowerShell.

### Example

`docs/examples/pipeline.pik`:

```pikslide
arrow "Markdown" "Source" right 200%
box "pikslide" "Formatter" rad 10px fit
arrow "PPTX" "Output" right 200%
arrow <- down 70% from last box.s
file "pikslide" "Language" fit
```

```sh
pikslide docs/examples/pipeline.pik docs/examples/pipeline.pptx --png
```

![pipeline.png: the diagram as PowerPoint draws it](https://raw.githubusercontent.com/mkyutani/pikslide/main/docs/examples/pipeline.png)

[docs/examples/](https://github.com/mkyutani/pikslide/tree/main/docs/examples) has more, each with the PPTX and PNG it
renders to.
[docs/examples/japan-capitals.md](https://github.com/mkyutani/pikslide/blob/main/docs/examples/japan-capitals.md) is one
that Claude Code drew, with the prompt it was given.

## Limits of the current layout stage

The layout stage is a deliberately pragmatic subset of a full CAD-style
layout engine, covering common diagrams well rather than every case:
default object sizes, sequential chaining,
`at`/`with`/`from`/`to`/`then`/`go`/`same`/`chop`, and box/ellipse/diamond
edge geometry are all there, but a few things are simplified:

- spline/arc curves are drawn as straight polylines,
- `fit` text sizing measures with the deck's own fonts when rendering to
  PowerPoint (docs/spec.md §3.3), but falls back to a flat per-character
  estimate otherwise,
- chopping against diamond/cylinder/file shapes uses a rectangle-like
  approximation rather than each shape's true outline.

See the module docstrings in `src/pikslide/pik/layout.py` for details.

## Development

```sh
uv run pytest
```

Test fixtures under `tests/fixtures/examples/` are a corpus of official
example diagrams inherited via the port described in Acknowledgments,
kept as a regression net for behavior that hasn't deliberately changed.

## Acknowledgments

pikslide traces its lineage through two earlier languages. Brian
Kernighan's `pic` (1984) introduced sequential, relative placement of
named objects — draw one thing, then the next one relative to it — rather
than absolute coordinates. D. Richard Hipp's [pikchr](https://pikchr.org/)
carried that idea into a full, modern language, emitting SVG. pikslide's
tokenizer, grammar, macro expansion, and layout engine began as a direct
port of pikchr's own, and the port goes well beyond syntax — default
object sizes, placement and chaining math, and edge geometry are all
inherited from it, not rebuilt from scratch. pikslide's own design departs
from there where a diagram that lives inside a PowerPoint slide, rather
than becoming an SVG picture, calls for a different answer.

pikchr's [source](https://pikchr.org/home/doc/tip/pikchr.y) states it is
released under the Zero-Clause BSD license. See [NOTICE](https://github.com/mkyutani/pikslide/blob/main/NOTICE) for
details.

## License

[0BSD](https://github.com/mkyutani/pikslide/blob/main/LICENSE)
