spec

Documentation

Overview

Package spec provides builders and parsers for spelling Noms databases, datasets and values.

Index

• Constants
• func CreateCommitMetaStruct(db datas.Database, date, message string, keyValueStrings map[string]string, ...) (types.Struct, error)
• func CreateDatabaseSpecString(protocol, db string) string
• func CreateHashSpecString(protocol, db string, h hash.Hash) string
• func CreateValueSpecString(protocol, db, path string) string
• func ReadAbsolutePaths(db datas.Database, paths ...string) ([]types.Value, error)
• func RegisterCommitMetaFlags(flags *flag.FlagSet)
• func RegisterExternalProtocol(name string, p ProtocolImpl) error
• func UnregisterExternalProtocol(name string) bool
• type AbsolutePath
  • func NewAbsolutePath(str string) (AbsolutePath, error)
  • func (p AbsolutePath) IsEmpty() bool
  • func (p AbsolutePath) Resolve(db datas.Database) (val types.Value)
  • func (p AbsolutePath) String() (str string)
• type ProtocolImpl
• type Spec
  • func ForDatabase(spec string) (Spec, error)
  • func ForDatabaseOpts(spec string, opts SpecOptions) (Spec, error)
  • func ForDataset(spec string) (Spec, error)
  • func ForDatasetOpts(spec string, opts SpecOptions) (Spec, error)
  • func ForPath(spec string) (Spec, error)
  • func ForPathOpts(spec string, opts SpecOptions) (Spec, error)
  • func (sp Spec) Close() error
  • func (sp Spec) GetDatabase() datas.Database
  • func (sp Spec) GetDataset() (ds datas.Dataset)
  • func (sp Spec) GetValue() (val types.Value)
  • func (sp Spec) Href() string
  • func (sp Spec) NewChunkStore() chunks.ChunkStore
  • func (sp Spec) Pin() (Spec, bool)
  • func (sp Spec) String() string
• type SpecOptions

Constants

const CommitMetaDateFormat = time.RFC3339

const Separator = "::"

Functions

func CreateCommitMetaStruct

func CreateCommitMetaStruct(db datas.Database, date, message string, keyValueStrings map[string]string, keyValuePaths map[string]types.Value) (types.Struct, error)

CreateCommitMetaStruct creates and returns a Noms struct suitable for use in CommitOptions.Meta. It returns types.EmptyStruct and an error if any issues are encountered. Database is used only if commitMetaKeyValuePaths are provided on the command line and values need to be resolved. Date should be ISO 8601 format (see CommitMetaDateFormat), if empty the current date is used. The values passed as command line arguments (if any) are merged with the values provided as function arguments.

func CreateDatabaseSpecString

func CreateDatabaseSpecString(protocol, db string) string

func CreateHashSpecString

func CreateHashSpecString(protocol, db string, h hash.Hash) string

func CreateValueSpecString

func CreateValueSpecString(protocol, db, path string) string

func ReadAbsolutePaths

func ReadAbsolutePaths(db datas.Database, paths ...string) ([]types.Value, error)

ReadAbsolutePaths attempts to parse each path in 'paths' and resolve them. If any path fails to parse correctly or if any path can be resolved to an existing Noms Value, then this function returns (nil, error).

func RegisterCommitMetaFlags

func RegisterCommitMetaFlags(flags *flag.FlagSet)

RegisterCommitMetaFlags registers command line flags used for creating commit meta structs.

func RegisterExternalProtocol

func RegisterExternalProtocol(name string, p ProtocolImpl) error

RegisterExternalProtocol registers an external protocol implementation with the given name and ProtocolImpl. Trying to register a protocol with a name that is already taken will return an error. Thread-safe.

func UnregisterExternalProtocol

func UnregisterExternalProtocol(name string) bool

UnregisterExternalProtocol will remove the protocol handler for the protocol with the given name. It will return true if there was a protocol with that name, false otherwise. Thread-safe

Types

type AbsolutePath

type AbsolutePath struct {
	// A literal value, like `true` or `42`, or `"foo"`. Only kinds Bool,
	// Number, and String are supported. This allows absolute paths to be used
	// to specify primitive new data in addition to referencing existing data.
	Value types.Value
	// Dataset is the dataset this AbsolutePath is rooted at. Only one of
	// Dataset and Hash should be set.
	Dataset string
	// Hash is the hash this AbsolutePath is rooted at. Only one of Dataset and
	// Hash should be set.
	Hash hash.Hash
	// Path is the relative path from Dataset or Hash. This can be empty. In
	// that case, the AbsolutePath describes the value at either Dataset or
	// Hash.
	Path types.Path
}

