writer

package module
v3.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 4, 2024 License: BSD-3-Clause Imports: 16 Imported by: 83

README

go-whosonfirst-writer

Go package that provides a common interface for writing data to multiple sources.

Documentation

Go Reference

Example

Writers are instantiated with the writer.NewWriter method which takes as its arguments a context.Context instance and a URI string. The URI's scheme represents the type of writer it implements and the remaining (URI) properties are used by that writer type to instantiate itself. For example:

import (
       "context"
       "github.com/whosonfirst/go-writer/v2"
       "strings"
)

func main() {

	ctx := context.Background()
	
	r := strings.NewReader("Hello world")
	
	wr, _ := writer.NewWriter(ctx, "fs:///usr/local/example")
	wr.Write(ctx, wr, "hello/world.txt", r)
}

Error handling omitted for the sake of brevity.

Writers

The following writers are exported by this package. Additional writers are defined in separate go-writer-* packages.

cwd://

Implements the Writer interface for writing documents to the current working directory.

fs://

Implements the Writer interface for writing documents as files on a local disk.

io://

Implements the Writer interface for writing documents to an io.Writer instance.

multi://

Implements the Writer interface for writing documents to multiple Writer instances.

null://

Implements the Writer interface for writing documents to nowhere.

repo://

Implements the Writer interface for writing documents to a Who's On First "data" directory.

stdout://

Implements the Writer interface for writing documents to STDOUT.

See also

Documentation

Overview

Package writer provides a common interface for writing data to one or more sources.

Index

Constants

View Source 
const IOWRITER_TARGET_KEY string = "github.com/whosonfirst/go-writer#io_writer"

IOWRITER_TARGET_KEY is the key used to store an `io.Writer` instance in a `context.Context` instance.

Variables

This section is empty.

Functions

func DefaultLogger 

func DefaultLogger() *log.Logger

DefaultLogger() returns a `log.Logger` instance that writes to `io.Discard`.

func GetIOWriterFromContext 

func GetIOWriterFromContext(ctx context.Context) (io.Writer, error)

GetIOWriterFromContext returns the `io.Writer` instance associated with the `IOWRITER_TARGET_KEY` value in 'ctx'.

func RegisterWriter 

func RegisterWriter(ctx context.Context, scheme string, init_func WriterInitializationFunc) error

RegisterWriter registers 'scheme' as a key pointing to 'init_func' in an internal lookup table used to create new `Writer` instances by the `NewWriter` method.

func Schemes 

func Schemes() []string

Schemes returns the list of schemes that have been registered.

func SetIOWriterWithContext 

func SetIOWriterWithContext(ctx context.Context, wr io.Writer) (context.Context, error)

SetIOWriterWithContext returns a new `context.Context` instance with 'wr' assigned to the `IOWRITER_TARGET_KEY` value.

Types

type CwdWriter 

type CwdWriter struct {
	Writer
	// contains filtered or unexported fields
}

CwdWriter is a struct that implements the `Writer` interface for writing documents to the current working directory.

func (*CwdWriter) Close 

func (wr *CwdWriter) Close(ctx context.Context) error

Close closes the underlying writer mechanism.

func (*CwdWriter) Flush 

func (wr *CwdWriter) Flush(ctx context.Context) error

Flush() invokes the Flush() method for the underlying writer mechanism.

func (*CwdWriter) SetLogger 

func (wr *CwdWriter) SetLogger(ctx context.Context, logger *log.Logger) error

SetLogger assigns 'logger' to 'wr'.

func (*CwdWriter) Write 

func (wr *CwdWriter) Write(ctx context.Context, path string, fh io.ReadSeeker) (int64, error)

Write copies the content of 'fh' to 'path'.

func (*CwdWriter) WriterURI 

func (wr *CwdWriter) WriterURI(ctx context.Context, path string) string

WriterURI returns the final URI for 'path'

type FileWriter 

type FileWriter struct {
	Writer
	// contains filtered or unexported fields
}

FileWriter is a struct that implements the `Writer` interface for writing documents as files on a local disk.

func (*FileWriter) Close 

func (wr *FileWriter) Close(ctx context.Context) error

Close closes the underlying writer mechanism.

func (*FileWriter) Flush 

func (wr *FileWriter) Flush(ctx context.Context) error

Flush is a no-op and returns nil.

func (*FileWriter) SetLogger 

func (wr *FileWriter) SetLogger(ctx context.Context, logger *log.Logger) error

SetLogger assigns 'logger' to 'wr'.

func (*FileWriter) Write 

func (wr *FileWriter) Write(ctx context.Context, path string, fh io.ReadSeeker) (int64, error)

Write copies the content of 'fh' to 'path', where 'path' is assumed to be relative to the root path defined in the constuctor. If the root directory for 'path' does not exist it will be created.

