modernc.org/scannertest v1.0.2

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 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
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:811e32e2d1474d01e9f2cfd6f56eb2e6c69db485bf6b28b821e742fe7d2692ec","contract":["scannertest.TestStates executes DFA state transitions against a conforming scannertest.Interface implementation.","scannertest.TestStates passes when the scanner correctly recognizes valid token prefixes generated from the grammar.","scannertest.TestStates returns an error when a non-conforming scanner rejects valid tokens or fails to scan.","scannertest.TestStates returns an error when provided with an invalid or malformed grammar specification."],"goal":"verify pkg:golang/modernc.org/scannertest@v1.0.2","kind":"HOW","packages":["pkg:golang/modernc.org/scannertest@v1.0.2"],"schemaVersion":1},"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","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 exampleGrammar = `
word    [a-zA-Z]+
number  [0-9]+
ws      [ \t\n\r]+

%%

{word}
{number}
{ws}
`

type exampleScanner struct {
	src []byte
	cur int
}

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

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

func (s *exampleScanner) peek() int {
	if s.cur < 0 {
		if len(s.src) == 0 {
			return -1
		}
		s.cur = int(s.src[0])
		s.src = s.src[1:]
	}
	return s.cur
}

func (s *exampleScanner) advance() {
	s.cur = -1
}

func (s *exampleScanner) Scan() error {
	c := s.peek()
	switch {
	case c < 0:
		return nil
	case c == ' ' || c == '\t' || c == '\n' || c == '\r':
		s.advance()
		for p := s.peek(); p == ' ' || p == '\t' || p == '\n' || p == '\r'; p = s.peek() {
			s.advance()
		}
		return nil
	case (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z'):
		s.advance()
		for p := s.peek(); (p >= 'a' && p <= 'z') || (p >= 'A' && p <= 'Z'); p = s.peek() {
			s.advance()
		}
		return nil
	case c >= '0' && c <= '9':
		s.advance()
		for p := s.peek(); p >= '0' && p <= '9'; p = s.peek() {
			s.advance()
		}
		return nil
	default:
		return fmt.Errorf("unexpected char: %c", c)
	}
}

func main() {
	var scanner exampleScanner
	err := scannertest.TestStates("example", bytes.NewBufferString(exampleGrammar), &scanner)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Scanner validation failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("Scanner validation succeeded.")
}

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

package main

import (
	"bytes"
	"fmt"
	"os"

	"modernc.org/scannertest"
)

const validGrammar = `
ident   [a-zA-Z_][a-zA-Z0-9_]*
number  [0-9]+
white   [ \t\n\r]+

%%

{ident}
{number}
{white}
`

type scannerImpl struct {
	src     []byte
	current int
}

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

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

func (s *scannerImpl) 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 *scannerImpl) next() {
	s.current = -1
}

func (s *scannerImpl) isWhite(c int) bool {
	return c == ' ' || c == '\t' || c == '\n' || c == '\r'
}

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

func (s *scannerImpl) isDigit(c int) bool {
	return c >= '0' && c <= '9'
}

func (s *scannerImpl) 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.isAlpha(c):
		s.next()
		for s.isAlpha(s.c()) || s.isDigit(s.c()) {
			s.next()
		}
		return nil
	case s.isDigit(c):
		s.next()
		for s.isDigit(s.c()) {
			s.next()
		}
		return nil
	default:
		return fmt.Errorf("unexpected character: %c", c)
	}
}

// faultyScanner rejects digits to simulate scanner non-conformance
type faultyScanner struct {
	scannerImpl
}

func (s *faultyScanner) Scan() error {
	c := s.c()
	if s.isDigit(c) {
		return fmt.Errorf("faultyScanner rejecting digit")
	}
	return s.scannerImpl.Scan()
}

func main() {
	// Assertion 1: scannertest.TestStates executes DFA state transitions against a conforming scannertest.Interface implementation.
	// Assertion 2: scannertest.TestStates passes when the scanner correctly recognizes valid token prefixes generated from the grammar.
	var scanner scannerImpl
	if err := scannertest.TestStates("validGrammar", bytes.NewBufferString(validGrammar), &scanner); err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: conforming scanner failed TestStates: %v\n", err)
		os.Exit(1)
	}

	// Assertion 3: scannertest.TestStates returns an error when a non-conforming scanner rejects valid tokens or fails to scan.
	var faulty faultyScanner
	if err := scannertest.TestStates("validGrammar", bytes.NewBufferString(validGrammar), &faulty); err == nil {
		fmt.Fprintf(os.Stderr, "FAIL: expected error for faultyScanner, got nil\n")
		os.Exit(1)
	}

	// Assertion 4: scannertest.TestStates returns an error when provided with an invalid or malformed grammar specification.
	invalidGrammar := "%% invalid [["
	var dummy scannerImpl
	if err := scannertest.TestStates("invalid", bytes.NewBufferString(invalidGrammar), &dummy); err == nil {
		fmt.Fprintf(os.Stderr, "FAIL: expected error on invalid grammar, got nil\n")
		os.Exit(1)
	}

	fmt.Println("PASS: all scannertest contract assertions passed.")
}