Documentation
¶
Overview ¶
Package database reads and writes ZenNotes databases: a `<Name>.base/` folder holding `data.csv`, a `schema.json` sidecar and record-page notes. Everything is composed from generic vault-file IO, the same composition the web and desktop remote clients use, so an edit made here is byte-identical to one made in the app's grid.
Index ¶
- Constants
- Variables
- func CSVPathForFormDir(formDir string) string
- func FieldTypeLabel(t string) string
- func FilterNeedsValue(op string) bool
- func FilterOpLabel(op string) string
- func FilterOps(fieldType string) []string
- func FormDirContaining(relPath string) string
- func FormDirFromCSVPath(csvPath string) string
- func GenID() string
- func HasRecordPages(csvPath string) bool
- func IsCheckboxTrue(cell string) bool
- func IsFormDirName(nameOrPath string) bool
- func IsLooseCSVPath(rel string) bool
- func IsNoteType(t string) bool
- func IsSelectType(t string) bool
- func IsSidecarPath(rel string) bool
- func JoinMultiSelect(values []string) string
- func JoinNoteLinks(targets []string) string
- func ParseCSV(text string) [][]string
- func SchemaPathFor(csvPath string) string
- func SerializeCSV(rows [][]string) string
- func SerializeRows(rows []Row, fields []Field) string
- func SplitMultiSelect(cell string) []string
- func SplitNoteLinks(cell string) []string
- func Stringify(o *Object) (string, error)
- func TitleFromCSVPath(csvPath string) string
- func TitleFromDir(nameOrPath string) string
- type BoardColumn
- type CSVLister
- type Doc
- func (d *Doc) ActiveView() *View
- func (d *Doc) AddField(name, typ string) (Field, error)
- func (d *Doc) AddRow() Row
- func (d *Doc) AddView(typ string) (View, error)
- func (d *Doc) ComposePageBody(row Row, body string) string
- func (d *Doc) DeleteField(id string) error
- func (d *Doc) DeleteRow(rowID string)
- func (d *Doc) DuplicateRow(rowID string) (Row, bool)
- func (d *Doc) EnsureSelectOption(fieldID, rawValue string) bool
- func (d *Doc) FieldByID(id string) *Field
- func (d *Doc) HiddenColumns(viewID string) []Field
- func (d *Doc) MoveColumn(viewID, fieldID, direction string) error
- func (d *Doc) RecordTitle(row Row) string
- func (d *Doc) RemoveSelectOption(fieldID, value string) error
- func (d *Doc) RemoveView(viewID string) error
- func (d *Doc) RenameField(id, name string) error
- func (d *Doc) RenameView(viewID, name string) error
- func (d *Doc) Resync() error
- func (d *Doc) RetypeField(id, typ string) error
- func (d *Doc) RowByID(id string) *Row
- func (d *Doc) SetActiveView(viewID string) error
- func (d *Doc) SetBoardColumnOrder(viewID string, order []string) error
- func (d *Doc) SetCardFields(viewID string, fieldIDs []string) error
- func (d *Doc) SetCell(rowID, fieldID, value string)
- func (d *Doc) SetFieldHidden(viewID, fieldID string, hidden bool) error
- func (d *Doc) SetFieldOptionsSource(fieldID string, source *OptionsSource) error
- func (d *Doc) SetGroupBy(viewID, fieldID string) error
- func (d *Doc) SetOptionColor(fieldID, value, color string) error
- func (d *Doc) SetViewFilters(viewID string, filters []FilterRule, conjunction string) error
- func (d *Doc) SetViewSorts(viewID string, sorts []SortRule) error
- func (d *Doc) TitleFieldID() string
- func (d *Doc) ViewByID(id string) *View
- func (d *Doc) VisibleColumns(viewID string) []Field
- type Field
- type FileMover
- type FileOps
- type FilterRule
- type Layout
- type Object
- func (o *Object) Array(key string) []any
- func (o *Object) Bool(key string) bool
- func (o *Object) Clone() *Object
- func (o *Object) Delete(key string)
- func (o *Object) Get(key string) (any, bool)
- func (o *Object) Keys() []string
- func (o *Object) MarshalJSON() ([]byte, error)
- func (o *Object) Object(key string) *Object
- func (o *Object) Set(key string, value any)
- func (o *Object) String(key string) string
- func (o *Object) UnmarshalJSON(data []byte) error
- type Ops
- func (o *Ops) ConvertToFolder(csvPath string) (string, error)
- func (o *Ops) CreateDatabase(folder vault.NoteFolder, subpath, title string) (*Doc, error)
- func (o *Ops) CreateRecordPage(csvPath, title, body string) (string, error)
- func (o *Ops) ListDatabases() ([]Summary, error)
- func (o *Ops) OpenDatabase(csvPath string) (*Doc, error)
- func (o *Ops) RenameDatabase(csvPath, newTitle string) (string, error)
- func (o *Ops) WriteRows(csvPath string, rows []Row) (*Doc, error)
- func (o *Ops) WriteSchema(csvPath string, doc *Doc) (*Doc, error)
- type OptionsSource
- type Row
- type SelectOption
- type SortRule
- type Summary
- type View
Constants ¶
const ( // FormDirSuffix marks a database folder. FormDirSuffix = ".base" // FormDataFile and FormSchemaFile are the fixed names inside it. FormDataFile = "data.csv" FormSchemaFile = "schema.json" // EmptyGroup is the board column for rows whose group-by cell is empty. EmptyGroup = "__empty__" )
const SidecarSuffix = ".base.json"
SidecarSuffix follows a loose `.csv` to name its schema file: `Books.csv` keeps its schema in `Books.csv.base.json`.
Variables ¶
var FieldTypes = []string{"text", "number", "checkbox", "date", "select", "multiSelect", "note", "noteMulti"}
FieldTypes lists the field types in the order the desktop offers them.
var OptionColors = []string{"red", "orange", "amber", "green", "teal", "sky", "blue", "indigo", "violet", "pink"}
OptionColors are the palette tokens the desktop assigns to options.
Functions ¶
func CSVPathForFormDir ¶
CSVPathForFormDir is `<dir>/data.csv`.
func FieldTypeLabel ¶
FieldTypeLabel is the display name of a field type.
func FilterNeedsValue ¶
FilterNeedsValue is false for operators that take no value.
func FilterOpLabel ¶
FilterOpLabel is the operator's display text.
func FormDirContaining ¶
FormDirContaining is the `.base` folder a path lives in, or "".
func FormDirFromCSVPath ¶
FormDirFromCSVPath is the database folder for a `data.csv` path, or "".
func GenID ¶
func GenID() string
GenID mints a lowercase v4 UUID, the row and field identity the app uses.
func HasRecordPages ¶
HasRecordPages is true when a database can own record pages: only `.base` folders have a pages directory.
func IsFormDirName ¶
IsFormDirName is true for a `<Name>.base` folder name or path.
func IsLooseCSVPath ¶
IsLooseCSVPath is true for a `.csv` outside any `.base` folder.
func IsNoteType ¶
IsNoteType is true for the two wikilink-backed types.
func IsSelectType ¶
IsSelectType is true for the two option-backed types.
func IsSidecarPath ¶
IsSidecarPath is true for a loose CSV's schema file.
func JoinMultiSelect ¶
JoinMultiSelect composes a multiSelect cell.
func JoinNoteLinks ¶
JoinNoteLinks composes a note cell from targets: `[[A]] [[B]]`.
func ParseCSV ¶
ParseCSV parses RFC 4180 text into a grid. Blank lines are dropped; a BOM is stripped.
func SchemaPathFor ¶
SchemaPathFor is `<dir>/schema.json` for a `.base` folder's data.csv, `<file>.csv.base.json` for a loose CSV, or "" for anything else.
func SerializeCSV ¶
SerializeCSV renders a grid as RFC 4180 text with LF newlines and a trailing newline.
func SerializeRows ¶
SerializeRows renders rows back to CSV text, header from the field names in field order.
func SplitMultiSelect ¶
SplitMultiSelect splits a multiSelect cell ("a, b") into values.
func SplitNoteLinks ¶
SplitNoteLinks extracts the wikilink targets of a note cell, in order.
func TitleFromCSVPath ¶
TitleFromCSVPath is the display title from a data.csv path.
func TitleFromDir ¶
TitleFromDir is the display title of a database folder.
Types ¶
type BoardColumn ¶
BoardColumn is one column of a board view.
func BoardColumns ¶
func BoardColumns(rows []Row, groupField Field, optionOrder []string) []BoardColumn
BoardColumns groups rows by a select field's value, an EmptyGroup column appended for rows whose cell is empty or references a removed option.
type CSVLister ¶
CSVLister is implemented by backends that can find loose `.csv` files; without it only `.base` folders are databases.
type Doc ¶
type Doc struct {
// Path is the vault-relative `data.csv` path: the database's identity.
Path string
Title string
// Sidecar is the normalized schema.json with pages made vault-relative.
Sidecar *Object
IDFieldID string
Fields []Field
Views []View
ActiveViewID string
// Pages maps row id to the record page's vault-relative path.
Pages map[string]string
Rows []Row
// PageHasContent says whether a row's page has body beyond its heading.
PageHasContent map[string]bool
}
Doc is a fully hydrated database.
func (*Doc) ActiveView ¶
ActiveView is the view the sidecar marks active, else the first.
func (*Doc) ComposePageBody ¶
ComposePageBody composes a record page: the row's properties as flat YAML frontmatter (id and title fields omitted) followed by body.
func (*Doc) DeleteField ¶
DeleteField removes a field everywhere it is referenced. The id field stays.
func (*Doc) DuplicateRow ¶
DuplicateRow copies a row's cells into a new row placed after it.
func (*Doc) EnsureSelectOption ¶
EnsureSelectOption mints an option for a select field when the value is new. Option values may not contain commas (the multiSelect separator). Returns true when the schema changed.
func (*Doc) HiddenColumns ¶
HiddenColumns lists the fields a table view hides (never the id field).
func (*Doc) MoveColumn ¶
MoveColumn shifts a column one visible step left or right in a table view; a no-op at the edges.
func (*Doc) RecordTitle ¶
RecordTitle is a row's display title: the title field's value or Untitled.
func (*Doc) RemoveSelectOption ¶
RemoveSelectOption drops an option from a select field.
func (*Doc) RemoveView ¶
RemoveView deletes a view, keeping at least one.
func (*Doc) RenameField ¶
RenameField changes the CSV header of a field.
func (*Doc) RenameView ¶
RenameView changes a view's name.
func (*Doc) RetypeField ¶
RetypeField changes a field's type, keeping the raw cell values.
func (*Doc) SetActiveView ¶
SetActiveView records which view opens by default.
func (*Doc) SetBoardColumnOrder ¶
SetBoardColumnOrder stores the column order of a board view.
func (*Doc) SetCardFields ¶
SetCardFields chooses which fields a board card shows.
func (*Doc) SetFieldHidden ¶
SetFieldHidden hides or shows a column in a table view.
func (*Doc) SetFieldOptionsSource ¶
func (d *Doc) SetFieldOptionsSource(fieldID string, source *OptionsSource) error
SetFieldOptionsSource points a select field at notes for its options, or back to the manual list when source is nil.
func (*Doc) SetGroupBy ¶
SetGroupBy points a board view at a select field.
func (*Doc) SetOptionColor ¶
SetOptionColor records a palette token for a select option.
func (*Doc) SetViewFilters ¶
func (d *Doc) SetViewFilters(viewID string, filters []FilterRule, conjunction string) error
SetViewFilters replaces a view's filters and how they combine.
func (*Doc) SetViewSorts ¶
SetViewSorts replaces a view's sort rules.
func (*Doc) TitleFieldID ¶
TitleFieldID is the first non-id field: the record title column.
func (*Doc) VisibleColumns ¶
VisibleColumns lists a table view's fields in display order, minus the hidden ones and the id column.
type Field ¶
type Field struct {
ID string
Name string
Type string
Options []SelectOption
Hidden bool
// OptionsSource, when set, discovers select options from notes instead
// of the explicit list: every note, a folder's notes, or a tag's.
OptionsSource *OptionsSource
// contains filtered or unexported fields
}
Field is one typed column.
func InferFields ¶
InferFields builds fields (and picks the id field) for a CSV that has no sidecar yet. A usable `id` column (all unique, non-empty) becomes the id field; otherwise a leading hidden `id` field is synthesized.
type FileMover ¶
FileMover is implemented by backends that can rename a file in place, which loose-CSV renames and conversions need.
type FileOps ¶
type FileOps interface {
ReadFileTextOrNull(rel string) (*string, error)
WriteFile(rel, text string) error
CreateFolder(folder vault.NoteFolder, subpath string) error
RenameFolder(folder vault.NoteFolder, oldSubpath, newSubpath string) (string, error)
// ListFolders must include `.base` folders.
ListFolders() ([]vault.FolderEntry, error)
VaultLayout() (Layout, error)
}
FileOps is the generic vault-file IO a transport provides. ReadFileTextOrNull must return nil for an ABSENT file and an error for anything else: nil is read as "no schema yet" and a schema is then inferred and written.
type FilterRule ¶
FilterRule is one view filter.
type Object ¶
type Object struct {
// contains filtered or unexported fields
}
Object is a JSON object that remembers key order. schema.json is user-visible and user-editable, and the app re-serializes it as parsed, so a round trip through here must keep every key where it was, known or not.
func DefaultView ¶
DefaultView is a single Table view (id hidden) over the fields in order.
func ParseObject ¶
ParseObject decodes JSON text into an ordered object.
func (*Object) MarshalJSON ¶
MarshalJSON encodes the object in key order without HTML escaping, the way JSON.stringify does.
func (*Object) UnmarshalJSON ¶
UnmarshalJSON decodes an object keeping key order; numbers stay as json.Number so their spelling survives a round trip.
type Ops ¶
type Ops struct {
// contains filtered or unexported fields
}
Ops composes database operations over FileOps.
func (*Ops) ConvertToFolder ¶
ConvertToFolder turns a loose CSV into a `<Name>.base` folder database, which is what record pages need. It returns the new data.csv path.
func (*Ops) CreateDatabase ¶
CreateDatabase creates an empty database with an id and a Name field.
func (*Ops) CreateRecordPage ¶
CreateRecordPage writes a record page note inside the database folder and returns its vault-relative path.
func (*Ops) ListDatabases ¶
ListDatabases finds every `.base` folder.
func (*Ops) OpenDatabase ¶
OpenDatabase hydrates a database. A CSV without a sidecar is adopted: its schema is inferred and materialized, and its rows re-written with ids.
func (*Ops) RenameDatabase ¶
RenameDatabase renames the `.base` folder and returns the new csv path.
type OptionsSource ¶
type OptionsSource struct {
Kind string // notes, folder, tag
Path string // folder: vault-relative directory
Tag string // tag: without the #
}
OptionsSource names where a select field's options come from.
func (*OptionsSource) Describe ¶
func (s *OptionsSource) Describe() string
Describe is the source's display text.
type Row ¶
Row is one record; cells are raw CSV strings keyed by field id.
func FilterRows ¶
func FilterRows(rows []Row, filters []FilterRule, doc *Doc, conjunction string) []Row
FilterRows applies a view's filters; `or` keeps rows matching any rule.
type SelectOption ¶
SelectOption is one pickable value of a select field.
type View ¶
type View struct {
ID string
Name string
Type string
Filters []FilterRule
FilterConjunction string
Sorts []SortRule
ColumnOrder []string
HiddenFieldIDs []string
GroupByFieldID string
BoardColumnOrder []string
// CardFieldIDs lists the fields a board card shows under its title;
// empty means every field.
CardFieldIDs []string
}
View is a saved table or board configuration.