scadfmt 0.1.0__py3-none-any.whl

scadfmt/__init__.py

@@ -0,0 +1,9 @@
+"""Opinionated formatter for OpenSCAD code (scadfmt)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+# release-please bumps pyproject.toml only, so the installed metadata is the single source of truth.
+try:
+    __version__ = version("scadfmt")
+except PackageNotFoundError:
+    __version__ = "unknown"

scadfmt/__main__.py

@@ -0,0 +1,7 @@
+"""Run scadfmt as `python -m scadfmt`."""
+
+import sys
+
+from scadfmt.cli import main
+
+sys.exit(main())

scadfmt/cli.py

@@ -0,0 +1,147 @@
+"""Command-line interface for scadfmt."""
+
+import argparse
+import difflib
+import logging
+import sys
+from pathlib import Path
+
+from scadfmt import __version__
+from scadfmt.fileio import write_atomically
+from scadfmt.formatter import FormatError, format_source
+from scadfmt.vscode import setup_vscode
+
+logger = logging.getLogger(__name__)
+
+EXIT_OK = 0
+EXIT_CHANGES = 1
+EXIT_ERROR = 2
+
+
+def _collect(paths: list[str]) -> list[Path]:
+    """Expand directories to the .scad files below them, sorted."""
+    files: list[Path] = []
+    for raw in paths:
+        path = Path(raw)
+        if path.is_dir():
+            files.extend(sorted(path.rglob("*.scad")))
+        else:
+            files.append(path)
+    return files
+
+
+def _diff(before: str, after: str, name: str) -> str:
+    """Unified diff between two versions of a file."""
+    return "".join(
+        difflib.unified_diff(
+            before.splitlines(keepends=True),
+            after.splitlines(keepends=True),
+            f"{name} (original)",
+            f"{name} (formatted)",
+        )
+    )
+
+
+def _write(text: str) -> None:
+    """Write UTF-8 text to stdout without newline translation."""
+    sys.stdout.buffer.write(text.encode("utf-8"))
+    sys.stdout.buffer.flush()
+
+
+def _format_stdin(check: bool, diff: bool) -> int:
+    """Format stdin to stdout, or report on it with --check or --diff."""
+    # Bytes, not text: text mode would translate newlines and use the locale codepage on Windows.
+    try:
+        source = sys.stdin.buffer.read().decode("utf-8")
+        formatted = format_source(source)
+    except (UnicodeDecodeError, FormatError) as e:
+        logger.error("<stdin>:%s", e)
+        return EXIT_ERROR
+    if diff:
+        _write(_diff(source, formatted, "<stdin>"))
+    elif not check:
+        _write(formatted)
+    return EXIT_CHANGES if check and formatted != source else EXIT_OK
+
+
+def _format_files(files: list[Path], check: bool, diff: bool) -> int:
+    """Format files in place, or report on them with --check or --diff."""
+    changed = errors = 0
+    for path in files:
+        try:
+            source = path.read_bytes().decode("utf-8")
+            formatted = format_source(source)
+        except (OSError, UnicodeDecodeError, FormatError) as e:
+            logger.error("%s:%s", path, e)
+            errors += 1
+            continue
+        if formatted == source:
+            continue
+        changed += 1
+        if diff:
+            _write(_diff(source, formatted, str(path)))
+        if check or diff:
+            logger.info("would reformat %s", path)
+        else:
+            try:
+                write_atomically(path, formatted)
+            except OSError as e:
+                logger.error("%s: cannot write: %s", path, e)
+                errors += 1
+                continue
+            logger.info("reformatted %s", path)
+    if errors:
+        return EXIT_ERROR
+    return EXIT_CHANGES if check and changed else EXIT_OK
+
+
+def _handle_format(args: argparse.Namespace) -> int:
+    """Run the format subcommand."""
+    if args.paths == ["-"]:
+        return _format_stdin(args.check, args.diff)
+    if "-" in args.paths:
+        logger.error("'-' (stdin) cannot be combined with file paths")
+        return EXIT_ERROR
+    return _format_files(_collect(args.paths), args.check, args.diff)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser.
+
+    Returns:
+        The configured parser.
+    """
+    parser = argparse.ArgumentParser(prog="scadfmt", description="Opinionated formatter for OpenSCAD code.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    format_parser = subparsers.add_parser("format", help="Format .scad files in place")
+    format_parser.add_argument("paths", nargs="+", help="Files or directories to format, or '-' for stdin")
+    format_parser.add_argument("--check", action="store_true", help="Write nothing, exit 1 if any file would change")
+    format_parser.add_argument("--diff", action="store_true", help="Write nothing, print a diff of the changes")
+
+    vscode_parser = subparsers.add_parser("vscode", help="Make scadfmt the VS Code formatter for .scad files")
+    vscode_parser.add_argument(
+        "--workspace", default=".", help="Workspace folder whose .vscode/settings.json is updated (default: .)"
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run scadfmt.
+
+    Args:
+        argv: Arguments without the program name. Defaults to sys.argv[1:].
+
+    Returns:
+        Exit code: 0 clean, 1 files would change (--check), 2 error.
+    """
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    args = build_parser().parse_args(argv)
+    if args.command == "vscode":
+        return EXIT_OK if setup_vscode(Path(args.workspace)) else EXIT_ERROR
+    return _handle_format(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scadfmt/fileio.py

@@ -0,0 +1,31 @@
+"""Atomic file writes shared by formatting and VS Code setup."""
+
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+
+def write_atomically(path: Path, text: str) -> None:
+    """Replace the file at path with text in one step, so a failed write never leaves a truncated file.
+
+    A symlink is followed and its target updated. An existing file keeps its permissions.
+
+    Args:
+        path: File to write, created if missing.
+        text: New content, written as UTF-8 without newline translation.
+
+    Raises:
+        OSError: If the temporary file cannot be written or moved into place.
+    """
+    target = path.resolve() if path.is_symlink() else path
+    handle, temp_name = tempfile.mkstemp(dir=target.parent, prefix=f".{target.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(handle, "wb") as temp:
+            temp.write(text.encode("utf-8"))
+        if target.exists():
+            shutil.copymode(target, temp_name)
+        os.replace(temp_name, target)
+    except OSError:
+        Path(temp_name).unlink(missing_ok=True)
+        raise

scadfmt/formatter.py

@@ -0,0 +1,527 @@
+"""Format OpenSCAD source by re-spacing and re-indenting its tokens.
+
+Line breaks stay where the author put them. Only the whitespace between tokens changes, which `format_source`
+verifies by comparing the tokens of input and output.
+"""
+
+from dataclasses import dataclass, field
+
+from scadfmt.tokenizer import Kind, Token, TokenizeError, significant, tokenize
+
+INDENT = "  "
+COMMENT_GAP = 2
+MAX_BLANK_LINES_TOP = 2
+MAX_BLANK_LINES_NESTED = 1
+FMT_OFF = "// fmt: off"
+FMT_ON = "// fmt: on"
+
+OPENERS = {"(": ")", "[": "]", "{": "}"}
+CLOSERS = {v: k for k, v in OPENERS.items()}
+# Keywords followed by a space before `(`; every other name is a call and stays tight.
+SPACED_BEFORE_PAREN = {"if", "for", "intersection_for", "function"}
+MODIFIERS = {"#", "%", "!", "*"}
+UNARY = {"-", "+", "!", "~"}
+HEADER_KEYWORDS = {"if", "for", "intersection_for", "let", "function", "assert", "echo"}
+# A previous token after which a line continues the statement instead of starting a new one.
+STATEMENT_ENDS = {";", "{", "}"}
+
+
+class FormatError(ValueError):
+    """Raised when source cannot be formatted safely."""
+
+
+@dataclass
+class _Frame:
+    """An open bracket (or the file root) and what the formatter tracks inside it."""
+
+    char: str
+    level: int
+    pending_ternaries: int = 0
+    # `(` right after `if`, `for`, `let`, `function`...: a `-` after its `)` starts an operand.
+    header: bool = False
+    # Levels of unbraced `if` lines still waiting for a possible `else`.
+    if_levels: list[int] = field(default_factory=list)
+
+
+@dataclass
+class _Line:
+    """One output line before trailing comments are aligned."""
+
+    indent: str
+    code: str
+    comment: str | None = None
+    verbatim: bool = False
+    blank: bool = False
+
+
+@dataclass
+# pylint: disable-next=too-many-instance-attributes  # Plain state holder for one formatting pass
+class _State:
+    """Everything the formatter carries from one token to the next."""
+
+    stack: list[_Frame] = field(default_factory=lambda: [_Frame("", -1)])
+    previous: Token | None = None
+    previous_role: str = ""
+    in_expression: bool = False
+    # Level of the line the last code line belongs to, see `_render_tokens`.
+    line_anchor: int = 0
+    after_header: bool = False
+    newline: str = "\n"
+    # Stack depths at which open module/function definitions started, and whether one just ended.
+    definition_depths: list[int] = field(default_factory=list)
+    definition_ended: bool = False
+
+
+def format_source(source: str) -> str:
+    """Format OpenSCAD source.
+
+    Args:
+        source: OpenSCAD source text.
+
+    Returns:
+        The formatted source, ending in exactly one newline. Line endings follow the first one in source.
+
+    Raises:
+        FormatError: On input that cannot be tokenized, has unbalanced brackets, or would change meaning.
+    """
+    try:
+        tokens = tokenize(source)
+    except TokenizeError as e:
+        raise FormatError(str(e)) from e
+    source_lines = source.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+    output = _render(_split_lines(_insert_breaks(tokens)), source_lines, _newline(source))
+    if significant(tokenize(output)) != significant(tokens):
+        raise FormatError("formatting would change the code, file left untouched (please report this as a bug)")
+    return output
+
+
+def _newline(source: str) -> str:
+    """The line ending the file uses, judged by its first line break (LF if it has none)."""
+    first = next((i for i, char in enumerate(source) if char in "\r\n"), None)
+    if first is None or source[first] == "\n":
+        return "\n"
+    return "\r\n" if source.startswith("\r\n", first) else "\r"
+
+
+def _insert_breaks(tokens: list[Token]) -> list[Token]:
+    """Put block contents and statements on their own lines.
+
+    Adds a line break after `{`, around `}` (keeping `} else`) and after `;` outside parentheses, except in empty
+    `{}`, before a trailing comment and inside `// fmt: off` regions. Added breaks have empty text.
+    """
+    out: list[Token] = []
+    stack: list[str] = []
+    fmt_off = False
+
+    def ensure_break(after: Token) -> None:
+        if out and out[-1].kind != Kind.NEWLINE:
+            out.append(Token(Kind.NEWLINE, "", after.line, after.col))
+
+    for index, token in enumerate(tokens):
+        following = tokens[index + 1] if index + 1 < len(tokens) else None
+        if token.kind == Kind.LINE_COMMENT and token.text.strip() in (FMT_OFF, FMT_ON):
+            fmt_off = token.text.strip() == FMT_OFF
+        is_op = token.kind == Kind.OP
+        if not fmt_off and is_op and token.text == "}" and not (out and out[-1].text == "{"):
+            ensure_break(token)
+        out.append(token)
+        if is_op and token.text in OPENERS:
+            stack.append(token.text)
+        elif is_op and token.text in CLOSERS and stack:
+            stack.pop()
+        if fmt_off or not is_op or following is None:
+            continue
+        if following.kind in (Kind.NEWLINE, Kind.LINE_COMMENT):
+            continue
+        if _breaks_after(token.text, following.text, not stack or stack[-1] == "{"):
+            ensure_break(token)
+    return out
+
+
+def _breaks_after(text: str, following: str, at_statement_level: bool) -> bool:
+    """Whether a line break follows the operator text when following comes next on the same line."""
+    if text == "{":
+        return following != "}"
+    if text == "}":
+        return following not in ("else", ";")
+    return text == ";" and at_statement_level
+
+
+def _split_lines(tokens: list[Token]) -> list[tuple[list[Token], int, int]]:
+    """Group tokens into physical lines.
+
+    Returns:
+        (tokens, first source line, last source line) per line. A multi-line comment or string keeps the lines it
+        spans in one group.
+    """
+    lines = []
+    current: list[Token] = []
+    start = 1
+    for token in tokens:
+        if token.kind == Kind.NEWLINE:
+            lines.append((current, start, token.line))
+            # An added break (empty text) splits a source line, so the next group starts on the same one.
+            current, start = [], token.line + 1 if token.text else token.line
+        else:
+            current.append(token)
+    if current:
+        lines.append((current, start, current[-1].line + current[-1].text.count("\n")))
+    return lines
+
+
+def _render(lines: list[tuple[list[Token], int, int]], source_lines: list[str], newline: str = "\n") -> str:
+    """Turn grouped tokens into formatted text joined by newline."""
+    state = _State(newline=newline)
+    out: list[_Line] = []
+    blank_run = 0
+    fmt_off = False
+    next_code_is_import = _next_code_is_import(lines)
+    definition_starts = _definition_starts(lines)
+    after_import = False
+    for index, (tokens, first, last) in enumerate(lines):
+        if not tokens:
+            if fmt_off:
+                out.append(_Line("", "", verbatim=True))
+            else:
+                blank_run += 1
+            continue
+        level = _match_else(tokens, _line_level(tokens[0], state), state)
+        marker = tokens[0].text.strip() if len(tokens) == 1 and tokens[0].kind == Kind.LINE_COMMENT else None
+        if after_import and not fmt_off:
+            blank_run, after_import = _import_block_gap(tokens, next_code_is_import[index])
+        if not _is_comment_only(tokens):
+            after_import = _is_import(tokens)
+        if not fmt_off:
+            blank_run = _definition_gap(tokens, blank_run, definition_starts[index], state)
+            if _is_definition(tokens):
+                state.definition_depths.append(len(state.stack))
+            out.extend(_blank_lines(blank_run, top_level=len(state.stack) == 1 and level == 0))
+        blank_run = 0
+        code, comment = _render_tokens(tokens, level, state)
+        _close_definitions(state)
+        if fmt_off and marker != FMT_ON:
+            out.extend(_Line("", text, verbatim=True) for text in source_lines[first - 1 : last])
+            continue
+        out.append(_Line(INDENT * level, code, comment))
+        fmt_off = marker == FMT_OFF or (fmt_off and marker != FMT_ON)
+    if len(state.stack) > 1:
+        frame = state.stack[-1]
+        raise FormatError(f"unclosed {frame.char!r} at end of file")
+    # Blank lines only reach out before a following line, so only leading ones need trimming.
+    while out and out[0].blank:
+        out.pop(0)
+    _align_comments(out)
+    # Joined with the file's newline directly: a multi-line string keeps its own line endings.
+    text = newline.join(line.code if line.verbatim else _join(line) for line in out)
+    return text + newline if text else ""
+
+
+def _is_definition(tokens: list[Token]) -> bool:
+    """True for a line starting a `module` or `function` definition (not a function literal)."""
+    first = tokens[0]
+    return (
+        first.kind == Kind.IDENT
+        and first.text in ("module", "function")
+        and tokens[1:2] != []
+        and (tokens[1].kind == Kind.IDENT)
+    )
+
+
+def _definition_starts(lines: list[tuple[list[Token], int, int]]) -> list[bool]:
+    """Per line: whether a definition, including the comments directly above it, starts here."""
+    starts = [False] * len(lines)
+    for index, (tokens, _, _) in enumerate(lines):
+        if not tokens or not _is_definition(tokens):
+            continue
+        top = index
+        while top > 0 and _is_attached_comment(lines[top - 1][0]):
+            top -= 1
+        starts[top] = True
+    return starts
+
+
+def _is_attached_comment(tokens: list[Token]) -> bool:
+    """True for a comment-only line that belongs to the definition below it (fmt markers never do)."""
+    if not tokens or not _is_comment_only(tokens):
+        return False
+    return tokens[0].text.strip() not in (FMT_OFF, FMT_ON)
+
+
+def _definition_gap(tokens: list[Token], blank_run: int, starts_definition: bool, state: _State) -> int:
+    """Exactly one blank line before and after a definition, but none next to a brace or the file start.
+
+    Returns:
+        The number of blank lines to put before this line.
+    """
+    ended, state.definition_ended = state.definition_ended, False
+    if not (starts_definition or ended):
+        return blank_run
+    previous, first = state.previous, tokens[0]
+    if previous is None or (previous.kind == Kind.OP and previous.text == "{"):
+        return blank_run
+    if first.kind == Kind.OP and first.text in CLOSERS:
+        return blank_run
+    return 1
+
+
+def _close_definitions(state: _State) -> None:
+    """Mark a definition as ended once its closing `;` or `}` brings the bracket depth back."""
+    previous = state.previous
+    while (
+        state.definition_depths
+        and len(state.stack) == state.definition_depths[-1]
+        and previous is not None
+        and previous.text in (";", "}")
+    ):
+        state.definition_depths.pop()
+        state.definition_ended = True
+
+
+def _blank_lines(count: int, top_level: bool) -> list[_Line]:
+    """Up to count blank lines, capped by where they sit."""
+    allowed = MAX_BLANK_LINES_TOP if top_level else MAX_BLANK_LINES_NESTED
+    return [_Line("", "", blank=True) for _ in range(min(count, allowed))]
+
+
+def _match_else(tokens: list[Token], level: int, state: _State) -> int:
+    """Put an `else` at the level of the unbraced `if` it belongs to, and track those `if`s.
+
+    Returns:
+        The line's level, corrected for an `else`.
+    """
+    frame, first = state.stack[-1], tokens[0]
+    if (first.kind == Kind.OP and first.text in CLOSERS) or _is_comment_only(tokens):
+        return level
+    is_else = first.kind == Kind.IDENT and first.text == "else"
+    if is_else and frame.if_levels:
+        level = frame.if_levels.pop()
+    elif frame.char in ("", "{") and level == frame.level + 1:
+        # A new statement ends every `if` at or below its level.
+        frame.if_levels = [pending for pending in frame.if_levels if pending < level]
+    starts_if = first.text == "if" or (is_else and len(tokens) > 1 and tokens[1].text == "if")
+    if first.kind == Kind.IDENT and starts_if:
+        frame.if_levels.append(level)
+    return level
+
+
+def _is_import(tokens: list[Token]) -> bool:
+    """True for an `include <...>` or `use <...>` line."""
+    return len(tokens) > 1 and tokens[1].kind == Kind.PATH
+
+
+def _is_comment_only(tokens: list[Token]) -> bool:
+    """True for a line holding only comments."""
+    return all(token.kind in (Kind.LINE_COMMENT, Kind.BLOCK_COMMENT) for token in tokens)
+
+
+def _import_block_gap(tokens: list[Token], next_code_is_import: bool) -> tuple[int, bool]:
+    """Blank lines before a line that follows an import: none inside the block, exactly one after it.
+
+    Returns:
+        The blank line count and whether the line still belongs to the import block.
+    """
+    inside = _is_import(tokens) or (_is_comment_only(tokens) and next_code_is_import)
+    return (0 if inside else 1), inside
+
+
+def _next_code_is_import(lines: list[tuple[list[Token], int, int]]) -> list[bool]:
+    """Per line: whether the next line with code after it is an import."""
+    result = [False] * len(lines)
+    following = False
+    for index in range(len(lines) - 1, -1, -1):
+        result[index] = following
+        tokens = lines[index][0]
+        if tokens and not _is_comment_only(tokens):
+            following = _is_import(tokens)
+    return result
+
+
+def _join(line: _Line) -> str:
+    """Build one output line from its parts."""
+    if line.blank:
+        return ""
+    if line.comment is None:
+        return line.indent + line.code
+    if not line.code:
+        return line.indent + line.comment
+    return line.indent + line.code + " " * COMMENT_GAP + line.comment
+
+
+def _align_comments(out: list[_Line]) -> None:
+    """Align trailing comments of consecutive lines to one column; a lone one keeps the default gap."""
+    run: list[_Line] = []
+    for line in [*out, None]:
+        if line is not None and not line.verbatim and line.code and line.comment is not None:
+            run.append(line)
+            continue
+        if len(run) > 1:
+            width = max(len(item.indent + item.code) for item in run)
+            for item in run:
+                item.code += " " * (width - len(item.indent + item.code))
+        run = []
+
+
+def _line_level(first: Token, state: _State) -> int:
+    """Indent level of a line starting with first, given the state before it."""
+    top = state.stack[-1]
+    if first.kind == Kind.OP and first.text in CLOSERS:
+        return max(top.level, 0)
+    base = top.level + 1
+    if top.char in ("(", "["):
+        return base
+    previous = state.previous
+    starts_statement = (
+        previous is None
+        or previous.kind == Kind.PATH
+        or (previous.kind == Kind.OP and previous.text in STATEMENT_ENDS)
+        or (first.kind == Kind.OP and first.text == "{")
+    )
+    if starts_statement:
+        return base
+    # Expressions continue one level in; a chain of module calls nests one level per line.
+    return base + 1 if state.in_expression else max(state.line_anchor, top.level) + 1
+
+
+def _render_tokens(tokens: list[Token], level: int, state: _State) -> tuple[str, str | None]:
+    """Render one line's tokens and update state.
+
+    Returns:
+        The code part and the trailing line comment, if any.
+    """
+    comment = None
+    if tokens[-1].kind == Kind.LINE_COMMENT:
+        comment = tokens[-1].text.rstrip()
+        tokens = tokens[:-1]
+    parts: list[str] = []
+    before: Token | None = None
+    before_role = ""
+    # A bracket opened after closing a multi-line `(` or `[` on this line belongs to the line that opened it.
+    anchor = level
+    for token in tokens:
+        role = _role(token, state)
+        text = _token_text(token, state.newline)
+        if before is not None and _needs_space(before, before_role, token, role):
+            parts.append(" ")
+        parts.append(text)
+        before, before_role = token, role
+        closed = _advance(token, role, anchor, state)
+        if closed is not None and closed.char in ("(", "["):
+            anchor = min(anchor, closed.level)
+    if any(token.kind != Kind.BLOCK_COMMENT for token in tokens):
+        state.line_anchor = anchor
+    return "".join(parts), comment
+
+
+def _token_text(token: Token, newline: str) -> str:
+    """Token text as written to the output."""
+    if token.kind == Kind.BLOCK_COMMENT:
+        return newline.join(part.rstrip() for part in token.text.splitlines())
+    return token.text
+
+
+def _role(token: Token, state: _State) -> str:
+    """Classify an operator by its position: binary, unary, modifier, range or plain."""
+    if token.kind != Kind.OP:
+        return ""
+    text = token.text
+    previous, frame = state.previous, state.stack[-1]
+    if text in MODIFIERS and _at_statement_start(state):
+        return "modifier"
+    if text in UNARY and (state.after_header or _expects_operand(previous)):
+        return "unary"
+    if text == ":":
+        return "binary" if frame.pending_ternaries else "range"
+    if text in OPENERS or text in CLOSERS or text in (",", ";", "."):
+        return ""
+    return "binary"
+
+
+def _at_statement_start(state: _State) -> bool:
+    """True where a `#`, `%`, `!` or `*` is a modifier rather than an operator."""
+    if state.stack[-1].char not in ("", "{") or state.in_expression:
+        return False
+    previous = state.previous
+    if previous is None or state.previous_role == "modifier":
+        return True
+    if previous.kind == Kind.IDENT:
+        return previous.text == "else"
+    return previous.kind == Kind.OP and previous.text in (";", "{", "}", ")")
+
+
+def _expects_operand(previous: Token | None) -> bool:
+    """True when the next token starts an operand, so `-` or `!` is unary."""
+    if previous is None:
+        return True
+    if previous.kind == Kind.IDENT:
+        return previous.text in ("else", "each")
+    return previous.kind == Kind.OP and previous.text not in (")", "]")
+
+
+# pylint: disable-next=too-many-return-statements  # One rule per line reads better than a nested condition
+def _needs_space(left: Token, left_role: str, right: Token, right_role: str) -> bool:
+    """Whether one space separates left and right on the same line."""
+    lt, rt = left.text, right.text
+    if right.kind == Kind.OP and rt in (")", "]", ",", ";"):
+        return False
+    if left.kind == Kind.OP and lt in ("(", "[", "."):
+        return False
+    if right.kind == Kind.OP and rt == ".":
+        return False
+    if left_role == "unary" and right_role == "unary" and lt in "+-" and rt in "+-":
+        return True  # `- -x`, never `--x`
+    if left_role in ("unary", "modifier") or "range" in (left_role, right_role):
+        return False
+    if "binary" in (left_role, right_role):
+        return True
+    if right.kind == Kind.OP and rt == "}":
+        return lt != "{"
+    if right.kind == Kind.OP and rt in ("(", "["):
+        return _space_before_bracket(left, rt)
+    return True
+
+
+def _space_before_bracket(left: Token, bracket: str) -> bool:
+    """Whether `(` or `[` after left gets a space: calls and indexing stay tight."""
+    if left.kind == Kind.IDENT:
+        return left.text in SPACED_BEFORE_PAREN if bracket == "(" else left.text == "each"
+    if left.kind == Kind.OP and left.text in (")", "]"):
+        return False
+    return True
+
+
+def _advance(token: Token, role: str, level: int, state: _State) -> _Frame | None:
+    """Update state after emitting token.
+
+    Returns:
+        The frame token closed, if it is a closing bracket.
+    """
+    if token.kind in (Kind.LINE_COMMENT, Kind.BLOCK_COMMENT):
+        return None
+    before = state.previous
+    state.previous, state.previous_role, state.after_header = token, role, False
+    if token.kind != Kind.OP:
+        return None
+    text, frame = token.text, state.stack[-1]
+    if text in OPENERS:
+        header = text == "(" and before is not None and before.kind == Kind.IDENT and before.text in HEADER_KEYWORDS
+        state.stack.append(_Frame(text, level, header=header))
+        if text == "{":
+            state.in_expression = False
+    elif text in CLOSERS:
+        if frame.char != CLOSERS[text]:
+            raise FormatError(f"{token.line}:{token.col}: unexpected {text!r}")
+        state.stack.pop()
+        state.after_header = frame.header
+        if text == "}":
+            state.in_expression = False
+        return frame
+    elif text == "?":
+        frame.pending_ternaries += 1
+    elif text == ":" and role == "binary":
+        frame.pending_ternaries -= 1
+    elif text == ";" and frame.char in ("", "{"):
+        state.in_expression = False
+        frame.pending_ternaries = 0
+    elif text == "=" and frame.char in ("", "{"):
+        state.in_expression = True
+    return None

scadfmt/tokenizer.py

@@ -0,0 +1,177 @@
+"""Split OpenSCAD source into tokens.
+
+The formatter only ever changes the whitespace between tokens, so the token list is also its safety check:
+the tokens of the formatted output must equal the tokens of the input.
+"""
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Kind(Enum):
+    """Token kinds the formatter distinguishes."""
+
+    NEWLINE = "newline"
+    LINE_COMMENT = "line_comment"
+    BLOCK_COMMENT = "block_comment"
+    STRING = "string"
+    NUMBER = "number"
+    IDENT = "ident"
+    PATH = "path"
+    OP = "op"
+
+
+@dataclass(frozen=True)
+class Token:
+    """One token with the position of its first character (1-based)."""
+
+    kind: Kind
+    text: str
+    line: int
+    col: int
+
+
+class TokenizeError(ValueError):
+    """Raised on input the tokenizer cannot split safely."""
+
+
+# Longest operators first, so `<=` wins over `<`.
+OPERATORS = (
+    "<<",
+    ">>",
+    "<=",
+    ">=",
+    "==",
+    "!=",
+    "&&",
+    "||",
+    "+",
+    "-",
+    "*",
+    "/",
+    "%",
+    "^",
+    "!",
+    "~",
+    "&",
+    "|",
+    "<",
+    ">",
+    "=",
+    "?",
+    ":",
+    ",",
+    ";",
+    ".",
+    "(",
+    ")",
+    "[",
+    "]",
+    "{",
+    "}",
+    "#",
+)
+
+_PATTERNS = [
+    # OpenSCAD also skips U+00A0 (no-break space) and U+FEFF (byte order mark).
+    (None, re.compile("[ \t\f\v\u00a0\ufeff]+")),
+    (Kind.NEWLINE, re.compile(r"\r\n|\r|\n")),
+    # Like OpenSCAD's lexer, a line comment ends at LF only; a trailing CR is stripped on output.
+    (Kind.LINE_COMMENT, re.compile(r"//[^\n]*")),
+    (Kind.BLOCK_COMMENT, re.compile(r"/\*.*?\*/", re.S)),
+    (Kind.STRING, re.compile(r'"(?:\\.|[^"\\])*"', re.S)),
+    (Kind.NUMBER, re.compile(r"0[xX][0-9A-Fa-f]+|(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?")),
+    # `$`, `$1` and Unicode letters (behind --enable=unicode-identifiers) are valid OpenSCAD identifiers too.
+    (Kind.IDENT, re.compile(r"\$\w*|[^\W\d]\w*")),
+    (Kind.OP, re.compile("|".join(re.escape(op) for op in OPERATORS))),
+]
+
+# `include <path>` and `use <path>` take a path, not an expression.
+_PATH = re.compile(r"<[^>\r\n]*>")
+_PATH_KEYWORDS = ("include", "use")
+_IDENT_CHAR = re.compile(r"[^\W\d]|\$")
+
+
+def tokenize(source: str) -> list[Token]:
+    """Split source into tokens, dropping spaces and tabs but keeping newlines.
+
+    Args:
+        source: OpenSCAD source text.
+
+    Returns:
+        The tokens in source order.
+
+    Raises:
+        TokenizeError: On a character that starts no known token, or an unterminated string or comment.
+    """
+    tokens: list[Token] = []
+    pos, line, line_start = 0, 1, 0
+    while pos < len(source):
+        col = pos - line_start + 1
+        previous = _last_significant(tokens)
+        if previous and previous.kind == Kind.IDENT and previous.text in _PATH_KEYWORDS:
+            match = _PATH.match(source, pos)
+            if match:
+                tokens.append(Token(Kind.PATH, match.group(), line, col))
+                pos = match.end()
+                continue
+        for kind, pattern in _PATTERNS:
+            match = pattern.match(source, pos)
+            if match:
+                break
+        else:
+            raise TokenizeError(_unknown_message(source, pos, line, col))
+        if kind == Kind.OP and source.startswith("/*", pos):
+            raise TokenizeError(_unknown_message(source, pos, line, col))
+        if kind == Kind.NUMBER and _IDENT_CHAR.match(source, match.end()):
+            # OpenSCAD reads `1abc` as one (deprecated) identifier; splitting it would change the code.
+            raise TokenizeError(f"{line}:{col}: identifiers starting with a digit are not supported")
+        text = match.group()
+        if kind is not None:
+            tokens.append(Token(kind, "\n" if kind == Kind.NEWLINE else text, line, col))
+        newlines = 1 if kind == Kind.NEWLINE else text.count("\n")
+        if newlines:
+            line += newlines
+            line_start = pos + len(text) if kind == Kind.NEWLINE else pos + text.rfind("\n") + 1
+        pos = match.end()
+    return tokens
+
+
+def _last_significant(tokens: list[Token]) -> Token | None:
+    """Return the last token that is neither a newline nor a comment."""
+    for token in reversed(tokens):
+        if token.kind not in (Kind.NEWLINE, Kind.LINE_COMMENT, Kind.BLOCK_COMMENT):
+            return token
+    return None
+
+
+def _unknown_message(source: str, pos: int, line: int, col: int) -> str:
+    """Describe why tokenizing stopped at pos."""
+    if source.startswith("/*", pos):
+        return f"{line}:{col}: unterminated block comment"
+    if source[pos] == '"':
+        return f"{line}:{col}: unterminated string"
+    return f"{line}:{col}: unexpected character {source[pos]!r}"
+
+
+def significant(tokens: list[Token]) -> list[tuple[Kind, str]]:
+    """Reduce tokens to what must survive formatting unchanged.
+
+    Newlines drop out, and trailing whitespace inside comments is ignored because the formatter strips it.
+
+    Args:
+        tokens: Tokens from `tokenize`.
+
+    Returns:
+        (kind, text) pairs to compare before and after formatting.
+    """
+    result = []
+    for token in tokens:
+        if token.kind == Kind.NEWLINE:
+            continue
+        text = token.text
+        if token.kind in (Kind.LINE_COMMENT, Kind.BLOCK_COMMENT):
+            text = "\n".join(part.rstrip() for part in text.splitlines())
+        result.append((token.kind, text))
+    return result

scadfmt/vscode.py

@@ -0,0 +1,101 @@
+"""Register scadfmt as the VS Code formatter for OpenSCAD files."""
+
+import json
+import logging
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from scadfmt.fileio import write_atomically
+
+logger = logging.getLogger(__name__)
+
+EXTENSION = "jkillian.custom-local-formatters"
+LANGUAGE = "scad"
+
+
+def formatter_command() -> str:
+    """Command VS Code runs to format a document: this interpreter, so it works in any install location.
+
+    Returns:
+        A shell command reading source on stdin and writing it formatted to stdout.
+    """
+    return f'"{sys.executable}" -m scadfmt format -'
+
+
+def merge_settings(settings: dict) -> dict:
+    """Add the scadfmt formatter to VS Code settings, replacing any other formatter for `scad`.
+
+    Args:
+        settings: Existing settings.json content.
+
+    Returns:
+        The updated settings (the same dict).
+    """
+    formatters = [
+        entry
+        for entry in settings.get("customLocalFormatters.formatters", [])
+        if LANGUAGE not in entry.get("languages", [])
+    ]
+    formatters.append({"command": formatter_command(), "languages": [LANGUAGE]})
+    settings["customLocalFormatters.formatters"] = formatters
+    settings.setdefault(f"[{LANGUAGE}]", {})["editor.defaultFormatter"] = EXTENSION
+    return settings
+
+
+def _install_extension() -> bool:
+    """Install the Custom Local Formatters extension with the `code` CLI."""
+    if not shutil.which("code"):
+        logger.error("VS Code CLI 'code' not found. Install VS Code and enable 'Add to PATH'.")
+        return False
+    try:
+        subprocess.run(
+            ["code", "--install-extension", EXTENSION, "--force"],
+            check=True,
+            capture_output=True,
+            text=True,
+            # code is a .cmd script on Windows, which only the shell resolves.
+            shell=platform.system() == "Windows",
+        )
+    except subprocess.CalledProcessError as e:
+        logger.error("Failed to install %s: %s", EXTENSION, e.stderr)
+        return False
+    logger.info("Installed %s", EXTENSION)
+    return True
+
+
+def setup_vscode(workspace: Path) -> bool:
+    """Install the extension and point it at scadfmt in the workspace settings.
+
+    Args:
+        workspace: Workspace folder; its .vscode/settings.json is created or updated.
+
+    Returns:
+        True on success, False otherwise.
+    """
+    settings_file = workspace / ".vscode" / "settings.json"
+    settings = {}
+    if settings_file.exists():
+        try:
+            settings = json.loads(settings_file.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as e:
+            # Comments or trailing commas: refuse rather than overwrite hand-written settings.
+            logger.error(
+                "%s is not plain JSON (%s). Add the settings from the scadfmt README by hand.", settings_file, e
+            )
+            return False
+        except (OSError, UnicodeDecodeError) as e:
+            logger.error("Cannot read %s: %s", settings_file, e)
+            return False
+    if not _install_extension():
+        return False
+    try:
+        settings_file.parent.mkdir(parents=True, exist_ok=True)
+        write_atomically(settings_file, json.dumps(merge_settings(settings), indent=2, sort_keys=True) + "\n")
+    except OSError as e:
+        logger.error("Cannot write %s: %s", settings_file, e)
+        return False
+    logger.info("Updated %s, scadfmt now formats .scad files (Format Document)", settings_file)
+    return True

scadfmt-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: scadfmt
+Version: 0.1.0
+Summary: Opinionated formatter for OpenSCAD code
+Author-email: Patrick Pötz <kellervater@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kellerlabs/homeracker
+Project-URL: Repository, https://github.com/kellerlabs/homeracker
+Project-URL: Documentation, https://github.com/kellerlabs/homeracker/tree/main/cmd/scadfmt
+Project-URL: Issues, https://github.com/kellerlabs/homeracker/issues
+Project-URL: Changelog, https://github.com/kellerlabs/homeracker/blob/main/cmd/scadfmt/CHANGELOG.md
+Keywords: openscad,formatter,scad,code-style,pre-commit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# 🎨 scadfmt
+
+## 📌 What
+
+An opinionated formatter for OpenSCAD code. It fixes indentation and spacing, puts blocks and statements on their own lines, and never joins lines or changes what the code does.
+
+## 🤔 Why
+
+Community contributions need one code style without style debates in review. Existing formatters rewrite code they do not understand (dropping operators, breaking `include` paths) or join hand-wrapped lines into very long ones. scadfmt only needs to know OpenSCAD's tokens, so new syntax rarely affects it, and it refuses to write output whose tokens differ from the input. See [build-own-openscad-formatter-scadfmt](../../docs/decisions/build-own-openscad-formatter-scadfmt.md).
+
+## 🔧 How
+
+### 📦 Install
+
+Requires Python 3.11 or newer, no other dependencies.
+
+```bash
+pip install scadfmt           # from PyPI
+pip install -e cmd/scadfmt    # from this repo
+```
+
+### ▶️ Usage
+
+```bash
+scadfmt format models/                  # format files in place, directories recursively
+scadfmt format --check models/          # write nothing, exit 1 if a file would change
+scadfmt format --diff part.scad         # write nothing, print a diff
+scadfmt format - < in.scad > out.scad   # stdin to stdout
+```
+
+Exit codes: `0` clean, `1` files would change (`--check`), `2` error. On an error (unknown character, unbalanced brackets) the file stays untouched.
+
+### 👀 Before and After
+
+```openscad
+include<BOSL2/std.scad>
+wall=2;// wall strength
+height_units=3; // rack units
+/**
+ * Bracket holding a device of the given size.
+ * center: centers the body on the origin
+ */
+module bracket(width=10,depth=20,center=false){
+    size=[width,depth,wall*height_units];
+    if(center){translate(-size/2)cube(size);}else{cube(size);}
+    for(i=[0:2:width])
+    translate([i,0,0])
+    rotate([0,0,-90])
+    #cylinder(h=wall,r=1);
+}
+```
+
+becomes
+
+```openscad
+include <BOSL2/std.scad>
+
+wall = 2;          // wall strength
+height_units = 3;  // rack units
+
+/**
+ * Bracket holding a device of the given size.
+ * center: centers the body on the origin
+ */
+module bracket(width = 10, depth = 20, center = false) {
+  size = [width, depth, wall * height_units];
+  if (center) {
+    translate(-size / 2) cube(size);
+  } else {
+    cube(size);
+  }
+  for (i = [0:2:width])
+    translate([i, 0, 0])
+      rotate([0, 0, -90])
+        #cylinder(h = wall, r = 1);
+}
+```
+
+### 📏 Rules
+
+| Rule | Example |
+|---|---|
+| 2 spaces per open `{ ( [`, one level per line that opens them | `cube([`↵`  1,`↵`]);` |
+| A line continuing a module call nests one level further | `translate(v)`↵`  cube();` |
+| A line continuing an expression is one level in | `x =`↵`  a +`↵`  b;` |
+| Spaces around every binary operator and every `=` | `cube(size = w * 2, center = true);` |
+| Tight unary operators, modifiers, calls, indexing | `-x`, `!a`, `#cube()`, `f(a)[0]` |
+| Tight range colons, spaced ternary colons | `[0:2:10]`, `a ? b : c` |
+| `if`, `for`, `intersection_for`, `function` get a space before `(` | `for (i = [0:2])` |
+| Space after commas, none inside brackets | `f(a, [1, 2])` |
+| Block contents on their own lines, `}` on its own line except `} else`, empty `{}` stays | `if (a) {`↵`  b();`↵`} else {` |
+| One statement per line (`;` inside `for (...)` excepted) | `a();`↵`b();` |
+| Exactly one blank line before and after each `module` and `function` definition, none next to a brace | `x = 1;`↵↵`module m() {` |
+| Imports form one block without blank lines, followed by exactly one blank line | `include <a.scad>`↵`use <b.scad>`↵↵`x = 1;` |
+| Trailing comments on consecutive lines share one column, a lone one gets 2 spaces | `x = 1;  // note` |
+| At most 2 blank lines at top level, 1 inside blocks | |
+| Keeps the file's line endings (LF or CRLF, judged by the first one), no trailing whitespace, one final newline | |
+
+Comments (`//` or `/* */`) directly above a line belong to it, so a blank line added before that line goes above its comments. Lines are never joined and line length is never limited.
+
+### 🙈 Opting Out
+
+Lines between `// fmt: off` and `// fmt: on` stay as written, for example a hand-aligned matrix:
+
+```openscad
+// fmt: off
+identity = [
+  1, 0, 0,
+  0, 1, 0,
+];
+// fmt: on
+```
+
+### 🪝 Pre-commit
+
+In another repository, install scadfmt from PyPI through a local hook:
+
+```yaml
+- repo: local
+  hooks:
+    - id: scadfmt
+      name: scadfmt
+      entry: scadfmt format
+      language: python
+      additional_dependencies: [scadfmt==0.1.0]
+      files: \.scad$
+```
+
+### 🖥️ VS Code
+
+```bash
+scadfmt vscode
+```
+
+Installs the [Custom Local Formatters](https://marketplace.visualstudio.com/items?itemName=jkillian.custom-local-formatters) extension and makes scadfmt the default formatter for `.scad` files in `.vscode/settings.json`, so **Format Document** (`Shift+Alt+F`) runs it. It refuses to touch a `settings.json` with comments; add the settings by hand then:
+
+```jsonc
+"customLocalFormatters.formatters": [{ "command": "\"/path/to/python\" -m scadfmt format -", "languages": ["scad"] }],
+"[scad]": { "editor.defaultFormatter": "jkillian.custom-local-formatters" }
+```
+
+For formatting on save, add `"editor.formatOnSave": true` to the `[scad]` block.
+
+### 🧪 Tests
+
+See [TESTING.md](../../TESTING.md#scadfmt-tests). `tests/canary/` holds a file using every OpenSCAD construct and its expected output; `check.sh` checks both against the pinned OpenSCAD.
+
+## 📚 References
+
+- [#177](https://github.com/kellerlabs/homeracker/issues/177): introduce an OpenSCAD formatter
+- [build-own-openscad-formatter-scadfmt](../../docs/decisions/build-own-openscad-formatter-scadfmt.md): why scadfmt exists and how it works
+- [OpenSCAD language reference](https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_Language)

scadfmt-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+scadfmt/__init__.py,sha256=GZdF8FtTWfRy-vEOcNUDVq0rNpauamj8QmIJAmWD1m4,320
+scadfmt/__main__.py,sha256=PAqkKibwVb-FpUwreY-Q1aBtFz0RvRb8bDCq8qOtHSc,102
+scadfmt/cli.py,sha256=4s1EzV9UL9W6PCgjtTF_8US6Z6bDI-MQXrUeZPhSY4Q,4948
+scadfmt/fileio.py,sha256=I08qEcmRBXteS0DuL5Mn2nTE3DLYBWSF6iK8lbcU2CM,1069
+scadfmt/formatter.py,sha256=tTSLIMFwJMwTnu9wGNTCx2a6XrWdP5MY9rjJnCvRm_A,20587
+scadfmt/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scadfmt/tokenizer.py,sha256=KxIj2zad0j7xtE6XcxOeAz1uUHb5txFNc0FD7Pk1xL4,5366
+scadfmt/vscode.py,sha256=cMfCHlOaRkrxe1mW6tZaaVH_3wSTocy9NPL_wcDkmWY,3490
+scadfmt-0.1.0.dist-info/METADATA,sha256=EP2BFsguGJS-debMeXW1PG3kJGtIABnNd6W3hNFMpPU,6841
+scadfmt-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+scadfmt-0.1.0.dist-info/entry_points.txt,sha256=MNxTqcXqMiB80h0q1-ddIUzf1GKkGDh0VvE9vcNSB2Y,45
+scadfmt-0.1.0.dist-info/top_level.txt,sha256=y7TxvZfW2J1BC0CZQLOElr70tIDFpQcP1PLGPw_pVYo,8
+scadfmt-0.1.0.dist-info/RECORD,,

scadfmt-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

scadfmt-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scadfmt = scadfmt.cli:main

scadfmt-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+scadfmt