fs

Documentation

Overview

Package fs is a library which allows you to write well constructed Altid services

Overview

fs aims to present a way to write canonical services, which behave correctly in all instances. A service in Altid has the following structure on disk:

/
	ctl
	events
	errors
	buffer1/
	buffer2/
	[...]

All buffer management occurs through writes to the ctl file. To open a buffer, for example, you write

open mybuffer > /path/to/service/ctl

This in turn calls the Open function of a Handler, as described below.

Any errors encountered in the lifetime of a service will be logged to `errors`, and any events on any buffers will be logged to `events`

Index

• func UserConfDir() (string, error)
• func UserShareDir() (string, error)
• type ComGroup
• type Command
  • func FindCommands(b []byte) ([]*Command, error)
  • func FromString(cmd string) (*Command, error)
  • func (c *Command) Bytes() []byte
  • func (c *Command) String() string
• type Control
  • func Mock(ctl interface{}, reqs chan string, service string, debug bool) (*Control, error)
  • func New(ctl interface{}, logdir, mtpt, service, doctype string, debug bool) (*Control, error)
  • func (c *Control) Cleanup()
  • func (c *Control) Context() context.Context
  • func (c *Control) CreateBuffer(name, doctype string) error
  • func (c *Control) DeleteBuffer(name, doctype string) error
  • func (c *Control) ErrorWriter() (*writer.WriteCloser, error)
  • func (c *Control) Event(eventmsg string) error
  • func (c *Control) HasBuffer(name, doctype string) bool
  • func (c *Control) ImageWriter(buffer, resource string) (*writer.WriteCloser, error)
  • func (c *Control) Input(buffer string) error
  • func (c *Control) Listen() error
  • func (c *Control) MainWriter(buffer, doctype string) (*writer.WriteCloser, error)
  • func (c *Control) NavWriter(buffer string) (*writer.WriteCloser, error)
  • func (c *Control) Notification(buff, from, msg string) error
  • func (c *Control) Remove(buffer, filename string) error
  • func (c *Control) SetCommands(cmd ...*Command) error
  • func (c *Control) SideWriter(buffer string) (*writer.WriteCloser, error)
  • func (c *Control) StatusWriter(buffer string) (*writer.WriteCloser, error)
  • func (c *Control) TitleWriter(buffer string) (*writer.WriteCloser, error)
• type Controller
• type Manager

Functions

func UserConfDir

func UserConfDir() (string, error)

UserConfDir returns the default root directory to use for user-specific configuration data. Users should create their own application-specific subdirectory within this one and use that. On Unix systems, it returns $XDG_CONFIG_HOME as specified by https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html if non-empty, else $HOME/.config. On Darwin, it returns $HOME/Library/Preferences. On Windows, it returns %LocalAppData%. On Plan 9, it returns $home/lib.

func UserShareDir

func UserShareDir() (string, error)

UserShareDir returns the default root directory to use for user-specific application data. Users should create their own application-specific subdirectory within this one and use that. On Unix systems, it returns $XDG_DATA_HOME as specified by https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html if non-empty, else $HOME/.local/share. On Darwin, it returns $HOME/Library. On Windows, it returns %LocalAppData%. On Plan 9, it returns $home/lib.

Types

type ComGroup

type ComGroup int

ComGroup is a logical grouping of commands To add a ComGroup, please do so in a PR

const (
	DefaultGroup ComGroup = iota
	ActionGroup
	MediaGroup
	ServiceGroup
)

Currently supported ComGroups

type Command

type Command struct {
	Name        string
	Description string
	Heading     ComGroup
	Args        []string
	Alias       []string
	From        string
}

Command represents an available command to a service The From field should generally be populated, except in the case of a ServiceGroup command

func FindCommands

func FindCommands(b []byte) ([]*Command, error)

FindCommands within a byte array It returns an error if it encounters malformed input

func FromString

func FromString(cmd string) (*Command, error)

FromString returns a partially filled command It will have a Heading type of DefaultGroup

func (*Command) Bytes

func (c *Command) Bytes() []byte

Bytes - Return a byte representation of a command

func (*Command) String

func (c *Command) String() string

type Control

type Control struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Control type can be used to manage a running ctl file session

func Mock

func Mock(ctl interface{}, reqs chan string, service string, debug bool) (*Control, error)

Mock returns a type that can be used for testing services it will track in-memory and behave like a file-backed control It will wait for messages on reqs which act as ctl messages A special message of `input <from> <msg>` will be be sent as input By default it writes to Stdout + Stderr with each WriteCloser If debug is true, all logs will be written to stdout

func New

func New(ctl interface{}, logdir, mtpt, service, doctype string, debug bool) (*Control, error)

