editor

Documentation

Overview

Package editor provides a server that serves an HTTP editor API, and functions convenient client access to the server.

Index

• Constants
• Variables
• func Close(URL *url.URL) error
• func Reader(URL *url.URL, addr edit.Address) (io.ReadCloser, error)
• type Buffer
  • func BufferInfo(URL *url.URL) (Buffer, error)
  • func BufferList(URL *url.URL) ([]Buffer, error)
  • func NewBuffer(URL *url.URL) (Buffer, error)
• type Change
• type ChangeList
• type ChangeStream
  • func Changes(URL *url.URL) (*ChangeStream, error)
  • func (s *ChangeStream) Close() error
  • func (s *ChangeStream) Next() (ChangeList, error)
• type EditResult
  • func Do(URL *url.URL, edits ...edit.Edit) ([]EditResult, error)
• type Editor
  • func EditorInfo(URL *url.URL) (Editor, error)
  • func NewEditor(URL *url.URL) (Editor, error)
• type Server
  • func NewServer() *Server
  • func (s *Server) Close() error
  • func (s *Server) RegisterHandlers(r *mux.Router)

Constants

const MaxInline = 8

MaxInline is the maximum size, in bytes, for which Change.Text is set.

Variables

var (
	// ErrNotFound indicates that a resource is not found.
	ErrNotFound = errors.New("not found")

	// ErrRange indicates an out-of-range Address.
	ErrRange = errors.New("bad range")
)

Functions

func Close

func Close(URL *url.URL) error

Close does a DELETE. The URL is expected to point at either a buffer path or an editor path.

func Reader

func Reader(URL *url.URL, addr edit.Address) (io.ReadCloser, error)

Reader returns an io.ReadCloser that reads the text from a given Address. If non-nil, the returned io.ReadCloser must be closed by the caller. If the Address is non-nil, it is set as the value of the addr URL parameter. The URL is expected to point at an editor's text path.

Types

type Buffer

type Buffer struct {
	// ID is the ID of the buffer.
	ID string `json:"id"`

	// Path is the path to the buffer's resource.
	Path string `json:"path"`

	// Sequence is the sequence number of the last edit on the buffer.
	Sequence int `json:"sequence"`

	// Editors containts the buffer's editors.
	Editors []Editor `json:"editors"`
}

A Buffer describes a buffer.

func BufferInfo

func BufferInfo(URL *url.URL) (Buffer, error)

BufferInfo does a GET and returns a Buffer from the response body. The URL is expected to point at a buffer path.

func BufferList

func BufferList(URL *url.URL) ([]Buffer, error)

BufferList does a GET and returns a list of Buffers from the response body. The URL is expected to point at an editor server's buffers list.

func NewBuffer

func NewBuffer(URL *url.URL) (Buffer, error)

NewBuffer does a PUT and returns a Buffer from the response body. The URL is expected to point at an editor server's buffers list.

type Change

type Change struct {
	// Span identifies the string of the buffer that was changed.
	//
	// The units of the Span are runes;
	// the first is the inclusive starting rune index,
	// and the second is the exclusive ending rune index.
	//
	// NOTE: in the future, we plan to change Span to use byte indices.
	edit.Span `json:"span"`

	// NewSize is the size, in runes, to which the span changed.
	NewSize int64 `json:"newSize"`

	// Text is the text to which the span changed.
	// Text is not set if the either new text size is 0
	// or greater than MaxInline bytes.
	Text []byte `json:"text"`
}

A Change is a single change made to a string of a buffer.

type ChangeList

type ChangeList struct {
	// Sequence is the sequence number
	// unique to the edit that made the changes.
	Sequence int `json:"sequence"`

	// Changes contains the changes made by an edit.
	// The changes are in the sequence applied to the buffer.
	Changes []Change `json:"changes"`
}

A ChangeList is an atomic sequence of changes made by an edit to a buffer.

type ChangeStream

type ChangeStream struct {
	// contains filtered or unexported fields
}

A ChangeStream reads changes made to a buffer. Methods on ChangeStream are safe for use by concurrent go routines.

func Changes

func Changes(URL *url.URL) (*ChangeStream, error)

Changes returns a ChangeStream that reads changes made to a buffer. The URL is expected to point at the changes file of a buffer. Note that the changes file is a websocket, and must use a ws scheme:

ws://host:port/buffer/<ID>/changes

func (*ChangeStream) Close

func (s *ChangeStream) Close() error

Close unblocks any calls to Next and closes the stream.

func (*ChangeStream) Next

