dab

Documentation

Overview

Package dab -- short for Data Access Broker -- contains functions that help save and load data, mostly to a local filesystem (but sometimes to a blind content-addressed objectstore, as well).

Most dab functions return objects from the wfapi package. Some return a dab type, in which case that object is to help manage further access -- but eventually you should still reach wfapi data types.

Functions that deal with the filesystem may expect to be dealing with either a workspace filesystem (e.g., commingled with other user files), or a catalog filesystem projection (a somewhat stricter situation). Sometimes these are the same. The function name should provide a hint about which situations it handles.

Sometimes, search features are provided for workspace filesystems, since there is no other index of those contents aside from the filesystem itself.

Most of these functions return the "latest" version of their relevant API type. At the moment, that's not saying much, because we haven't grown in such a way that we support major varations of API object reversions -- but in the future, this means these functions may do "migrational" transforms to the data on the fly.

Index

• Constants
• func ModuleFromFile(fsys fs.FS, filename string) (wfapi.Module, error)
• func PlotFromFile(fsys fs.FS, filename string) (wfapi.Plot, error)
• func ValidateModuleName(moduleName wfapi.ModuleName) error
• type FileType
  • func GetFileType(name string) (FileType, error)

Constants

const (
	MagicFilename_Module = "module.wf"
	MagicFilename_Plot   = "plot.wf"
)

const (
	MagicFilename_Workspace     = ".warpforge"
	MagicFilename_HomeWorkspace = ".warphome"
)

const MagicFilename_Formula = "formula.wf"

Functions

func ModuleFromFile

func ModuleFromFile(fsys fs.FS, filename string) (wfapi.Module, error)

ModuleFromFile loads a wfapi.Module from filesystem path.

In typical usage, the filename parameter will have the suffix of MagicFilename_Module.

Errors:

• warpforge-error-io -- for errors reading from fsys.
• warpforge-error-serialization -- for errors from try to parse the data as a Module.
• warpforge-error-datatoonew -- if encountering unknown data from a newer version of warpforge!
• warpforge-error-module-invalid -- when module name is invalid

func PlotFromFile

func PlotFromFile(fsys fs.FS, filename string) (wfapi.Plot, error)

PlotFromFile loads a wfapi.Plot from filesystem path.

In typical usage, the filename parameter will have the suffix of MagicFilename_Plot.

Errors:

• warpforge-error-io -- for errors reading from fsys.
• warpforge-error-serialization -- for errors from try to parse the data as a Plot.
• warpforge-error-datatoonew -- if encountering unknown data from a newer version of warpforge!

func ValidateModuleName

func ValidateModuleName(moduleName wfapi.ModuleName) error

ValidateModuleName checks the module name for invalid strings.

Examples of valid module names:

• foobar
• foo.bar/grill
• foo-bar

"Path segments" are defined as the segments separated by forward slash "/". "Domain segments" are defined as the segments separated by dot "." and only applies to the first path segment.

A module name must resemble a domain name (per DNS RFC 1123 & 1035) with optional subsequent path segments. I.E.

[[[...]]]subdomain.]subdomain.]domain[/path[/morepath[...]]]

The rules are summarized as following:

• Name MUST contain only:
• ASCII lowercase alpha-numeric characters
• hyphens '-'
• dots '.'
• forward slash '/'.
• Name MUST start AND end each path or domain segment with an ASCII lowercase alpha-numeric character.
• First path segment of the name MUST be 253 characters or less
• Each domain segment MUST only include ASCII, lowercase, alpha-numeric characters and hyphens '-'
• Each domain segment MUST be 63 characters or less

Errors:

• warpforge-error-module-invalid -- when module name is invalid

Types

type FileType

type FileType string

const (
	FileType_Module  FileType = "module"
	FileType_Plot    FileType = "plot"
	FileType_Formula FileType = "formula"
)

func GetFileType

func GetFileType(name string) (FileType, error)

GetFileType returns the file type, which is the file name without extension e.g., formula.wf -> formula, module.wf -> module, etc...

Errors:

• warpforge-error-invalid -- if the file name is not recognized