README
¶
core/docs
Reads and writes a workspace's files for AutoDoc's own apps, over the workspace
root's golib vfs.FS. A read returns the content with the version it was read at; every write is
conditional on the version the writer read, so no writer replaces what it has not seen, and the
index learns of the write as it learns of an external edit. A derived format (a PDF, a DOCX) reads
as the text the build's deriver makes of it, and is read-only.
| Name | What |
|---|---|
New(fsys, eligible, opts...) |
the *Docs of fsys that eligible admits (the workspace's include and exclude; nil admits every path) |
WithTextExtensions(text) |
the workspace's own plain-text extensions, asked at each read and write |
WithRegistrations(r) |
reads the build's registered extensions as their kind (UTF-8 text, checked on a write) |
WithDeriver(reg) |
reads the formats reg derives as their derived text, read-only |
Doc |
a document's Content at a Version |
(*Docs).Admits(path) |
whether path is a document: eligible, and a format the build reads |
(*Docs).Derived(path) |
whether Read returns text derived from path, not its own bytes |
(*Docs).Read(ctx, path) |
the document and the version its content was read at (stat'ed before and after, read again when it moved) |
(*Docs).ReadRaw(ctx, path) |
Read without deriving, for a derived format whose source is text (HTML); any other derived format is refused |
(*Docs).Write(ctx, path, content, want) |
writes if the document is still at want; want "" creates it and the folders above it. A stale want is a *vfs.ConflictError |
(*Docs).WriteRaw(ctx, path, content, want) |
Write that admits a derived format whose source is text, with UTF-8 content |
(*Docs).Rename(ctx, from, to) |
moves a document to a path where nothing is yet |
(*Docs).Remove(ctx, path, want) |
deletes the document if it is still at want |
MaxSize |
the largest document read or written: 4 MiB less 64 KiB |
TruncatedMark |
begins the last line of a derived text cut to fit one read |
ErrCommitted |
the write landed, then a follow-up step failed: no version is promised; read and compare, never resend |
ErrNotEligible |
a path the workspace does not index or a derived format the build does not derive; raw access to a derived format with no raw text; content that is not the UTF-8 text its kind requires |
ErrTooLarge |
a document over MaxSize, or a derived document's file over derived.MaxContainer |
ErrReadOnly |
a write, rename or removal of a derived document |
A Docs is not changed after New and holds no lock: its methods may be called from any number of
goroutines when the vfs.FS, eligible, the WithTextExtensions function and the deriver are safe
for concurrent use. Two writers of one path are kept apart by the vfs.FS's conditional writes, not
by Docs.
Documentation
¶
Overview ¶
Package docs reads and writes a workspace's files for AutoDoc's own apps. A Docs works over one workspace root, given as a golib vfs.FS; it never opens a file any other way.
A read returns the content with the version it was read at: the file is stat'ed before and after the read, and read again when the version moved, so the version names the bytes returned. Every write goes through the vfs, conditional on the version the writer read (a create on the path not existing yet), so the index learns of it the same way it learns of an external edit, and no writer replaces what it has not seen. A path the workspace does not index is refused (ErrNotEligible), and so is a document over MaxSize (ErrTooLarge).
A derived format (a PDF, a DOCX: a file the build's deriver turns into text) reads as its derived text, cut to fit one read when it is longer (TruncatedMark), and is read-only (ErrReadOnly). ReadRaw and WriteRaw reach the file's own bytes of a derived format whose source is text (HTML).
Concurrency: New sets a Docs's fields and no method changes them; a Docs holds no lock and starts no goroutine. Its methods may be called from any number of goroutines when the vfs.FS, the eligible function, the WithTextExtensions function and the WithDeriver table's deriver are safe for concurrent use. Two writers of one path are kept apart by the vfs.FS's conditional operations (CreateExclusive, WriteFileIf, RenameNoReplace, RemoveIf), not by Docs.
Index ¶
- Constants
- Variables
- type Doc
- type Docs
- func (d *Docs) Admits(path string) bool
- func (d *Docs) Derived(path string) bool
- func (d *Docs) Read(ctx context.Context, path string) (Doc, error)
- func (d *Docs) ReadRaw(ctx context.Context, path string) (Doc, error)
- func (d *Docs) Remove(ctx context.Context, path string, want vfs.Version) error
- func (d *Docs) Rename(ctx context.Context, from, to string) error
- func (d *Docs) Write(ctx context.Context, path string, content []byte, want vfs.Version) (vfs.Version, error)
- func (d *Docs) WriteRaw(ctx context.Context, path string, content []byte, want vfs.Version) (vfs.Version, error)
- type Option
Constants ¶
const MaxSize = 4<<20 - 64<<10
MaxSize is the largest document read or written: the RPC message limit (4 MiB), less room for the message around it. A larger file is refused, never truncated. A derived document's text is the one exception: it is cut to fit, and says so (Read).
const TruncatedMark = "[autodoc: truncated]"
TruncatedMark begins the last line of a derived text cut to fit one read. The line is AutoDoc's, never the document's: a reader quoting the text stops before it.
Variables ¶
var ( // ErrCommitted is a write that landed, then a follow-up step failed (Committed, -32066): the // change took effect but no version can be promised. The client reads the document and compares; // it never sends the write again. ErrCommitted = errs.Sentinel(errs.ErrPrecondition, "docs: the write landed, then a follow-up step failed") // ErrNotEligible is a path the workspace does not index (outside include, inside exclude): // AutoDoc's apps edit files, not every file under the root. ErrNotEligible = errs.Sentinel(errs.ErrInvalidArgument, "docs: not a file of this workspace") // ErrTooLarge is a document over MaxSize, or a derived document's file over derived.MaxContainer. ErrTooLarge = errs.Sentinel(errs.ErrInvalidArgument, "docs: the document is over the size limit") // ErrReadOnly is a write, a rename or a removal of a derived document: AutoDoc serves its // text, and never changes the file it was made of. ErrReadOnly = errs.Sentinel(errs.ErrInvalidArgument, "docs: a derived document is read-only") )
Functions ¶
This section is empty.
Types ¶
type Docs ¶
type Docs struct {
// contains filtered or unexported fields
}
Docs is the document API over one workspace root.
func (*Docs) Admits ¶ added in v0.1.25
Admits reports whether path is a document of these: eligible, and a format the build reads.
func (*Docs) Derived ¶ added in v0.1.15
Derived reports whether path is a format the build derives: Read returns text derived from the file, not the file's own bytes.
func (*Docs) Read ¶
Read returns the document at path with the version its content was read at. The file is stat'ed before and after the read, and read again when it changed in between, so the version never names other bytes than the ones returned.
func (*Docs) ReadRaw ¶ added in v0.1.32
ReadRaw is Read without deriving: the file's own bytes and their version, for a derived format whose source is text (kind.RawText: HTML), so it can be edited. Any other document reads as Read reads it; any other derived format is refused, whatever its bytes.
func (*Docs) Write ¶
func (d *Docs) Write(ctx context.Context, path string, content []byte, want vfs.Version) (vfs.Version, error)
Write writes content to path if the document is still at version want, and returns the new version. want "" creates a document that must not exist yet, and the folders above it. A stale want, or an existing path for a create, fails with a *vfs.ConflictError and leaves the file as it is.
func (*Docs) WriteRaw ¶ added in v0.1.32
func (d *Docs) WriteRaw(ctx context.Context, path string, content []byte, want vfs.Version) (vfs.Version, error)
WriteRaw is Write that admits a derived format whose source is text (kind.RawText: HTML), with text bytes: the file's own bytes, edited. Any other derived format is refused before anything is written, whatever the version: an existing PDF is never replaced.
type Option ¶ added in v0.1.9
type Option func(*Docs)
Option configures Docs.
func WithDeriver ¶ added in v0.1.13
func WithDeriver(reg *registrations.Table) Option
WithDeriver reads the formats reg derives as their derived text, read-only.
func WithRegistrations ¶ added in v0.1.12
func WithRegistrations(r kind.Registrations) Option
WithRegistrations reads files of the build's registered extensions as their kind (kind.Registered: UTF-8 text, validated as such on a write).
func WithTextExtensions ¶ added in v0.1.9
WithTextExtensions reads the workspace's own plain-text extensions (core/kind) from text, asked at each read and write, so a change applies without a restart.
Source Files