From e78556fc332a61f3b56de926e4ca910f90ee7a7d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Olivier=20Mengu=C3=A9?= <dolmen@cpan.org>
Date: Mon, 18 May 2026 15:48:40 +0200
Subject: [PATCH] README.md: rework to show how to use 'peg' via 'go tool'

Rework README.md in a go1.24+ era where tools versionning is managed in
go.mod. Users are now instructed to install peg via 'go get -tool',
and execute via 'go tool'.

References:
- https://go.dev/doc/modules/managing-dependencies#tools
- https://pkg.go.dev/cmd/go#hdr-Run_specified_go_tool
---
 README.md | 38 ++++++++++++++++++--------------------
 1 file changed, 18 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 60733f6..7799776 100644
--- a/README.md
+++ b/README.md
@@ -5,46 +5,44 @@
 
 A [Parsing Expression Grammar](https://en.wikipedia.org/wiki/Parsing_expression_grammar) ( hence `peg`) is a way to create grammars similar in principle to [regular expressions](https://en.wikipedia.org/wiki/Regular_expression) but which allow better code integration. Specifically, `peg` is an implementation of the [Packrat](https://en.wikipedia.org/wiki/Parsing_expression_grammar#Implementing_parsers_from_parsing_expression_grammars) parser generator originally implemented as [peg/leg](https://www.piumarta.com/software/peg/) by [Ian Piumarta](https://www.piumarta.com/cv/) in C. A Packrat parser is a "descent recursive parser" capable of backtracking and negative look-ahead assertions which are problematic for regular expression engines.
 
-## Installation
+## PEG file syntax
 
-```
-go install github.com/pointlander/peg@latest
-```
+See [peg-file-syntax.md](docs/peg-file-syntax.md)
 
 
 ## Usage
 
-### Build executable
-
+1. Add `peg` as a [tool](https://go.dev/doc/modules/managing-dependencies#tools) in your Go module:
+```console
+$ go get -tool github.com/pointlander/peg@main
 ```
-go generate && go build
-```
-
-### Help
-
+2. Create your `mygrammar.peg` file (see [doc](docs/peg-file-syntax.md))
+3. Add a `//go:generate` line in a Go source of your package (idiom is `doc.go`):
+```go
+//go:generate go tool peg mygrammar.peg
 ```
-./peg -h
+3. Run `go generate` to generate `mygrammar.peg.go` from `mygrammar.peg`
+```console
+$ go generate
 ```
 
-
 ### Example
 
 This creates the file `peg.peg.go`:
 ```
-./peg -inline -switch peg.peg
+$ go tool peg -inline -switch peg.peg
 ```
 
-
-## PEG file syntax
-
-See [peg-file-syntax.md](docs/peg-file-syntax.md)
-
+### Help
+```
+$ go tool peg -h
+```
 
 ## Development
 
 ### Requirements
 
-* [Golang](https://golang.org/doc/install), see [go.mod](go.mod) for version
+* [Golang](https://go.dev/doc/install), see [go.mod](go.mod) for version
 * [golangci-lint latest version](https://github.com/golangci/golangci-lint#install) (v2 or later)
 * [Bash 3.2.x or higher](https://www.gnu.org/software/bash)