Documentation
¶
Overview ¶
Package iterators provide iterator implementations.
Summary ¶
An iterator goal is to decouple the facts about the origin of the data, to the consumer who use the data. Most common scenario is to hide the fact if data is from a Certain DB, STDIN or from somewhere else. This helps to design data consumers that doesn't rely on the data source concrete implementation, while still able to do composition and different kind of actions on the received data stream. An Interface represent multiple data that can be 0 and infinite. As a general rule of thumb, if the consumer is not the final destination of the data stream, the consumer should use the pipeline pattern, in order to avoid bottleneck with local resources.
Interface define a separate object that encapsulates accessing and traversing an aggregate object. Clients use an iterator to access and traverse an aggregate without knowing its representation (data structures). Interface design inspirited by https://golang.org/pkg/encoding/json/#Decoder
Why an Object with empty interface instead of type safe channels to represent streams ¶
There are multiple approach to the same problem, and I only prefer this approach, because the error handling is easier trough this. In channel based pipeline pattern, you have to make sure that the information about the error is passed trough either trough some kind of separate error channel, or trough the message object it self that being passed around. If the pipeline can be composited during a certain use case, you can pass around a context.Context object to represent this. In the case of Interface pattern, this failure communicated during the individual iteration, which leaves it up to you to propagate the error forward, or handle at the place.
Resources ¶
https://en.wikipedia.org/wiki/Iterator_pattern https://en.wikipedia.org/wiki/Pipeline_(software)
Index ¶
- Constants
- func Collect(i Interface, slicePtr interface{}) (err error)
- func Count(i Interface) (int, error)
- func First(i Interface, ptr interface{}) (found bool, err error)
- func ForEach(i Interface, fn interface{}) (rErr error)
- func Last(i Interface, e interface{}) (found bool, err error)
- func NewPipe() (*PipeReceiver, *PipeSender)
- type Callback
- type CallbackIterator
- type ConcurrentAccessIterator
- type Decoder
- type DecoderFunc
- type Empty
- type Encoder
- type EncoderFunc
- type Error
- type FilterIterator
- type Interface
- type MapIter
- type MapTransformFunc
- type Mock
- type PipeReceiver
- type PipeSender
- type SQLRowMapper
- type SQLRowMapperFunc
- type SQLRowScanner
- type SQLRows
- type SQLRowsIterator
- type Scanner
- type SingleElement
- type Slice
Examples ¶
Constants ¶
const Break consterror.Error = `iterators:break`
const ( // ErrClosed is the value that will be returned if a iterator has been closed but next decode is called ErrClosed consterror.Error = "Closed" )
Variables ¶
This section is empty.
Functions ¶
func Count ¶
Count will iterate over and count the total iterations number
Good when all you want is count all the elements in an iterator but don't want to do anything else.
func NewPipe ¶
func NewPipe() (*PipeReceiver, *PipeSender)
NewPipe return a receiver and a sender. This can be used with resources that
Example ¶
package main
import (
"github.com/adamluzsi/frameless/iterators"
)
func main() {
var (
iter iterators.Interface
sender *iterators.PipeSender
)
iter, sender = iterators.NewPipe()
_ = iter // send to caller for consuming it
_ = sender // use it to send values for each iter.Next() call
}
Output:
Types ¶
type CallbackIterator ¶
func (*CallbackIterator) Close ¶
func (i *CallbackIterator) Close() error
type ConcurrentAccessIterator ¶
type ConcurrentAccessIterator struct {
Interface
// contains filtered or unexported fields
}
func WithConcurrentAccess ¶
func WithConcurrentAccess(i Interface) *ConcurrentAccessIterator
WithConcurrentAccess allows you to convert any iterator into one that is safe to use from concurrent access. The caveat with this, that this protection only allows 1 Decode call for each Next call.
func (*ConcurrentAccessIterator) Decode ¶
func (i *ConcurrentAccessIterator) Decode(ptr interface{}) error
func (*ConcurrentAccessIterator) Next ¶
func (i *ConcurrentAccessIterator) Next() bool
type Decoder ¶
type Decoder interface {
// Decode will populate/replace/configure the value of the received pointer type
// and in case of failure, returns an error.
Decode(ptr interface{}) error
}
Decoder is the interface to represent value decoding into a passed pointer type. Most commonly this happens with value decoding that was received from some sort of external resource. Decoder in other words the interface for populating/replacing a public struct with values that retried from an external resource.
type DecoderFunc ¶
type DecoderFunc func(interface{}) error
DecoderFunc enables to use anonymous functions to be a valid DecoderFunc
func (DecoderFunc) Decode ¶
func (lambda DecoderFunc) Decode(i interface{}) error
Decode proxy the call to the wrapped Decoder function
type Empty ¶
type Empty struct{}
Empty iterator can help achieve Null Object Pattern when no value is logically expected and iterator should be returned
type Encoder ¶
type Encoder interface {
//
// Encode encode a simple message back to the wrapped communication channel
// message is an interface type because the channel communication layer and content and the serialization is up to the Encoder to implement
//
// If the message is a complex type that has multiple fields,
// an exported struct that represent the content must be declared at the controller level
// and all the presenters must based on that input for they test
Encode(interface{}) error
}
Encoder is a scope isolation boundary. One use-case for this is for example the Presenter object that encapsulate the external resource presentation mechanism from it's user.
Scope:
receive Entities, that will be used by the creator of the Encoder
type EncoderFunc ¶
type EncoderFunc func(interface{}) error
EncoderFunc is a wrapper to convert standalone functions into a presenter
func (EncoderFunc) Encode ¶
func (lambda EncoderFunc) Encode(i interface{}) error
Encode implements the Encoder Interface
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error iterator can be used for returning an error wrapped with iterator interface. This can be used when external resource encounter unexpected non recoverable error during query execution.
type FilterIterator ¶
type FilterIterator struct {
// contains filtered or unexported fields
}
func Filter ¶
func Filter(i Interface, selectorFunc interface{}) *FilterIterator
Example ¶
package main
import (
"fmt"
"log"
"github.com/adamluzsi/frameless/iterators"
)
func main() {
var iter iterators.Interface
iter = iterators.NewSlice([]int{0, 1, 2, 3, 4, 5, 6, 7, 8, 9})
iter = iterators.Filter(iter, func(n int) bool { return n > 2 })
defer iter.Close()
for iter.Next() {
var n int
if err := iter.Decode(&n); err != nil {
log.Fatal(err)
}
fmt.Println(n)
}
if err := iter.Err(); err != nil {
log.Fatal(err)
}
}
Output:
func (*FilterIterator) Close ¶
func (fi *FilterIterator) Close() error
func (*FilterIterator) Decode ¶
func (fi *FilterIterator) Decode(e interface{}) error
func (*FilterIterator) Err ¶
func (fi *FilterIterator) Err() error
func (*FilterIterator) Next ¶
func (fi *FilterIterator) Next() bool
type Interface ¶
type Interface interface {
// this is required to make it able to cancel iterators where resource being used behind the scene
// for all other case where the underling io is handled on higher level, it should simply return nil
io.Closer
// Next will ensure that Decode return the next item when it is executed
Next() bool
// Err return the cause if for some reason by default the More return false all the time
Err() error
// Decoder will populate an object with values and/or return error
// this is required to retrieve the current value from the iterator
Decoder
}
Interface define a separate object that encapsulates accessing and traversing an aggregate object. Clients use an iterator to access and traverse an aggregate without knowing its representation (data structures). Interface design inspirited by https://golang.org/pkg/encoding/json/#Decoder https://en.wikipedia.org/wiki/Iterator_pattern
func WithCallback ¶
type MapIter ¶
type MapIter struct {
// contains filtered or unexported fields
}
func Map ¶
func Map(iter Interface, transform MapTransformFunc) *MapIter
Map allows you to do additional transformation on the values. This is useful in cases, where you have to alter the input value, or change the type all together. Like when you read lines from an input stream, and then you map the line content to a certain data structure, in order to not expose what steps needed in order to unserialize the input stream, thus protect the business rules from this information.
type MapTransformFunc ¶
type Mock ¶
type Mock struct {
StubDecode func(interface{}) error
StubClose func() error
StubNext func() bool
StubErr func() error
// contains filtered or unexported fields
}
func (*Mock) ResetClose ¶
func (m *Mock) ResetClose()
func (*Mock) ResetDecode ¶
func (m *Mock) ResetDecode()
type PipeReceiver ¶
type PipeReceiver struct {
// contains filtered or unexported fields
}
PipeReceiver implements iterator interface while it's still being able to receive values, used for streaming
func (*PipeReceiver) Close ¶
func (i *PipeReceiver) Close() error
Close sends a signal back that no more value should be sent because receiver stop listening
func (*PipeReceiver) Decode ¶
func (i *PipeReceiver) Decode(e interface{}) error
Decode will link the current buffered value to the pointer value that is given as "e"
func (*PipeReceiver) Err ¶
func (i *PipeReceiver) Err() error
Err returns an error object that the pipe sender want to present for the pipe receiver
func (*PipeReceiver) Next ¶
func (i *PipeReceiver) Next() bool
Next set the current entity for the next value returns false if no next value
type PipeSender ¶
type PipeSender struct {
// contains filtered or unexported fields
}
PipeSender provides access to feed a pipe receiver with entities
func (*PipeSender) Close ¶
func (f *PipeSender) Close() error
Close close the feed and err channel, which eventually notify the receiver that no more value expected
func (*PipeSender) Encode ¶
func (f *PipeSender) Encode(e interface{}) error
Encode send value to the PipeReceiver and returns ErrClosed error if no more value expected on the receiver side
func (*PipeSender) Error ¶
func (f *PipeSender) Error(err error)
Error send an error object to the PipeReceiver side, so it will be accessible with iterator.Err()
type SQLRowMapper ¶
type SQLRowMapper interface {
Map(s SQLRowScanner, ptr interface{}) error
}
type SQLRowMapperFunc ¶
type SQLRowMapperFunc func(SQLRowScanner, interface{}) error
func (SQLRowMapperFunc) Map ¶
func (fn SQLRowMapperFunc) Map(s SQLRowScanner, e interface{}) error
type SQLRowScanner ¶
type SQLRowScanner interface {
Scan(...interface{}) error
}
type SQLRowsIterator ¶
type SQLRowsIterator struct {
// contains filtered or unexported fields
}
SQLRowsIterator allow you to use the same iterator pattern with sql.Rows structure. it allows you to do dynamic filtering, pipeline/middleware pattern on your sql results by using this wrapping around it. it also makes testing easier with the same Interface interface.
func NewSQLRows ¶
func NewSQLRows(rows SQLRows, mapper SQLRowMapper) *SQLRowsIterator
func (*SQLRowsIterator) Close ¶
func (i *SQLRowsIterator) Close() error
func (*SQLRowsIterator) Decode ¶
func (i *SQLRowsIterator) Decode(e interface{}) error
func (*SQLRowsIterator) Err ¶
func (i *SQLRowsIterator) Err() error
func (*SQLRowsIterator) Next ¶
func (i *SQLRowsIterator) Next() bool
type Scanner ¶
func NewScanner ¶
type SingleElement ¶
type SingleElement struct {
// contains filtered or unexported fields
}
func NewSingleElement ¶
func NewSingleElement(e interface{}) *SingleElement
NewSingleElement creates an iterator that can return one single element and will ensure that Next can only be called once.
func (*SingleElement) Close ¶
func (i *SingleElement) Close() error
func (*SingleElement) Decode ¶
func (i *SingleElement) Decode(e interface{}) error
func (*SingleElement) Err ¶
func (i *SingleElement) Err() error
func (*SingleElement) Next ¶
func (i *SingleElement) Next() bool
Source Files