Documentation
¶
Overview ¶
Package dsref defines structure and syntax for referring to a dataset
Index ¶
- Constants
- Variables
- func EnsureValidName(text string) error
- func EnsureValidUsername(text string) error
- func GenerateName(input, prefix string) string
- func IsRefString(text string) bool
- func IsValidName(text string) bool
- type Loader
- type MemResolver
- type ParseResolveLoad
- type Ref
- type Resolver
- type Rev
- type State
- type VersionInfo
Constants ¶
const AllGenerations = -1
AllGenerations represents all the generations of a dataset's history
const PuncCharacters = "`~!@#$%^&*()=+[{]}\\|;:'\",<.>/?"
PuncCharacters is the list of punctuation characters that get converted to dashes
Variables ¶
var ( // ErrEmptyRef is an error for when a reference is empty ErrEmptyRef = fmt.Errorf("empty reference") // ErrParseError is an error returned when parsing fails ErrParseError = fmt.Errorf("could not parse ref") // ErrUnexpectedChar is an error when a character is unexpected, topic string must be non-empty ErrUnexpectedChar = fmt.Errorf("unexpected character") // ErrNotHumanFriendly is an error returned when a reference is not human-friendly ErrNotHumanFriendly = fmt.Errorf("unexpected character '@', ref can only have username/name") // ErrBadCaseName is the error when a bad case is used in the dataset name ErrBadCaseName = fmt.Errorf("dataset name may not contain any upper-case letters") // ErrBadCaseUsername is for when a username contains upper-case letters ErrBadCaseUsername = fmt.Errorf("username may not contain any upper-case letters") // ErrBadCaseShouldRename is the error when a dataset should be renamed to not use upper case letters ErrBadCaseShouldRename = fmt.Errorf("dataset name should not contain any upper-case letters, rename it to only use lower-case letters, numbers, and underscores") // ErrDescribeValidName is an error describing a valid dataset name ErrDescribeValidName = fmt.Errorf("dataset name must start with a lower-case letter, and only contain lower-case letters, numbers, dashes, and underscore. Maximum length is 144 characters") // ErrDescribeValidUsername describes valid username ErrDescribeValidUsername = fmt.Errorf("username must start with a lower-case letter, and only contain lower-case letters, numbers, dashes, and underscores") )
var ( // ErrRefNotFound must be returned by a ref resolver that cannot resolve a // given reference ErrRefNotFound = errors.New("reference not found") // ErrPathRequired should be returned by functions that require a reference // have a path value, but got none. // ErrPathRequired should *not* be returned by implentationf of the // ResolveRef interface ErrPathRequired = errors.New("reference path value is required") )
var ErrNoHistory = fmt.Errorf("no history")
ErrNoHistory indicates a resolved reference has no HEAD path
var NameMaxLength = 44
NameMaxLength is the maximum length of a name that will be generated
Functions ¶
func EnsureValidName ¶ added in v0.9.8
EnsureValidName returns nil if the name is valid, and an error otherwise
func EnsureValidUsername ¶ added in v0.9.8
EnsureValidUsername is the same as EnsureValidName but returns a different error
func GenerateName ¶ added in v0.9.8
GenerateName converts the input into a valid dataset string, which starts with a lower-case letter, and only has letters, digits, dashes and underscores.
func IsRefString ¶ added in v0.9.5
IsRefString returns whether the string parses as a valid reference
func IsValidName ¶ added in v0.9.5
IsValidName returns whether the dataset name is valid
Types ¶
type Loader ¶ added in v0.9.9
type Loader interface {
LoadDataset(ctx context.Context, ref Ref, source string) (*dataset.Dataset, error)
}
Loader loads and opens a dataset. The only useful implementation of the loader interface is in github.com/qri-io/qri/lib. TODO(b5) - This interface is a work-in-progress
type MemResolver ¶ added in v0.9.9
type MemResolver struct {
Username string
RefMap map[string]string
IDMap map[string]VersionInfo
}
MemResolver holds maps that can do a cheap version of dataset resolution, for tests
func NewMemResolver ¶ added in v0.9.9
func NewMemResolver(username string) *MemResolver
NewMemResolver returns a new MemResolver
func (*MemResolver) GetInfo ¶ added in v0.9.9
func (m *MemResolver) GetInfo(initID string) *VersionInfo
GetInfo returns a VersionInfo by initID, or nil if not found
func (*MemResolver) Put ¶ added in v0.9.9
func (m *MemResolver) Put(info VersionInfo)
Put adds a VersionInfo to the resolver
func (*MemResolver) ResolveRef ¶ added in v0.9.9
ResolveRef finds the identifier & head path for a dataset reference implements resolve.NameResolver interface
type ParseResolveLoad ¶ added in v0.9.9
ParseResolveLoad is a function that combines dataset reference parsing, reference resolution, and loading in one function, turning a reference string into a dataset pointer
type Ref ¶
type Ref struct {
// InitID is the canonical identifer for a dataset history
InitID string `json:"initID,omitempty"`
// Username of dataset owner
Username string `json:"username,omitempty"`
// ProfileID of dataset owner
ProfileID string `json:"profileID,omitempty"`
// Unique name reference for this dataset
Name string `json:"name,omitempty"`
// Content-addressed path for this dataset
Path string `json:"path,omitempty"`
}
Ref is a reference to a dataset
func ParseHumanFriendly ¶ added in v0.9.5
ParseHumanFriendly parses a reference that only has a username and a dataset name
func (Ref) Human ¶ added in v0.9.9
Human returns the human-friendly representation of the reference example: some_user/my_dataset
func (Ref) VersionInfo ¶ added in v0.9.9
func (r Ref) VersionInfo() VersionInfo
VersionInfo creates a new sparse VersionInfo from a reference
type Resolver ¶ added in v0.9.9
type Resolver interface {
// ResolveRef uses ref as an outParam, setting ref.ID and ref.Path on success
// some implementations of name resolution may make network calls
// the returned "source" value should be either an empty string, indicating
// the source was resolved locally, or the multiaddress of the network
// address that performed the resolution
ResolveRef(ctx context.Context, ref *Ref) (source string, err error)
}
Resolver finds the identifier and HEAD path for a dataset reference
func ParallelResolver ¶ added in v0.9.9
ParallelResolver composes multiple resolvers into one resolver that runs in parallel when called, using the first resolver that doesn't return ErrRefNotFound
func SequentialResolver ¶ added in v0.9.9
SequentialResolver composes multiple resolvers into one that runs each resolver in sequence, using the first resolver that doesn't return ErrorNotFound
type Rev ¶
type Rev struct {
// field scopt, currently can only be a component name, or the entire dataset
Field string
// the nth-generational ancestor of a history
Gen int
}
Rev names a field of a dataset at a snapshot relative to the latest version in a history Much of this is inspired by git revisions: https://git-scm.com/docs/gitrevisions
Unlike git, Qri is aware of the underlying data model it's selecting against, so revisions can have conventional names for specifying fields of a dataset
func NewAllRevisions ¶
func NewAllRevisions() Rev
NewAllRevisions returns a Rev struct that represents all revisions.
type State ¶ added in v0.9.8
type State int
State is used to handle the state machine that processes strings
const ( // StateNone is for being outside of a word, looking at spaces StateNone State = 0 // StateLowerWord is for looking at a word made-up of lower-case letters StateLowerWord State = 1 // StateFirstUpper is for looking at the first upper-case letter of a word StateFirstUpper State = 2 // StateCapsWord is for looking at a word made up of all upper-case letters StateCapsWord State = 3 // StateNumber is for looking at a sequence of digits StateNumber State = 4 // StatePunc is for looking at punctuation characters StatePunc State = 5 // StateExit is set by flush in order to exit the top-level loop immediately StateExit State = 6 )
type VersionInfo ¶ added in v0.9.5
type VersionInfo struct {
//
// Key as a stable identifier
//
// InitID is derived from the logbook for the dataset
InitID string `json:"initID,omitempty"`
//
// Fields from dsref.Ref
//
// Username of dataset owner
Username string `json:"username,omitempty"`
// ProfileID of dataset owner
ProfileID string `json:"profileID,omitempty"`
// Unique name reference for this dataset
Name string `json:"name,omitempty"`
// Content-addressed path for this dataset
Path string `json:"path,omitempty"`
//
// State about the dataset that can change
//
// If true, this dataset has published versions
Published bool `json:"published,omitempty"`
// If true, this reference doesn't exist locally. Only makes sense if path is set, as this
// flag refers to specific versions, not to entire dataset histories.
Foreign bool `json:"foreign,omitempty"`
//
// Meta fields
//
// Title from the meta structure
MetaTitle string `json:"metaTitle,omitempty"`
// List of themes from the meta structure, comma-separated list
ThemeList string `json:"themeList,omitempty"`
//
// Structure fields
//
// Size of the body in bytes
BodySize int `json:"bodySize,omitempty"`
// Num of rows in the body
BodyRows int `json:"bodyRows,omitempty"`
// Format of the body, such as "csv" or "json"
BodyFormat string `json:"bodyFromat,omitempty"`
// Number of errors from the structure
NumErrors int `json:"numErrors,omitempty"`
//
// Commit fields
//
// Timestamp field from the commit
CommitTime time.Time `json:"commitTime,omitempty"`
//
// About the dataset's history and location
//
// Number of versions that the dataset has
NumVersions int `json:"numVersions,omitempty"`
// FSIPath is this dataset's link to the local filesystem if one exists
FSIPath string `json:"fsiPath,omitempty"`
}
VersionInfo describes a dataset reference and detailed information about it
func ConvertDatasetToVersionInfo
deprecated
added in
v0.9.5
func ConvertDatasetToVersionInfo(ds *dataset.Dataset) VersionInfo
ConvertDatasetToVersionInfo assigns values form a dataset to a VersionInfo This function is a shim while we work on building up dscache as a store of VersionInfo.
Deprecated: Don't use this function for new code. Instead reference a VersionInfo that is stored somewhere, or write a function that builds a VersionInfo without needing a dataset
func (*VersionInfo) Alias ¶ added in v0.9.5
func (v *VersionInfo) Alias() string
Alias returns the alias components of a Ref as a string
func (*VersionInfo) SimpleRef ¶ added in v0.9.5
func (v *VersionInfo) SimpleRef() Ref
SimpleRef returns a simple dsref.Ref
Source Files
Directories