roster

README

go-roster

Go package provides interfaces and methods for defining internal lookup tables (or "rosters") for registering and instantiatinge custom interfaces with multiple implementations.

Documentation

Example

The following example is the body of the roster_test.go file:

package roster

import (
	"context"
	"fmt"
	"net/url"
	"testing"
)

// Create a toy interface that might have multiple implementations including a common
// method signature for creating instantiations of that interface.

type Example interface {
	String() string
}

type ExampleInitializationFunc func(context.Context, string) (Example, error)

func RegisterExample(ctx context.Context, scheme string, init_func ExampleInitializationFunc) error {
	return example_roster.Register(ctx, scheme, init_func)
}

func NewExample(ctx context.Context, uri string) (Example, error) {

	u, err := url.Parse(uri)

	if err != nil {
		return nil, fmt.Errorf("Failed to parse URI, %w", err)
	}

	scheme := u.Scheme

	i, err := example_roster.Driver(ctx, scheme)

	if err != nil {
		return nil, fmt.Errorf("Failed to find registeration for %s, %w", scheme, err)
	}

	init_func := i.(ExampleInitializationFunc)
	return init_func(ctx, uri)
}

// Something that implements the Example interface

type StringExample struct {
	Example
	value string
}

func NewStringExample(ctx context.Context, uri string) (Example, error) {

	u, err := url.Parse(uri)

	if err != nil {
		return nil, fmt.Errorf("Failed to parse URL, %w", err)
	}

	s := &StringExample{
		value: u.Path,
	}

	return s, nil
}

func (e *StringExample) String() string {
	return e.value
}

// Create a global "roster" of implementations of the Example interface

var example_roster Roster

// Ensure that there is a valid roster (for use by the code handling the Example interface)
// and register the StringExample implementation

func init() {

	ctx := context.Background()

	r, err := NewDefaultRoster()

	if err != nil {
		panic(err)
	}

	example_roster = r

	err = RegisterExample(ctx, "string", NewStringExample)

	if err != nil {
		panic(err)
	}
}

func TestRoster(t *testing.T) {

	ctx := context.Background()

	e, err := NewExample(ctx, "string:///helloworld")

	if err != nil {
		t.Fatalf("Failed to create new example, %v", err)
	}

	v := e.String()

	if v != "/helloworld" {
		t.Fatalf("Unexpected result: '%s'", v)
	}
}

Concrete examples

• https://github.com/whosonfirst/go-reader
• https://github.com/whosonfirst/go-writer

Documentation

Overview

package roster provides interfaces and methods for defining internal lookup tables for registering and instantiatinge custom interfaces with multiple implementations. The expectation is that these (roster) interfaces will never be seen by user-facing code.

Index

• type DefaultRoster
  • func (dr *DefaultRoster) Driver(ctx context.Context, name string) (interface{}, error)
  • func (dr *DefaultRoster) Drivers(ctx context.Context) []string
  • func (dr *DefaultRoster) NormalizeName(ctx context.Context, name string) string
  • func (dr *DefaultRoster) Register(ctx context.Context, name string, i interface{}) error
  • func (dr *DefaultRoster) UnregisterAll(ctx context.Context) error
• type Roster
  • func NewDefaultRoster() (Roster, error)

Types

type DefaultRoster

type DefaultRoster struct {
	Roster
	// contains filtered or unexported fields
}

DefaultRoster implements the the `Roster` interface mapping scheme names to arbitrary interface values.

func (*DefaultRoster) Driver

func (dr *DefaultRoster) Driver(ctx context.Context, name string) (interface{}, error)

Driver returns the value associated with the key for the normalized value of 'name' in the list of registered drivers available to 'dr'.

func (*DefaultRoster) Drivers

func (dr *DefaultRoster) Drivers(ctx context.Context) []string

Drivers returns the list of registered schemes for all the drivers available to 'dr'.

func (*DefaultRoster) NormalizeName

func (dr *DefaultRoster) NormalizeName(ctx context.Context, name string) string

NormalizeName returns a normalized (upper-cased) version of 'name'.

func (*DefaultRoster) Register

func (dr *DefaultRoster) Register(ctx context.Context, name string, i interface{}) error

Registers creates a new entry in the list of drivers available to 'dr' mapping the normalized version of 'name' to 'i'.

func (*DefaultRoster) UnregisterAll

func (dr *DefaultRoster) UnregisterAll(ctx context.Context) error

UnregisterAll removes all the registers drivers from 'dr'.

type Roster

type Roster interface {
	// Driver returns the value associated with a name or scheme from the list of drivers that have been registered.
	Driver(context.Context, string) (interface{}, error)
	// Drivers returns the list of names or schemes for the list of drivers that have been registered.
	Drivers(context.Context) []string
	// UnregisterAll removes all the registered drivers from an instance implementing the Roster interfave.
	UnregisterAll(context.Context) error
	// NormalizeName returns a normalized version of a string.
	NormalizeName(context.Context, string) string
	// Register associated a name or scheme with an arbitrary interface.
	Register(context.Context, string, interface{}) error
}

type Roster is an interface for defining internal lookup tables (or "rosters") for registering and instantiatinge custom interfaces with multiple implementations.

func NewDefaultRoster

func NewDefaultRoster() (Roster, error)

NewDefaultRoster returns a new `DefaultRoster` instance.