func (*FileWriter) WriterURI 

func (wr *FileWriter) WriterURI(ctx context.Context, path string) string

WriterURI returns the absolute URL for 'path' relative to the root directory defined in the `FileWriter` constuctor.

type IOWriter 

type IOWriter struct {
	Writer
	// contains filtered or unexported fields
}

IOWriter is a struct that implements the `Writer` interface for writing documents to an `io.Writer` instance.

func (*IOWriter) Close 

func (io_wr *IOWriter) Close(ctx context.Context) error

Close closes the underlying writer mechanism.

func (*IOWriter) Flush 

func (io_wr *IOWriter) Flush(ctx context.Context) error

Flush publish any outstanding data.

func (*IOWriter) SetLogger 

func (io_wr *IOWriter) SetLogger(ctx context.Context, logger *log.Logger) error

SetLogger assigns 'logger' to 'wr'.

func (*IOWriter) Write 

func (io_wr *IOWriter) Write(ctx context.Context, path string, fh io.ReadSeeker) (int64, error)

Write copies the content of 'fh' to 'path'. It is assumed that either 'io_wr' was created using the NewIOWriterWithWriter method in which there is an explicit `io.Writer` target or that 'ctx' contains a valid `io.Writer` instance that has been assigned by the `SetIOWriterWithContext` method.

func (*IOWriter) WriterURI 

func (io_wr *IOWriter) WriterURI(ctx context.Context, path string) string

WriterURI returns the final URI for path.

type MultiWriter 

type MultiWriter struct {
	Writer
	// contains filtered or unexported fields
}

Type MultiWriter implements the `Writer` interface for writing documents to multiple `Writer` instances.

func (*MultiWriter) Close 

func (mw *MultiWriter) Close(ctx context.Context) error

Closes closes each of the underlying `Writer` instances (in the order they were specified to the 'mw' instance) unless 'mw' was created by `NewAsyncMultiWriter`.

func (*MultiWriter) Flush 

func (mw *MultiWriter) Flush(ctx context.Context) error

Flushes publishes any outstanding data for each of the underlying `Writer` instances (in the order they were specified to the 'mw' instance) unless 'mw' was created by `NewAsyncMultiWriter`.

func (*MultiWriter) SetLogger 

func (mw *MultiWriter) SetLogger(ctx context.Context, logger *log.Logger) error

SetLogger assign 'logger' to each of the underlying `Writer` instances (in the order they were specified to the 'mw' instance) unless 'mw' was created by `NewAsyncMultiWriter`.

func (*MultiWriter) Write 

func (mw *MultiWriter) Write(ctx context.Context, key string, fh io.ReadSeeker) (int64, error)

Write copies the contents of 'fh' to each of the writers contained by 'mw' in the order they were specified unless 'mw' was created by `NewAsyncMultiWriter`.

func (*MultiWriter) WriterURI 

func (mw *MultiWriter) WriterURI(ctx context.Context, key string) string

WriteURI returns an empty string. Because 'mw' has multiple underlying `Writer` instances each of which specifies their own `WriteURI` methods it's either a choice of returning a concatenated string (with all the values) or an empty string. The decision was made to opt for the latter.

type MultiWriterOptions 

type MultiWriterOptions struct {
	Writers []Writer
	Async   bool
	Logger  *log.Logger
	Verbose bool
}

type NullWriter 

type NullWriter struct {
	Writer
}

NullWriter is a struct that implements the `Writer` interface for writing documents to nowhere.

func (*NullWriter) Close 

func (wr *NullWriter) Close(ctx context.Context) error

Close is a no-op to conform to the `Writer` instance and returns nil.

func (*NullWriter) Flush 

func (wr *NullWriter) Flush(ctx context.Context) error

Flush is a no-op to conform to the `Writer` instance and returns nil.

func (*NullWriter) SetLogger 

func (wr *NullWriter) SetLogger(ctx context.Context, logger *log.Logger) error

SetLogger is a no-op to conform to the `Writer` instance and returns nil.

func (*NullWriter) Write 

func (wr *NullWriter) Write(ctx context.Context, path string, fh io.ReadSeeker) (int64, error)

Write copies the content of 'fh' to 'path' using an `io.Discard` writer.

func (*NullWriter) WriterURI 

func (wr *NullWriter) WriterURI(ctx context.Context, path string) string

WriterURI returns the value of 'path'

type StdoutWriter 

type StdoutWriter struct {
	Writer
}

StdoutWriter is a struct that implements the `Writer` interface for writing documents to STDOUT.

func (*StdoutWriter) Close 

func (wr *StdoutWriter) Close(ctx context.Context) error

Close is a no-op to conform to the `Writer` instance and returns nil.

func (*StdoutWriter) Flush 

func (wr *StdoutWriter) Flush(ctx context.Context) error

