gocloud.dev: gocloud.dev/runtimevar/filevar Index | Examples | Files

package filevar

import "gocloud.dev/runtimevar/filevar"

Package filevar provides a runtimevar implementation with variables backed by the filesystem. Use OpenVariable to construct a *runtimevar.Variable.

Configuration files can be updated using any commands (cp, mv) or tools/editors. This package does not guarantee read consistency since it does not have control over the writes. For example, some kinds of updates might result in filevar temporarily receiving an error or an empty value.

Known Issues:

* On macOS, if an empty file is copied into a configuration file,

filevar will not detect the change.


For runtimevar.OpenVariable, filevar registers for the scheme "file". To customize the URL opener, or for more details on the URL format, see URLOpener. See https://gocloud.dev/concepts/urls/ for background information.


filevar does not support any types for As.


// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
// PRAGMA: On gocloud.dev, add a blank import: _ "gocloud.dev/runtimevar/filevar"
// PRAGMA: On gocloud.dev, hide lines until the next blank line.
ctx := context.Background()

// runtimevar.OpenVariable creates a *runtimevar.Variable from a URL.

v, err := runtimevar.OpenVariable(ctx, "file:///path/to/config.txt?decoder=string")
if err != nil {
defer v.Close()



Package Files



const Scheme = "file"

Scheme is the URL scheme filevar registers its URLOpener under on runtimevar.DefaultMux.

func OpenVariable Uses

func OpenVariable(path string, decoder *runtimevar.Decoder, opts *Options) (*runtimevar.Variable, error)

OpenVariable constructs a *runtimevar.Variable backed by the file at path. The file holds raw bytes; provide a decoder to decode the raw bytes into the appropriate type for runtimevar.Snapshot.Value. See the runtimevar package documentation for examples of decoders.


// Create a temporary file to hold our config.
f, err := ioutil.TempFile("", "")
if err != nil {
if _, err := f.Write([]byte("hello world")); err != nil {

// Construct a *runtimevar.Variable pointing at f.
v, err := filevar.OpenVariable(f.Name(), runtimevar.StringDecoder, nil)
if err != nil {
defer v.Close()

// We can now read the current value of the variable from v.
snapshot, err := v.Latest(context.Background())
if err != nil {
// runtimevar.Snapshot.Value is decoded to a string.


hello world

type Options Uses

type Options struct {
    // WaitDuration controls the frequency of retries after an error. For example,
    // if the file does not exist. Defaults to 30 seconds.
    WaitDuration time.Duration

Options sets options.

type URLOpener Uses

type URLOpener struct {
    // Decoder specifies the decoder to use if one is not specified in the URL.
    // Defaults to runtimevar.BytesDecoder.
    Decoder *runtimevar.Decoder

    // Options specifies the options to pass to OpenVariable.
    Options Options

URLOpener opens filevar URLs like "file:///path/to/config.json?decoder=json".

The URL's host+path is used as the path to the file to watch. If os.PathSeparator != "/", any leading "/" from the path is dropped and remaining '/' characters are converted to os.PathSeparator.

The following URL parameters are supported:

- decoder: The decoder to use. Defaults to URLOpener.Decoder, or
    runtimevar.BytesDecoder if URLOpener.Decoder is nil.
    See runtimevar.DecoderByName for supported values.

func (*URLOpener) OpenVariableURL Uses

func (o *URLOpener) OpenVariableURL(ctx context.Context, u *url.URL) (*runtimevar.Variable, error)

OpenVariableURL opens the variable at the URL's path. See the package doc for more details.

Package filevar imports 14 packages (graph) and is imported by 6 packages. Updated 2019-08-02. Refresh now. Tools for package owners.