file

README

go-file

go-file essentially tries to provide a wrapper for file-like objects of different backend types. It uses URLs to identify files (be they local, in Doozer or somewhere else) and provide relatively transparent access to them.

At this point, it only supports watching files in different types of file systems, but there is support planned for implementing transparent access to readers and lateron even writers.

Watchers

So far, watchers are the only implemented common method. They can be used to watch files for changes and receive a callback with the file name and an io.ReadCloser object with the modified file contents for ease of access.

The basic important function is file.Watch(). It picks the correct handler for the URL type it's being passed and invokes it. The handler itself will do its thing in the background to ensure all modifications of the affected file are noticed and reported.

The callback itself will only see an io.ReadCloser interface to use when it's being notified of changes. This means that it doesn't require any logic relevant to the underlying file system implementation to get to the files contents.

Since the contents of the modified file may actually be irrelevant, implementations are required to ensure that just closing the file without reading it means that no nontrivial cost will be incurred; any expensive initialization should be deferred until the first call to Read().

Documentation

Overview

Virtual file system client implementation for Go.

Index

• Variables
• func List(u *url.URL) ([]string, error)
• func Open(u *url.URL) (io.ReadCloser, error)
• func OpenForAppend(u *url.URL) (io.WriteCloser, error)
• func OpenForWrite(u *url.URL) (io.WriteCloser, error)
• func RegisterFileSystem(schema string, fs FileSystem)
• func RegisterWatcher(schema string, creator WatcherCreator)
• func Remove(u *url.URL) error
• type FileSystem
• type ReadCloserFake
  • func NewReadCloserFake(reader io.Reader) *ReadCloserFake
  • func (d *ReadCloserFake) Close() error
  • func (d *ReadCloserFake) Read(dest []byte) (int, error)
• type Watcher
  • func Watch(fileurl *url.URL, handler func(string, io.ReadCloser)) (Watcher, error)
• type WatcherCreator

Variables

var FS_OperationNotImplementedError error = errors.New("Operation not implemented for this file system")

Functions

func List

func List(u *url.URL) ([]string, error)

Read all names under the given path as file names. Requires "u" to point to a directory. The list of file names returned should only be short, local names which can be appended to the URL to form a new one.

func Open

func Open(u *url.URL) (io.ReadCloser, error)

Return a reader for the file given as "u".

func OpenForAppend

func OpenForAppend(u *url.URL) (io.WriteCloser, error)

Return a writer for appending data to the file given as "u". Any writer should guarantee that all data has been written by the time Close() returns without an error. No other guarantees have to be given.

func OpenForWrite

func OpenForWrite(u *url.URL) (io.WriteCloser, error)

Return a writer for the file given as "u". Any writer should guarantee that all data has been written by the time Close() returns without an error. No other guarantees have to be given.

func RegisterFileSystem

func RegisterFileSystem(schema string, fs FileSystem)

Register "fs" as a file system implementation for all URLs with the given "schema".

func RegisterWatcher

func RegisterWatcher(schema string, creator WatcherCreator)

Register "creator" as a handler for watchers for all URLs with the given "schema".

func Remove

func Remove(u *url.URL) error

Remove the referenced object from the file system. This would cause the file to be deleted from the underlying file system, or whatever operation is equivalent to that.

Types

type FileSystem

type FileSystem interface {
	Open(*url.URL) (io.ReadCloser, error)
	OpenForWrite(*url.URL) (io.WriteCloser, error)
	OpenForAppend(*url.URL) (io.WriteCloser, error)
	List(*url.URL) ([]string, error)
	Watch(*url.URL, func(string, io.ReadCloser)) (Watcher, error)
	Remove(*url.URL) error
}

Object providing all relevant operations for file systems. The individual file system backend implementations need to handle these properly, or return a FS_OperationNotImplementedError.

type ReadCloserFake

type ReadCloserFake struct {
	// contains filtered or unexported fields
}

Helper structure to offer read and close functionality on Doozer files.

func NewReadCloserFake

func NewReadCloserFake(reader io.Reader) *ReadCloserFake

Create an ew ReadCloserFake object reading from "reader".

func (*ReadCloserFake) Close

func (d *ReadCloserFake) Close() error

Close the ReadCloser, making all subsequent calls to Read() return EOF.

func (*ReadCloserFake) Read

func (d *ReadCloserFake) Read(dest []byte) (int, error)

Read a number of bytes from the wrapped reader, unless close has already been called.

type Watcher

type Watcher interface {
	// Stop listening for notifications on the given file. This may take
	// until the next event to take effect.
	Shutdown() error

	// Retrieve the error channel associated with the watcher.
	// It will stream a list of all errors created while watching.
	ErrChan() chan error
}

Watchers are the objects doing the actual watching of individual files. They are configured by the WatcherCreator and will continue invoking their configured handlers until Shutdown() is called.

func Watch

func Watch(fileurl *url.URL, handler func(string, io.ReadCloser)) (Watcher, error)

Watch the given "fileurl" for changes, sending all of them to the specified "handler". This will look up the required handler for the scheme specified in the URL and forward the watch request. A Watcher object is returned which can be used to stop watching, as defined by the individual watchers.

type WatcherCreator

type WatcherCreator interface {
	Watch(*url.URL, func(string, io.ReadCloser)) (Watcher, error)
}

Objects describing how to watch a specific type of files, identified by their URL schema. Watch will be invoked whenever watching a file with the given schema is requested.