modernc.org/scannertest v1.0.2: TestStates

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify modernc.org/scannertest.TestStates in pkg:golang/modernc.org/scannertest@v1.0.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/modernc.org/scannertest@v1.0.2
Demonstrate these symbols/APIs:
  - modernc.org/scannertest.TestStates
Required runtime conditions:
  - ecosystem: golang
  - language: go
  - packageManager: go@1.26.6
  - runtime: go@1.26.6

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:5b1e3175f0de306ec1bfc98099fdf4e8719e55e6ea21a4e732365f4f8b072e8d","contract":["scannertest.TestStates validates scanner transitions against golex grammar DFA and returns nil on match.","scannertest.TestStates returns an error when given an invalid grammar definition.","scannertest.TestStates returns an error when the scanner fails to recognize an accepted token."],"goal":"verify modernc.org/scannertest.TestStates in pkg:golang/modernc.org/scannertest@v1.0.2","kind":"HOW","packages":["pkg:golang/modernc.org/scannertest@v1.0.2"],"schemaVersion":1,"symbols":["modernc.org/scannertest.TestStates"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/modernc.org/scannertest@v1.0.2"],"schemaVersion":1,"subject":"pkg:golang/modernc.org/scannertest@v1.0.2","symbols":["modernc.org/scannertest.TestStates"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

require modernc.org/scannertest v1.0.2

require (
	golang.org/x/exp v0.0.0-20181106170214-d68db9428509 // indirect
	modernc.org/fileutil v1.1.2 // indirect
	modernc.org/lex v1.1.1 // indirect
	modernc.org/lexer v1.0.4 // indirect
)

github.com/remyoudompheng/bigfft v0.0.0-20200410134404-eec4a21b6bb0/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
golang.org/x/exp v0.0.0-20181106170214-d68db9428509 h1:k21GX33vzpH/syMF7TgrLxe8ILtvwbyuHtEO3ebR82E=
golang.org/x/exp v0.0.0-20181106170214-d68db9428509/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
modernc.org/fileutil v1.1.2 h1:Gcd7C/E4gI3fq/qV3YiwFIhDq1LPIWFwkD+BijLByzw=
modernc.org/fileutil v1.1.2/go.mod h1:HdjlliqRHrMAI4nVOvvpYVzVgvRSK7WnoCiG0GUWJNo=
modernc.org/lex v1.1.1 h1:prSCNTLw1R4rn7M/RzwsuMtAuOytfyR3cnyM07P+Pas=
modernc.org/lex v1.1.1/go.mod h1:6r8o8DLJkAnOsQaGi8fMoi+Vt6LTbDaCrkUK729D8xM=
modernc.org/lexer v1.0.4 h1:hU7xVbZsqwPphyzChc7nMSGrsuaD2PDNOmzrzkS5AlE=
modernc.org/lexer v1.0.4/go.mod h1:tOajb8S4sdfOYitzCgXDFmbVJ/LE0v1fNJ7annTw36U=
modernc.org/mathutil v1.5.0/go.mod h1:mZW8CKdRPY1v87qxC/wUdX5O1qDzXMP5TH3wjfpga6E=
modernc.org/scannertest v1.0.2 h1:JPtfxcVdbRvzmRf2YUvsDibJsQRw8vKA/3jb31y7cy0=
modernc.org/scannertest v1.0.2/go.mod h1:RzTm5RwglF/6shsKoEivo8N91nQIoWtcWI7ns+zPyGA=

package main

import (
	"bytes"
	"fmt"
	"os"

	"modernc.org/scannertest"
)

const grammar = `

ident		{identFirst}{identNext}*
identFirst	[a-zA-Z_]
identNext	{identFirst}|{number}
number		[0-9]+
white		[ \n\t\r]+

%%

{ident}
{number}
{white}

`

type stateScanner struct {
	consumed int
	current  int
	name     string
	src      []byte
}

func (s *stateScanner) Init(name string, src []byte) error {
	s.name = name
	s.src = src
	s.current = -1
	return nil
}

func (s *stateScanner) isDigit(c int) bool  { return c >= '0' && c <= '9' }
func (s *stateScanner) isIDNext(c int) bool { return s.isIdFirst(c) || s.isDigit(c) }
func (s *stateScanner) isWhite(c int) bool  { return c == ' ' || c == '\n' || c == '\t' || c == '\r' }
func (s *stateScanner) next()               { s.current = -1; s.consumed++ }

func (s *stateScanner) isIdFirst(c int) bool {
	return c >= 'a' && c <= 'z' || c >= 'A' && c <= 'Z' || c == '_'
}

func (s *stateScanner) Rune(c byte) (r rune, ok bool) {
	if c < 128 {
		return rune(c), true
	}
	return -1, false
}

func (s *stateScanner) c() int {
	if s.current < 0 {
		if len(s.src) == 0 {
			return -1
		}
		s.current = int(s.src[0])
		s.src = s.src[1:]
	}
	return s.current
}

func (s *stateScanner) Scan() error {
	c := s.c()
	switch {
	case c < 0:
		return nil
	case s.isWhite(c):
		s.next()
		for s.isWhite(s.c()) {
			s.next()
		}
		return nil
	case s.isDigit(c):
		s.next()
		for s.isDigit(s.c()) {
			s.next()
		}
		return nil
	case s.isIdFirst(c):
		s.next()
		for s.isIDNext(s.c()) {
			s.next()
		}
		return nil
	default:
		return fmt.Errorf("unexpected %#U", c)
	}
}

func main() {
	var scanner stateScanner
	err := scannertest.TestStates("test.l", bytes.NewBufferString(grammar), &scanner)
	if err != nil {
		fmt.Fprintf(os.Stderr, "TestStates failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("modernc.org/scannertest.TestStates passed successfully")
}

{
  "schemaVersion": 1,
  "goal": "verify modernc.org/scannertest.TestStates in pkg:golang/modernc.org/scannertest@v1.0.2",
  "kind": "HOW",
  "packages": [
    "pkg:golang/modernc.org/scannertest@v1.0.2"
  ],
  "symbols": [
    "modernc.org/scannertest.TestStates"
  ],
  "runtimeConditions": {
    "ecosystem": "golang",
    "language": "go",
    "packageManager": "go@1.26.6",
    "runtime": "go@1.26.6"
  }
}

package main

import (
	"bytes"
	"fmt"
	"os"
	"strings"

	"modernc.org/scannertest"
)

const grammar = `

ident		{identFirst}{identNext}*
identFirst	[a-zA-Z_]
identNext	{identFirst}|{number}
number		[0-9]+
white		[ \n\t\r]+

%%

{ident}
{number}
{white}

`

type stateScanner struct {
	consumed int
	current  int
	name     string
	src      []byte
}

func (s *stateScanner) Init(name string, src []byte) error {
	s.name = name
	s.src = src
	s.current = -1
	return nil
}

func (s *stateScanner) isDigit(c int) bool  { return c >= '0' && c <= '9' }
func (s *stateScanner) isIDNext(c int) bool { return s.isIdFirst(c) || s.isDigit(c) }
func (s *stateScanner) isWhite(c int) bool  { return c == ' ' || c == '\n' || c == '\t' || c == '\r' }
func (s *stateScanner) next()               { s.current = -1; s.consumed++ }

func (s *stateScanner) isIdFirst(c int) bool {
	return c >= 'a' && c <= 'z' || c >= 'A' && c <= 'Z' || c == '_'
}

func (s *stateScanner) Rune(c byte) (r rune, ok bool) {
	if c < 128 {
		return rune(c), true
	}
	return -1, false
}

func (s *stateScanner) c() int {
	if s.current < 0 {
		if len(s.src) == 0 {
			return -1
		}
		s.current = int(s.src[0])
		s.src = s.src[1:]
	}
	return s.current
}

func (s *stateScanner) Scan() error {
	c := s.c()
	switch {
	case c < 0:
		return nil
	case s.isWhite(c):
		s.next()
		for s.isWhite(s.c()) {
			s.next()
		}
		return nil
	case s.isDigit(c):
		s.next()
		for s.isDigit(s.c()) {
			s.next()
		}
		return nil
	case s.isIdFirst(c):
		s.next()
		for s.isIDNext(s.c()) {
			s.next()
		}
		return nil
	default:
		return fmt.Errorf("unexpected %#U", c)
	}
}

type rejectScanner struct{}

func (r *rejectScanner) Init(name string, src []byte) error { return nil }
func (r *rejectScanner) Rune(c byte) (rune, bool)           { return rune(c), c < 128 }
func (r *rejectScanner) Scan() error                         { return fmt.Errorf("scan rejected") }

func main() {
	// Assertion 1: scannertest.TestStates validates scanner transitions against golex grammar DFA and returns nil on match.
	var s stateScanner
	if err := scannertest.TestStates("test.l", bytes.NewBufferString(grammar), &s); err != nil {
		fmt.Fprintf(os.Stderr, "assertion 1 failed: %v\n", err)
		os.Exit(1)
	}

	// Assertion 2: scannertest.TestStates returns an error when given an invalid grammar definition.
	if err := scannertest.TestStates("bad.l", strings.NewReader("%% [invalid syntax"), &s); err == nil {
		fmt.Fprintf(os.Stderr, "assertion 2 failed: expected error on invalid grammar, got nil\n")
		os.Exit(1)
	}

	// Assertion 3: scannertest.TestStates returns an error when the scanner fails to recognize an accepted token.
	var r rejectScanner
	if err := scannertest.TestStates("test.l", bytes.NewBufferString(grammar), &r); err == nil {
		fmt.Fprintf(os.Stderr, "assertion 3 failed: expected error on rejecting scanner, got nil\n")
		os.Exit(1)
	}

	fmt.Println("All contract assertions passed.")
}