Metadata-Version: 2.5
Name: asp-format
Version: 0.1.1
Summary: A formatter for Answer Set Programming (ASP) programs
Project-URL: Homepage, https://codeberg.org/erikgroeneveld/asp-format
Author: Erik Groeneveld
License-Expression: LGPL-3.0-or-later
Keywords: answer set programming,asp,clingo,formatter,lint
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Text Processing :: General
Requires-Python: >=3.14
Requires-Dist: black
Requires-Dist: clingo
Provides-Extra: selftest
Requires-Dist: selftest; extra == 'selftest'
Description-Content-Type: text/markdown

# asp-format

A formatter for Answer Set Programming (ASP) programs. It reads the same input
as clingo and re-renders a program in a clean, deterministic style without
changing its meaning: long lines wrap at the eightieth column, each
continuation indents four spaces, and comments keep both their place and their
framing.

## Install

```sh
$ pip install asp-format
```

## Use it as a command

asp-format rewrites `.lp` files on disk or echoes the result to standard
output. It is fail safe by default: the formatted program is built in full
before any write, and an atomic rename means a program that does not parse
never leaves the source file half written.

```sh
$ asp-format prog.lp
$ asp-format --in-place a.lp b.lp
$ asp-format --help
```

Options:

- `PATH` one or more `.lp` files; with no path the command stays silent.
- `-i`, `--in-place` rewrite each source file in place instead of printing it.
- `-h`, `--help` print the usage and exit.

## A small example

**Input**

```
a:-b,c.
```

**Output**

```
a  :-
    b,
    c.
```

## Use it as a library

```python
from asp_format import format_text, format_files, format_file

format_text("a:-b,c.")
format_files(["a.lp", "b.lp"])
format_file("a.lp", in_place=True)
```

`format_text` turns one program string into its formatted text, `format_files`
joins the results for several files, and `format_file` reads and (with
`in_place=True`) rewrites a file fail safely. To format standard input, pipe it
through `format_text`. The lower-level helpers are `parse` (the top-level
nodes), `render` (print one program), `ast_skeleton` and `protect_includes` (the
parsing around them), and `Formatter`, the underlying `clingo.ast.Transformer`
for anyone who drives the walk themselves.

## The formatting contract

- Lines stay within an 80-character limit, a few long names and paths aside.
- Code wraps at its separators `:-`, `;`, `,` and `.`, then indents four spaces per level; expressions and intervals keep their one-line shape.
- A run of comments opens one blank line before it and leaves nothing blank after it, `% program` directives open with two blank lines, and multi-line blocks take one blank.
- An overflowing comment is rewrapped on whitespace but keeps its framing, so a `%* ... *%` block stays a block and a `%` line comment spreads over `%` lines rather than becoming a block.

## About the author

This project was set up by Erik Groeneveld. He wrote the parser and the AST
visitor that turns an Answer Set Program into neatly formatted code, and he then
let a local large-language model extend and refine the work under his own
review. He steers the model by questions rather than by dictating changes,
because asking questions surfaces the model's learned knowledge while dictating
makes it placate. He reviews everything and edits when he can do better or
faster, to honor Codeberg's rule against sharing a project that mostly consists
of generative-AI output.

Both the idea and the architecture are his. There is no other ASP formatter on
the internet, so this implementation is his, and it is free for anyone to use.

## License

Licensed under the GNU Lesser General Public License, version 3 or any later
version (`LGPL-3.0-or-later`). The full text is in
`LICENSES/LGPL-3.0.txt`, and each source file carries the matching SPDX header
`SPDX-License-Identifier: LGPL-3.0-or-later`.

## Acknowledgements

My heartfelt thanks to Qwen3.8 and Pi.dev for their relentless hard work, extraordinary patience, and generous interpretation of the phrase “just one more thing.”

They worked through nights, weekends, and several moments that any reasonable person would have reserved for reconsidering their commitments. No revision was too small, no deadline too unreasonable, and no supposedly final draft ever quite final enough.

This software would not have been possible without them. Any remaining errors are mine, despite my best efforts to delegate those too.

Erik Groeneveld
