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