feat: add example cli tool

Author: UltiRequiem

README.md

@@ -121,22 +121,48 @@ func AllWords() []string
 
 Every known word, sorted. Returns a copy — safe to mutate.
 
+## CLI Tool
+
+`cmd/thesaurus` is a small example CLI over the package's own API — stdlib only,
+no dependencies:
+
+```bash
+go install github.com/bobadilla-tech/thesaurus-go/cmd/thesaurus@latest
+```
+
+```bash
+$ thesaurus lookup happy
+Synonyms: [joyful cheerful content pleased delighted glad elated blissful]
+Antonyms: [sad unhappy miserable sorrowful dejected gloomy melancholy]
+
+$ thesaurus prefix happ
+happen
+happening
+happenstance
+happily
+happiness
+happy
+
+$ thesaurus count
+45695
+```
+
 ## How It Works
 
 1. **Normalize**: input words are trimmed and converted to lowercase.
 2. **Curated lookup**: a small hand-maintained dataset is checked first. Curated
    entries always take precedence over OEWN.
-3. \*_OEWN fallback_: if the word is not present in the curated dataset,
+3. **OEWN fallback**: if the word is not present in the curated dataset,
    synonyms and antonyms are resolved from the embedded Open English WordNet
    indexes.
 4. **Embedded data**: the generated JSON indexes are gzip-compressed and
    embedded into the binary using `go:embed`.
 
 ## Regenerating the Dataset
 
-The repository includes a build-time parser located in `cmd/wnparser`. Data
-sources are pluggable through a `Provider` interface (see
-`cmd/wnparser/provider.go`) — `oewn` is the only one implemented today, but
+The repository includes a build-time preprocessor located in `cmd/datasetbuild`.
+Data sources are pluggable through a `Provider` interface (see
+`cmd/datasetbuild/provider.go`) — `oewn` is the only one implemented today, but
 adding another means implementing `Provider` and registering it, with no changes
 to `main()`.
 
