README
¶
bookmark
Persistent access to user-selected files and folders across launches, cgo-free.
// After the user picks a folder (e.g. filedialog.PickDirectory):
token, err := bookmark.Create(dir)
// store token wherever the app keeps per-machine state
// On the next launch, before touching the folder:
path, release, err := bookmark.Resolve(token)
defer release()
Under the macOS App Sandbox, access granted through an open panel (the powerbox) dies with the process; the token captures it as a security-scoped bookmark so the next launch can restore it. On Windows and Linux, and on macOS outside the sandbox, filesystem access already persists, so the token simply records the path. Callers store the opaque token and never branch by platform.
Details of the contract:
Createrequires the item to exist (macOS cannot bookmark a missing path; the other platforms match, so there is one behavior).Resolvestarts the access grant and returns a release function, safe to call more than once. A sandboxed process holds a limited number of concurrent grants: release when done.- The resolved path can differ from the created one when the user moved the item - macOS resolves the bookmark, not the path.
- A bookmark can go stale after the item moves; recreate the token
after a successful
Resolvewhen convenient. - A security-scoped token resolved on another platform reports
ErrUnsupported(tokens can travel in synced app state).
No main-thread requirement: unlike the panels in filedialog, the
bookmark calls have no UI.
Documentation
¶
Overview ¶
Package bookmark persists access to user-selected files and folders across application launches, cgo-free.
Under the macOS App Store sandbox, access granted through an open panel (the powerbox) dies with the process; a security-scoped bookmark is the supported way to carry that grant to the next launch. On Windows and Linux, and on macOS outside the sandbox, filesystem access already persists, so the token simply records the path. The API is uniform: callers store the opaque token and never branch by platform.
The usual flow: after the user picks a file or folder, Create a token and store it; on the next launch, Resolve the token before touching the item, and call the returned release function when done with it (a sandboxed process holds a limited number of concurrent grants). A resolved bookmark can go stale when the item moves; recreate the token after a successful Resolve when convenient.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrUnsupported = errors.New("bookmark: token not resolvable on this platform")
ErrUnsupported reports a token that cannot be resolved on this platform (a macOS security-scoped token on Windows or Linux).
Functions ¶
func Create ¶
Create returns an opaque token that later restores access to path. The item must exist: macOS cannot bookmark a missing path, and the other platforms match that behavior so callers see one contract.
func Resolve ¶
Resolve turns a token back into a usable path and starts the access grant. The returned release function ends the grant and is safe to call more than once. The path may differ from the one given to Create if the user moved the item (macOS resolves the bookmark, not the path). Resolve does not check that the item still exists.
Types ¶
This section is empty.
Source Files