documents

README.md

@@ -4,12 +4,47 @@
 [![Actions/Go](https://github.com/koron-go/inflater/workflows/Go/badge.svg)](https://github.com/koron-go/inflater/actions?query=workflow%3AGo)
 [![Go Report Card](https://goreportcard.com/badge/github.com/koron-go/inflater)](https://goreportcard.com/report/github.com/koron-go/inflater)
 
-## Operations
-
-* V -> S (inflate)
-* V -> V
-* S -> S (V -> S)
-* S -> S (V -> V: map)
-* S -> S (V -> discard: filter)
-* S + S -> S (join)
-* S * S -> S
+The package `inflater` provides an `Inflater` interface that inflates a value
+into multiple values and some operations to combine them `Inflater`s.
+
+## Install and Upgrade
+
+```console
+$ go get github.com/koron-go/inflater@latest
+```
+
+## Description
+
+The first idea of the `inflater` was very simple: to perform an algorithm that
+predicts and expands multiple strings from a single input string using a single
+interface combination.  Therefore, the first Inflate function was defined as
+`func Inflate(s string) <-chan string`
+
+Combining this with the [rangefunc][rangefunc] added in Go 1.23 and using
+generics instead of `string`, we have the following `Inflater` interface.  This
+is intended to inflate multiple values based on a `seed`.
+
+```go
+type Inflater[V any] interface {
+	Inflate(seed V) iter.Seq[V]
+}
+```
+
+The package `inflater` provides several special `Inflater` types.
+
+* `None` - An Inflater that consumes all input and produces no output, like a black hole.
+* `Keep` - An Inflater that outputs the input as is.
+* `Map` - An Inflater that converts input with a function and outputs it.
+* `Filter` - An Inflater that judges and filters input with a function.
+
+It also provides the ability to combine multiple `Inflater` objects to create another `Inflater` object.
+
+* `Parallel` - Pass the input to multiple `Inflater`s and concatenate their outputs into a single `iter.Seq`.
+* `Serial` - Inflate the input with the first `Inflater`, inflate the output of that with the next `Inflater`, and repeat that to get the output iter.Seq
+
+In addition, we provide two `Inflater`s that perform basic operations on strings.
+
+* `Prefix` - An Inflater that outputs multiple values with an each prefix string attached to the input string.
+* `Suffix` - An Inflater that outputs multiple values with an each suffix string attached to the input string.
+
+[rangefunc]:https://tip.golang.org/wiki/RangefuncExperiment

inflater.go

@@ -1,18 +1,23 @@
 /*
-Package inflater provides ...
+Package `inflater` provides an `Inflater` interface that inflates a value
+into multiple values and some operations to combine them `Inflater`s.
 */
 package inflater
 
 import (
 	"iter"
 )
 
+// Inflater is the interface that inflate a value to a sequence of values
 type Inflater[V any] interface {
+	// Inflate a seed value to a sequence of values.
 	Inflate(seed V) iter.Seq[V]
 }
 
+// InflateFunc is a wrapper function for using a function as an Inflater.
 type InflaterFunc[V any] func(seed V) iter.Seq[V]
 
+// Inflate a value to a sequence of values.
 func (f InflaterFunc[V]) Inflate(seed V) iter.Seq[V] {
 	return f(seed)
 }
@@ -33,6 +38,7 @@ func Keep[V any]() Inflater[V] {
 	})
 }
 
+// Map is an Inflater which maps (modify/convert) a value to another value with a function.
 func Map[V any](apply func(V) V) Inflater[V] {
 	if apply == nil {
 		return Keep[V]()
@@ -46,7 +52,7 @@ func Map[V any](apply func(V) V) Inflater[V] {
 	})
 }
 
-// Filter provides an Inflater which inflate a seed if check(seed) returns true.
+// Filter provides an Inflater which pass through a seed if check(seed) returns true.
 func Filter[V any](check func(V) bool) Inflater[V] {
 	if check == nil {
 		return Keep[V]()
@@ -60,7 +66,8 @@ func Filter[V any](check func(V) bool) Inflater[V] {
 	})
 }
 
-// Parallel2 creates an Inflater with distribute a seed to two Inflaters.
+// Parallel2 creates an Inflater that inflates one input with two Inflaters and
+// concatenates the results into one iter.Seq.
 func Parallel2[V any](first, second Inflater[V]) Inflater[V] {
 	return InflaterFunc[V](func(seed V) iter.Seq[V] {
 		return func(yield func(V) bool) {
@@ -78,7 +85,8 @@ func Parallel2[V any](first, second Inflater[V]) Inflater[V] {
 	})
 }
 
-// Parallel creates an Inflater which distibute a seed to multiple Inflaters.
+// Parallel creates an Inflater that inflates one input with multiple Inflaters
+// and concatenates the results into one iter.Seq.
 func Parallel[V any](inflaters ...Inflater[V]) Inflater[V] {
 	switch len(inflaters) {
 	case 0:
@@ -92,8 +100,8 @@ func Parallel[V any](inflaters ...Inflater[V]) Inflater[V] {
 	}
 }
 
-// Serial2 creates an Inflater that inflates the result of the first
-// Inflater with the second Inflater.
+// Serial2 creates an Inflater that inflates the input with the first Inflater
+// and then inflates the result with the second Inflater.
 func Serial2[V any](first, second Inflater[V]) Inflater[V] {
 	return InflaterFunc[V](func(seed V) iter.Seq[V] {
 		return func(yield func(V) bool) {
@@ -108,8 +116,9 @@ func Serial2[V any](first, second Inflater[V]) Inflater[V] {
 	})
 }
 
-// Serial creates an Inflater that applies multiple Inflaters in sequence to
-// its result repeatedly.
+// Serial creates an Inflater that inflates the input with the first Inflater,
+// then inflates the result with the second Inflater, and repeats this for all
+// the given Inflaters.
 func Serial[V any](inflaters ...Inflater[V]) Inflater[V] {
 	switch len(inflaters) {
 	case 0:
@@ -123,7 +132,7 @@ func Serial[V any](inflaters ...Inflater[V]) Inflater[V] {
 	}
 }
 
-// Prefix provides an Inflater which inflate with prefixes.
+// Prefix creates an Inflater that prepends each prefix string to one input.
 func Prefix[V ~string](prefixes ...V) Inflater[V] {
 	if len(prefixes) == 0 {
 		return None[V]()
@@ -139,7 +148,7 @@ func Prefix[V ~string](prefixes ...V) Inflater[V] {
 	})
 }
 
-// Suffix provides an Inflater which inflate with suffixes.
+// Suffix creates an Inflater that appends each suffix string to the input.
 func Suffix[V ~string](suffixes ...V) Inflater[V] {
 	if len(suffixes) == 0 {
 		return None[V]()