Flush is a no-op to conform to the `Writer` instance and returns nil.

func (*StdoutWriter) SetLogger 

func (wr *StdoutWriter) SetLogger(ctx context.Context, logger *log.Logger) error

SetLogger assigns 'logger' to 'wr'.

func (*StdoutWriter) Write 

func (wr *StdoutWriter) Write(ctx context.Context, path string, fh io.ReadSeeker) (int64, error)

Write copies the content of 'fh' to 'path' using an `os.Stdout` writer.

func (*StdoutWriter) WriterURI 

func (wr *StdoutWriter) WriterURI(ctx context.Context, path string) string

WriterURI returns the value of 'path'

type Writer 

type Writer interface {
	// Writer copies the contents of an `io.ReadSeeker` instance to a relative path.
	// The absolute path for the file is determined by the instance implementing the `Writer` interface.
	Write(context.Context, string, io.ReadSeeker) (int64, error)
	// WriterURI returns the absolute URI for an instance implementing the `Writer` interface.
	WriterURI(context.Context, string) string
	// Flush publishes any outstanding data. The details of if, how or where data is "published" is determined by individual implementations.
	Flush(context.Context) error
	// Close closes any underlying writing mechnisms for an instance implementing the `Writer` interface.
	Close(context.Context) error
	// SetLogger assigns a custom logger to a `Writer` instance
	SetLogger(context.Context, *log.Logger) error
}

Writer is an interface for writing data to multiple sources or targets.

func NewAsyncMultiWriter 

func NewAsyncMultiWriter(ctx context.Context, writers ...Writer) (Writer, error)

NewMultiWriter returns a Writer instance that will send all writes to each instance in 'writers' asynchronously.

func NewCwdWriter 

func NewCwdWriter(ctx context.Context, uri string) (Writer, error)

NewCwdWriter returns a new `CwdWriter` instance for writing documents to the current working directory configured by 'uri' in the form of: 

cwd://

Technically 'uri' can also be an empty string.

func NewFileWriter 

func NewFileWriter(ctx context.Context, uri string) (Writer, error)

NewFileWriter returns a new `FileWriter` instance for writing documents as files on a local disk, configured by 'uri' in the form of: 

fs://{PATH}

Where {PATH} is an absolute path to an existing directory where files will be written.

func NewIOWriter 

func NewIOWriter(ctx context.Context, uri string) (Writer, error)

NewIOWriter returns a new `IOWriter` instance for writing documents to an `io.Writer` instance configured by 'uri' in the form of: 

io://

In order to assign the actual `io.Writer` instance to use you will need to call the `SetIOWriterWithContext` method and pass the resultant `context.Context` instance to the `Write` method.

func NewIOWriterWithWriter added in v3.1.0 

func NewIOWriterWithWriter(ctx context.Context, wr io.Writer) (Writer, error)

NewIOWriter returns a new `IOWriter` instance for writing documents to 'wr'.

func NewMultiWriter 

func NewMultiWriter(ctx context.Context, writers ...Writer) (Writer, error)

NewMultiWriter returns a Writer instance that will send all writes to each instance in 'writers'. Writes happen synchronolously in the order in which the underlying Writer instances are specified.

func NewMultiWriterWithOptions 

func NewMultiWriterWithOptions(ctx context.Context, opts *MultiWriterOptions) (Writer, error)

NewMultiWriterWithOptions returns a Writer instance derived from 'opts'.

func NewNullWriter 

func NewNullWriter(ctx context.Context, uri string) (Writer, error)

NewNullWriter returns a new `CwdWriter` instance for writing documents to nowhere configured by 'uri' in the form of: 

null://

Technically 'uri' can also be an empty string.

func NewRepoWriter 

func NewRepoWriter(ctx context.Context, uri string) (Writer, error)

NewRepoWriter is a convenience method to update 'uri' by appending a `data` directory to its path and changing its scheme to `fs://` before invoking NewWriter with the updated URI.

func NewStdoutWriter 

func NewStdoutWriter(ctx context.Context, uri string) (Writer, error)

NewStdoutWriter returns a new `CwdWriter` instance for writing documents to STDOUT configured by 'uri' in the form of: 

stdout://

Technically 'uri' can also be an empty string.

func NewWriter 

func NewWriter(ctx context.Context, uri string) (Writer, error)

NewWriter returns a new `Writer` instance configured by 'uri'. The value of 'uri' is parsed as a `url.URL` and its scheme is used as the key for a corresponding `WriterInitializationFunc` function used to instantiate the new `Writer`. It is assumed that the scheme (and initialization function) have been registered by the `RegisterWriter` method.

type WriterInitializationFunc 

type WriterInitializationFunc func(ctx context.Context, uri string) (Writer, error)

WriterInitializationFunc is a function defined by individual writer package and used to create an instance of that writer

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.