pawnfmt

README

pawnfmt

A fast, deterministic formatter for Pawn (SA-MP / open.mp) source: .pwn and .inc files.

With no paths, pawnfmt discovers the nearest Pawn project and formats it. Explicit files and stdin remain project-independent.

Install

Download a prebuilt binary from GitHub Releases. Release archives are built for Linux, macOS, and Windows on amd64 and arm64.

If you already have Go installed, you can also install from source:

go install github.com/pawnkit/pawnfmt/cmd/pawnfmt@latest

Use a version tag instead of latest when you want reproducible CI builds:

go install github.com/pawnkit/pawnfmt/cmd/pawnfmt@<tag>

Usage

Format files in place:

pawnfmt --write gamemodes includes

Check formatting without changing files:

pawnfmt --check gamemodes includes

Print a diff:

pawnfmt --diff script.pwn

Editor and CI integration

Call pawnfmt directly from your editor or CI:

pawnfmt --check gamemodes includes

For Git hooks, choose the hook manager that fits your project:

• Lefthook
• prek
• pre-commit

Lefthook:

pre-commit:
  jobs:
    - run: pawnfmt --write {staged_files}
      glob: "*.{pwn,inc}"
      stage_fixed: true

prek:

repos:
  - repo: local
    hooks:
      - id: pawnfmt
        name: pawnfmt
        entry: pawnfmt --write
        language: system
        files: \.(pwn|inc)$

pre-commit:

- repo: https://github.com/pawnkit/pawnfmt
  rev: <tag>
  hooks:
    - id: pawnfmt

A plain Git hook also works if you do not want a hook manager:

#!/bin/sh
pawnfmt --check gamemodes includes

Save it as .git/hooks/pre-commit and make it executable.

Configuration

Create a commented config with every default:

pawnfmt --init-config

See the configuration reference for discovery, inheritance, EditorConfig, and available options. Development and less common CLI behavior are covered in project notes.

Go package

Tools can format source without running the CLI:

formatted, err := pawnfmt.Format(source, pawnfmt.Options{TabSize: 4})

The zero options use pawnfmt's defaults. Set UseTabs to use tab indentation.

Contributing

Formatting reports with a short input and expected output are especially useful. See CONTRIBUTING.md.

Documentation

Overview

Package pawnfmt exposes Pawn source formatting.

Index

• func Format(source []byte, opts Options) ([]byte, error)
• type Options
• type ParseMode
• type Range
• type RangeResult
  • func FormatRange(source []byte, start, end int, opts Options) (RangeResult, error)

Functions

func Format

func Format(source []byte, opts Options) ([]byte, error)

Format formats a complete Pawn source file.

Types

type Options

type Options struct {
	TabSize   int
	UseTabs   bool
	ParseMode ParseMode
}

Options controls library formatting.

type ParseMode

type ParseMode string

ParseMode controls how formatting handles parser errors.

const (
	ParseModeStrict   ParseMode = "strict"
	ParseModeTolerant ParseMode = "tolerant"
)

Parse modes accepted by Options.

type Range

type Range struct {
	Start int
	End   int
}

Range is a byte range in the original source.

type RangeResult

type RangeResult struct {
	Source         []byte
	FormattedRange Range
}

RangeResult contains formatted source and the replaced range.

func FormatRange

func FormatRange(source []byte, start, end int, opts Options) (RangeResult, error)

FormatRange formats the top-level syntax unit containing the range.