New sets up a ready-to-listen ctl file logdir is the directory to store copies of the contents of files created; specifically doctype. Logging any other type of data is left to implementation details, but is considered poor form for Altid's design. mtpt is the directory to create the file system in service is the subdirectory inside mtpt for the runtime fs This will return an error if a ctl file exists at the given directory, or if doctype is invalid.

func (*Control) Cleanup

func (c *Control) Cleanup()

Cleanup removes created symlinks and removes the main dir On plan9, it unbinds any file named "document" or "feed", prior to removing the directory itself.

func (*Control) Context

func (c *Control) Context() context.Context

Context returns the underlying context of the service This will be closed after Quit() is called

func (*Control) CreateBuffer

func (c *Control) CreateBuffer(name, doctype string) error

CreateBuffer creates a buffer of given name, as well as symlinking your file as follows: `os.Symlink(path.Join(logdir, name), path.Join(rundir, name, doctype))` This logged file will persist across reboots Calling CreateBuffer on a directory that already exists will return nil

func (*Control) DeleteBuffer

func (c *Control) DeleteBuffer(name, doctype string) error

DeleteBuffer unlinks a document/buffer, and cleanly removes the directory Will return an error if it's unable to unlink on plan9, or if the remove fails.

func (*Control) ErrorWriter

func (c *Control) ErrorWriter() (*writer.WriteCloser, error)

ErrorWriter returns a WriteCloser attached to a services' errors file

func (*Control) Event

func (c *Control) Event(eventmsg string) error

Event appends the given string to the events file of Control's working directory. Strings cannot contain newlines, tabs, spaces, or control characters. Returns "$service: invalid event $eventmsg" or nil.

func (*Control) HasBuffer

func (c *Control) HasBuffer(name, doctype string) bool

HasBuffer returns whether or not a buffer is present in the current control session

func (*Control) ImageWriter

func (c *Control) ImageWriter(buffer, resource string) (*writer.WriteCloser, error)

ImageWriter returns a WriteCloser attached to a named file in the buffers' image directory

func (*Control) Input

func (c *Control) Input(buffer string) error

Input starts an input file in the named buffer If Input is called before a buffer is created, an error will be returned If the Controller sent to Input does not implement a Handler this will panic

func (*Control) Listen

func (c *Control) Listen() error

Listen creates a file named "ctl" inside RunDirectory, after making sure the directory exists Any text written to the ctl file will be parsed, line by line. Messages handled internally are as follows: open (or join), close (or part), and quit, which causes Listen() to return. This will return an error if we're unable to create the ctlfile itself, and will log any error relating to control messages.

func (*Control) MainWriter

func (c *Control) MainWriter(buffer, doctype string) (*writer.WriteCloser, error)

MainWriter returns a WriteCloser attached to a buffers feed/document function to set the contents of a given buffers' document or feed file, which will as well send the correct event to the events file

func (*Control) NavWriter

func (c *Control) NavWriter(buffer string) (*writer.WriteCloser, error)

NavWriter returns a WriteCloser attached to a buffers nav file, which will as well send the correct event to the events file

func (*Control) Notification

func (c *Control) Notification(buff, from, msg string) error

Notification appends the content of msg to a buffers notification file Any errors encountered during file opening/creation will be returned The canonical form of notification can be found in the markup libs' Notification type, And the output of the Parse() method can be used directly here For example

ntfy, err := markup.NewNotifier(buff, from, msg)
if err != nil {
    log.Fatal(err)
}
fs.Notification(ntfy.Parse())

func (*Control) Remove

func (c *Control) Remove(buffer, filename string) error

Remove removes a buffer from the runtime dir. If the buffer doesn't exist, this is a no-op

func (*Control) SetCommands

func (c *Control) SetCommands(cmd ...*Command) error

SetCommands allows services to add additional commands Any client command encountered which matches will send The resulting command down to RunCommand Commands must include at least a name and a heading Running SetCommands after calling Start or Listen will have no effect

func (*Control) SideWriter

func (c *Control) SideWriter(buffer string) (*writer.WriteCloser, error)

SideWriter returns a WriteCloser attached to a buffers `aside` file, which will as well send the correct event to the events file

func (*Control) StatusWriter

func (c *Control) StatusWriter(buffer string) (*writer.WriteCloser, error)

StatusWriter returns a WriteCloser attached to a buffers status file, which will as well send the correct event to the events file

func (*Control) TitleWriter

func (c *Control) TitleWriter(buffer string) (*writer.WriteCloser, error)

TitleWriter returns a WriteCloser attached to a buffers title file, which will as well send the correct event to the events file

type Controller

type Controller interface {
	Manager
	input.Handler
}

Controller is our main type for controlling a session

type Manager

type Manager interface {
	Run(*Control, *Command) error
	Quit()
}

Manager wraps all interactions with the `ctl` file