@@ -146,7 +172,7 @@ format) and generates the compressed JSON files embedded by the package.
 Example:
 
 ```bash
-go run ./cmd/wnparser \
+go run ./cmd/datasetbuild \
   -input english-wordnet-2025.xml \
   -output-dir ./dataset \
   -provider oewn

cmd/thesaurus/commands.go

@@ -0,0 +1,36 @@
+package main
+
+import (
+	"fmt"
+	"io"
+
+	thesaurus "github.com/bobadilla-tech/thesaurus-go"
+)
+
+// runLookup prints the synonyms and antonyms for word, or returns an error
+// if word has no entry.
+func runLookup(word string, out io.Writer) error {
+	entry, ok := thesaurus.Lookup(word)
+	if !ok {
+		return fmt.Errorf("%q: not found", word)
+	}
+
+	fmt.Fprintln(out, "Synonyms:", entry.Synonyms)
+	fmt.Fprintln(out, "Antonyms:", entry.Antonyms)
+	return nil
+}
+
+// runPrefix prints every known word starting with prefix, one per line.
+func runPrefix(prefix string, out io.Writer) error {
+	matches := thesaurus.WordsWithPrefix(prefix)
+	for _, word := range matches {
+		fmt.Fprintln(out, word)
+	}
+	return nil
+}
+
+// runCount prints the total number of words the dataset can look up.
+func runCount(out io.Writer) error {
+	fmt.Fprintln(out, thesaurus.Count())
+	return nil
+}

cmd/thesaurus/commands_test.go

@@ -0,0 +1,66 @@
+package main
+
+import (
+	"bytes"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	thesaurus "github.com/bobadilla-tech/thesaurus-go"
+)
+
+func TestRunLookup_KnownWord(t *testing.T) {
+	var buf bytes.Buffer
+
+	err := runLookup("happy", &buf)
+
+	require.NoError(t, err)
+	out := buf.String()
+	assert.Contains(t, out, "Synonyms:")
+	assert.Contains(t, out, "Antonyms:")
+}
+
+func TestRunLookup_UnknownWord(t *testing.T) {
+	var buf bytes.Buffer
+
+	err := runLookup("zzzznotaword", &buf)
+
+	assert.Error(t, err, "expected an error for an unknown word")
+	assert.Empty(t, buf.String(), "should not print anything for an unknown word")
+}
+
+func TestRunPrefix_KnownPrefix(t *testing.T) {
+	var buf bytes.Buffer
+
+	err := runPrefix("happ", &buf)
+
+	require.NoError(t, err)
+	lines := strings.Fields(buf.String())
+	assert.NotEmpty(t, lines)
+	for _, w := range lines {
+		assert.True(t, strings.HasPrefix(w, "happ"), "%q does not start with 'happ'", w)
+	}
+}
+
+func TestRunPrefix_UnknownPrefix(t *testing.T) {
+	var buf bytes.Buffer
+
+	err := runPrefix("zzzznotaprefix", &buf)
+
+	require.NoError(t, err, "an unmatched prefix is not an error")
+	assert.Empty(t, buf.String())
+}
+
+func TestRunCount_MatchesLibrary(t *testing.T) {
+	var buf bytes.Buffer
+
+	err := runCount(&buf)
+
+	require.NoError(t, err)
+	got, convErr := strconv.Atoi(strings.TrimSpace(buf.String()))
+	require.NoError(t, convErr)
+	assert.Equal(t, thesaurus.Count(), got)
+}

cmd/thesaurus/main.go

@@ -0,0 +1,59 @@
+// Command thesaurus is a small example CLI over the thesaurus package,
+// demonstrating Lookup, WordsWithPrefix, and Count from the terminal.
+//
+// Usage:
+//
+//	thesaurus lookup <word>
+//	thesaurus prefix <prefix>
+//	thesaurus count
+package main
+
+import (
+	"fmt"
+	"os"
+)
+
+func usage() {
+	fmt.Fprintln(os.Stderr, "usage:")
+	fmt.Fprintln(os.Stderr, "  thesaurus lookup <word>")
+	fmt.Fprintln(os.Stderr, "  thesaurus prefix <prefix>")
+	fmt.Fprintln(os.Stderr, "  thesaurus count")
+}
+
+func main() {
+	if len(os.Args) < 2 {
+		usage()
+		os.Exit(2)
+	}
+
+	var err error
+	switch cmd := os.Args[1]; cmd {
+	case "lookup":
+		if len(os.Args) != 3 {
+			usage()
+			os.Exit(2)
+		}
+		err = runLookup(os.Args[2], os.Stdout)
+	case "prefix":
+		if len(os.Args) != 3 {
+			usage()
+			os.Exit(2)
+		}
+		err = runPrefix(os.Args[2], os.Stdout)
+	case "count":
+		if len(os.Args) != 2 {
+			usage()
+			os.Exit(2)
+		}
+		err = runCount(os.Stdout)
+	default:
+		fmt.Fprintf(os.Stderr, "unknown command %q\n", cmd)
+		usage()
+		os.Exit(2)
+	}
+
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}

oewn_embed.go

@@ -37,7 +37,6 @@ var antonymsOEWNData map[string][]string
 var allWords []string
 
 func init() {
-
 	if err := json.Unmarshal(curatedRaw, &curatedData); err != nil {
 		panic(err)
 	}
@@ -50,20 +49,25 @@ func init() {
 
 func buildAllWords(curated map[string]Entry, synonymsOEWN, antonymsOEWN map[string][]string) []string {
 	seen := make(map[string]struct{}, len(curated)+len(synonymsOEWN)+len(antonymsOEWN))
+	
 	for word := range curated {
 		seen[word] = struct{}{}
 	}
+	
 	for word := range synonymsOEWN {
 		seen[word] = struct{}{}
 	}
+	
 	for word := range antonymsOEWN {
 		seen[word] = struct{}{}
 	}
 
 	words := make([]string, 0, len(seen))
+	
 	for word := range seen {
 		words = append(words, word)
 	}
+	
 	sort.Strings(words)
 	return words
 }
@@ -75,18 +79,21 @@ func buildAllWords(curated map[string]Entry, synonymsOEWN, antonymsOEWN map[stri
 // or missing dataset.
 func mustLoadGzipJSON(compressed []byte) map[string][]string {
 	gz, err := gzip.NewReader(bytes.NewReader(compressed))
+
 	if err != nil {
 		panic(err)
 	}
 
 	defer gz.Close()
 
 	decompressed, err := io.ReadAll(gz)
+	
 	if err != nil {
 		panic(err)
 	}
 
 	var data map[string][]string
+	
 	if err := json.Unmarshal(decompressed, &data); err != nil {
 		panic(err)
 	}