AbsolutePath describes the location of a Value within a Noms database.

To locate a value relative to some other value, see Path. To locate a value globally, see Spec.

For more on paths, absolute paths, and specs, see: https://github.com/attic-labs/noms/blob/master/doc/spelling.md.

func NewAbsolutePath

func NewAbsolutePath(str string) (AbsolutePath, error)

NewAbsolutePath attempts to parse 'str' and return an AbsolutePath.

func (AbsolutePath) IsEmpty

func (p AbsolutePath) IsEmpty() bool

func (AbsolutePath) Resolve

func (p AbsolutePath) Resolve(db datas.Database) (val types.Value)

Resolve returns the Value reachable by 'p' in 'db'.

func (AbsolutePath) String

func (p AbsolutePath) String() (str string)

type ProtocolImpl

type ProtocolImpl interface {
	NewChunkStore(sp Spec) (chunks.ChunkStore, error)
	NewDatabase(sp Spec) (datas.Database, error)
}

ProtocolImpl is the interface that external protocols should implement.

type Spec

type Spec struct {
	// Protocol is one of "mem", "nbs", "http", or "aws", or anything registered with RegisterExternalProtocol
	Protocol string

	// DatabaseName is the name of the Spec's database, which is the string after
	// "protocol:". http/https specs include their leading "//" characters.
	DatabaseName string

	// Options are the SpecOptions that the Spec was constructed with.
	Options SpecOptions

	// Path is nil unless the spec was created with ForPath.
	Path AbsolutePath
	// contains filtered or unexported fields
}

Spec locates a Noms database, dataset, or value globally. Spec caches its database instance so it therefore does not reflect new commits in the db, by (legacy) design.

func ForDatabase

func ForDatabase(spec string) (Spec, error)

ForDatabase parses a spec for a Database.

func ForDatabaseOpts

func ForDatabaseOpts(spec string, opts SpecOptions) (Spec, error)

ForDatabaseOpts parses a spec for a Database.

func ForDataset

func ForDataset(spec string) (Spec, error)

ForDataset parses a spec for a Dataset.

func ForDatasetOpts

func ForDatasetOpts(spec string, opts SpecOptions) (Spec, error)

ForDatasetOpts parses a spec for a Dataset.

func ForPath

func ForPath(spec string) (Spec, error)

ForPath parses a spec for a path to a Value.

func ForPathOpts

func ForPathOpts(spec string, opts SpecOptions) (Spec, error)

ForPathOpts parses a spec for a path to a Value.

func (Spec) Close

func (sp Spec) Close() error

func (Spec) GetDatabase

func (sp Spec) GetDatabase() datas.Database

GetDatabase returns the Database instance that this Spec's DatabaseName describes. The same Database instance is returned every time, unless Close is called. If the Spec is closed, it is re-opened with a new Database.

func (Spec) GetDataset

func (sp Spec) GetDataset() (ds datas.Dataset)

GetDataset returns the current Dataset instance for this Spec's Database. GetDataset is live, so if Commit is called on this Spec's Database later, a new up-to-date Dataset will returned on the next call to GetDataset. If this is not a Dataset spec, returns nil.

func (Spec) GetValue

func (sp Spec) GetValue() (val types.Value)

GetValue returns the Value at this Spec's Path within its Database, or nil if this isn't a Path Spec or if that path isn't found.

func (Spec) Href

func (sp Spec) Href() string

Href treats the Protocol and DatabaseName as a URL, and returns its href. For example, the spec http://example.com/path::ds returns "http://example.com/path". If the Protocol is not "http" or "http", returns an empty string.

func (Spec) NewChunkStore

func (sp Spec) NewChunkStore() chunks.ChunkStore

NewChunkStore returns a new ChunkStore instance that this Spec's DatabaseName describes. It's unusual to call this method, GetDatabase is more useful. Unlike GetDatabase, a new ChunkStore instance is returned every time. If there is no ChunkStore, for example remote databases, returns nil.

func (Spec) Pin

func (sp Spec) Pin() (Spec, bool)

Pin returns a Spec in which the dataset component, if any, has been replaced with the hash of the HEAD of that dataset. This "pins" the path to the state of the database at the current moment in time. Returns itself if the PathSpec is already "pinned".

func (Spec) String

func (sp Spec) String() string

type SpecOptions

type SpecOptions struct {
	// Authorization token for requests. For example, if the database is HTTP
	// this will used for an `Authorization: Bearer ${authorization}` header.
	Authorization string
}

SpecOptions customize Spec behavior.