func (s *ChangeStream) Next() (ChangeList, error)

Next returns the next ChangeList from the stream. Calling Next on a closed ChangeStream returns io.EOF.

type EditResult

type EditResult struct {
	// Sequence is the sequence number unique to the edit.
	Sequence int `json:"sequence"`

	// Print is any data that the edit printed.
	Print string `json:"print,omitempty"`

	// Error is any error that occurred.
	Error string `json:"error,omitempty"`
}

An EditResult is result of performing an edito on a buffer.

func Do

func Do(URL *url.URL, edits ...edit.Edit) ([]EditResult, error)

Do POSTs a sequence of edits and returns a list of the EditResults from the response body. The URL is expected to point at an editor path.

type Editor

type Editor struct {
	// ID is the ID of the editor.
	ID string `json:"id"`

	// Path is the path to the editor's resource.
	Path string `json:"path"`

	// BufferPath is the path to the editor's buffer's resource.
	BufferPath string `json:"bufferPath"`
}

An Editor describes an editor.

func EditorInfo

func EditorInfo(URL *url.URL) (Editor, error)

EditorInfo does a GET and returns an Editor from the response body. The URL is expected to point at an editor path.

func NewEditor

func NewEditor(URL *url.URL) (Editor, error)

NewEditor does a PUT and returns an Editor from the response body. The URL is expected to point at a buffer path.

type Server

type Server struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Server implements http.Handler, serving an HTTP text editor. It provides an HTTP API for creating buffers of text and editors to read and modify those buffers.

Buffers and editors

A buffer is an un-bounded sequence of runes. Buffers can be viewed and modified using editors. A buffer can have multiple editors, but each editor edits only a single buffer.

An editor can view and modify a buffer using the T edit language documented here: https://godoc.org/github.com/eaburns/T/edit#Ed. While multiple editors can edit the same buffer concurrently, each editor maintains its own local state.

func NewServer

func NewServer() *Server

NewServer returns a new Server.

func (*Server) Close

func (s *Server) Close() error

Close closes the server and all of its buffers.

func (*Server) RegisterHandlers

func (s *Server) RegisterHandlers(r *mux.Router)

RegisterHandlers registers handlers for the following paths and methods:

 /buffers is the list of opened buffers.

	GET returns a Buffer list of the opened buffers.
	Returns:
	• OK on success.
	• Internal Server Error on internal error.

	PUT creates a new, empty buffer and returns its Buffer.
	Returns:
	• OK on success.
	• Internal Server Error on internal error.

 /buffer/<ID> is the buffer with the given ID.

	GET returns the buffer's Buffer
	Returns:
	• OK on success.
	• Internal Server Error on internal error.
	• Not Found if the buffer is not found.

	DELETE deletes the buffer and all of its editors.
	Returns:
	• OK on success.
	• Internal Server Error on internal error.
	• Not Found if the buffer is not found.

	PUT creates a new editor for the buffer and returns its Editor.
	Returns:
	• OK on success.
	• Internal Server Error on internal error.
	• Not Found if the buffer is not found.

 /buffer/<ID>/changes is the buffer's change stream.

	GET upgrades the connection to a websocket.
	A ChangeList is sent on the websocket
	for each edit made to the buffer.
	Returns:
	• Internal Server Error on internal error.
	• Not Found if the buffer is not found.

 /editor/<ID> is the editor with the given ID.

	GET returns the editor's Editor.
	Returns:
	• OK on success.
	• Internal Server Error on internal error.
	• Not Found if the editor is not found.

	DELETE deletes the editor.
	Returns:
	• OK on success.
	• Internal Server Error on internal error.
	• Not Found if the editor editor is not found.

 /editor/<ID>/text is the text that the editor edits.

	GET returns the text of the editor's buffer.
	Parameters:
	• addr can optionally be set to an address string.
	  It must not appear multiple times, there can only be one addr.
	  If it is set, only the text within the address is returned.
 	  Otherwise, all text is returned.
	Returns:
	• OK on success.
	• Internal Server Error on internal error.
	• Not Found if the editor is not found.
	• Bad Request if the URL parameters or addr value are malformed.
	• Range Not Satisfiable if there is an error evaluating the address.
	  The response body will contain an error message.

	POST performs an atomic sequence of edits on the buffer.
	The body must be an ordered list of Edits.
	The response is an ordered list of EditResult.
	Returns:
	• OK on success.
	• Internal Server Error on internal error.
	• Not Found if the editor is not found.
	• Bad Request if the Edit list is malformed.

Unless otherwise stated, the body of all error responses is the error message.