cmd

package
Version: v0.0.0-...-b6ae310 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 4, 2015 License: GPL-3.0 Imports: 10 Imported by: 0

Documentation

Overview

Package cmd implements vim-like stateful operation.

Index

Constants

View Source
const (
	ShiftMask   = C.GDK_SHIFT_MASK
	LockMask    = C.GDK_LOCK_MASK
	ControlMask = C.GDK_CONTROL_MASK
	Mod1Mask    = C.GDK_MOD1_MASK
	Mod2Mask    = C.GDK_MOD2_MASK
	Mod3Mask    = C.GDK_MOD3_MASK
	Mod4Mask    = C.GDK_MOD4_MASK
	Mod5Mask    = C.GDK_MOD5_MASK
	Button1Mark = C.GDK_BUTTON1_MASK
	Button2Mark = C.GDK_BUTTON2_MASK
	Button3Mark = C.GDK_BUTTON3_MASK
	Button4Mark = C.GDK_BUTTON4_MASK
	Button5Mark = C.GDK_BUTTON5_MASK
	SuperMask   = C.GDK_SUPER_MASK
	HyperMask   = C.GDK_HYPER_MASK
	MetaMask    = C.GDK_META_MASK
	ReleaseMask = C.GDK_RELEASE_MASK
)

The constants in this block map directly to GDK modifier masks; each represents a modifier key or button, which may be pressed.

They may be logically ORed to combine them, and logically ANDed to check whether a given Key has these modifiers pressed.

View Source
const (
	KeyVoid      = C.GDK_KEY_VoidSymbol
	KeyEscape    = C.GDK_KEY_Escape
	KeyLeft      = C.GDK_KEY_Left
	KeyKPLeft    = C.GDK_KEY_KP_Left
	KeyRight     = C.GDK_KEY_Right
	KeyKPRight   = C.GDK_KEY_KP_Right
	KeyUp        = C.GDK_KEY_Up
	KeyKPUp      = C.GDK_KEY_KP_Up
	KeyDown      = C.GDK_KEY_Down
	KeyKPDown    = C.GDK_KEY_KP_Down
	KeyReturn    = C.GDK_KEY_Return
	KeyKPEnter   = C.GDK_KEY_KP_Enter
	KeyBackSpace = C.GDK_KEY_BackSpace
	KeyDelete    = C.GDK_KEY_Delete
	KeyKPDelete  = C.GDK_KEY_KP_Delete
	KeyHome      = C.GDK_KEY_Home
	KeyKPHome    = C.GDK_KEY_KP_Home
	KeyEnd       = C.GDK_KEY_End
	KeyKPEnd     = C.GDK_KEY_KP_End
	KeyTab       = C.GDK_KEY_Tab
	KeyLeftTab   = C.GDK_KEY_ISO_Left_Tab
)

The constants in this block map directly to GDK keyvals, and are used to compare with Key.Keyval to check which key was pressed.

Variables

View Source
var PrintBindings = false

PrintBindings specifies whether or not to print bindings as and when they run.

Functions

func KeysString

func KeysString(keys []Key) string

KeysString produces a string value associated with a slice of keys, forcing selected keys into their long form.

See KeysStringSelective

func KeysStringSelective

func KeysStringSelective(keys []Key, selective bool) string

KeysStringSelective produces a string representation of a slice of keys, selectively forcing some into their long form.

Each Key will be handled as in Key.StringSelective.

Keys producing a string value longer than one character will be placed in angled braces - e.g. <Escape> or <C-a>

func NewCompletion

func NewCompletion(s State)

NewCompletion schedules a completion to start once calculations have found at least one completion.

If no completions are found, nothing is done.

Types

type Binding

type Binding struct {
	From []Key
	To   func([]Key, *int, Substate)
	Name string
	Desc string
}

A Binding maps a sequence of keys to a function to be executed when they are pressed. The executer function will be passed the exact key sequence pressed, as well as a pointer to the (potentially) extracted <num> virtual key.

func ParseRawBindings

func ParseRawBindings(
	bindings []RawBinding,
	builtins Builtins,
	runCmd func(string)) ([]*Binding, []error)

ParseRawBindings applies RawBinding.ParseBinding to a slice of raw bindings.

Parse errors are not ignored, but parsing will continue regardless. All parse errors are returned, along with all bindings which did not fail to parse.

type BindingTree

type BindingTree struct {
	Binding  *Binding
	Subtrees map[Key]*BindingTree
}

A BindingTree is a tree structure for a set of bindings. Each key sequence corresponds to a node in the tree, (the empty sequence being the root), with a binding function optionally attached to any node.

func NewBindingTree

func NewBindingTree(bindings []*Binding) (*BindingTree, []error)

NewBindingTree converts a slice of Bindings into a tree format. Errors occur only if bindings conflict.

Building the binding tree continues if errors occur; only those elements which cause the conflict (i.e. the latter conflicting ones) will be ignored.

func (*BindingTree) Append

func (t *BindingTree) Append(binding *Binding) error

Append adds a new binding to a BindingTree.

Fails if the binding conflicts with an existing one.

func (*BindingTree) IterLeaves

func (t *BindingTree) IterLeaves() <-chan *Binding

IterLeaves iterates recursively over the leaves of the tree.

Not terribly efficient due to each recursion step creating a new goroutine, but hey.

type Builtin

type Builtin struct {
	Func func(*int)
	Name string
	Desc string
}

A Builtin is a builtin function.

type Builtins

type Builtins map[string]*Builtin

Builtins are a collection of functions, which are accessible by their name.

type CommandLineMode

type CommandLineMode struct {
	*StateIndependant
	Substate
	CurrentKeys []Key
	CursorPos   int
	CursorHome  int
	CursorEnd   int
	Finalizer   func(string)
}

CommandLineMode a mode which allows the user to enter a single line of text.

The invoker of CommandLineMode supplies a Finalizer function, which is used to act on the text after the user presses enter.

func NewCommandLineMode

func NewCommandLineMode(
	s State,
	st Substate,
	f func(string)) *CommandLineMode

NewCommandLineMode initializes a command line mode, starting from some state s and a finalizer function.

The finalizer function is run if a command line entry is accepted, with the command line entry as an argument.

func NewPartialCommandLineMode

func NewPartialCommandLineMode(
	s State,
	st Substate,
	beforeCursor,
	afterCursor string,
	f func(string)) *CommandLineMode

NewPartialCommandLineMode acts like NewCommandLineMode, except that it defaults to a provided string as the command line instead of an empty one.

Note that the strings are parsed into their Key components.

func (*CommandLineMode) GetStateIndependant

func (s *CommandLineMode) GetStateIndependant() *StateIndependant

GetStateIndependant gets the state independant associated with this state.

func (*CommandLineMode) GetSubstate

func (s *CommandLineMode) GetSubstate() Substate

GetSubstate gets the substate associated with this state.

func (*CommandLineMode) Paste

func (s *CommandLineMode) Paste(str string) State

Paste pastes a string into the command line.

func (*CommandLineMode) ProcessKeyPress

func (s *CommandLineMode) ProcessKeyPress(key RealKey) (State, bool)

ProcessKeyPress processes the press of a single Key in CommandLineMode.

Typically the Key is added to the current command line, with a few exceptions.

BackSpace deletes the last read key, or if none are left, returns to NormalMode.

Enter accepts the CommandLine and runs the finalizer, returning to NormalMode afterwards.

Escape returns to NormalMode.

type CompleterFunction

type CompleterFunction func(s State, firstFunc func(ok bool), states *[]State) (cancel func())

A CompletionFunction is a function called to complete a state.

It takes the state to complete, a function to be called when the first completion is found (with true, or false if none is found), and a pointer to the slice of completed states which will be generated concurrently.

It returns a function which can be called to cancel completion. Completion should always be cancelled eventually.

type CompletionMode

type CompletionMode struct {
	State
	Substate
	CompletionStates  *[]State
	CurrentCompletion int
	CancelFunc        func()
}

CompletionMode is a mode in which some other state is being completed.

func (*CompletionMode) ChildState

func (s *CompletionMode) ChildState() State

ChildState gets the original state being completed.

func (*CompletionMode) GetSubstate

func (s *CompletionMode) GetSubstate() Substate

GetSubstate gets the substate of the current state.

func (*CompletionMode) ProcessKeyPress

func (s *CompletionMode) ProcessKeyPress(key RealKey) (State, bool)

ProcessKeyPress processes a single key press in completion mode.

Tab or down chooses the next completion, Shift-Tab (ISO Left Tab) or up the previous one, escape cancels it and any other key is passed to the completion state (effectively accepting it)

func (*CompletionMode) SwapChildState

func (s *CompletionMode) SwapChildState(newState State) ContainerState

SwapChildState swaps out the child state, returning the resulting container.

type ConfirmMode

type ConfirmMode struct {
	State
	Substate
	Prompt      string
	ConfirmKeys []Key
	CancelKeys  []Key
	Default     *bool
	Callback    func(bool)
}

ConfirmMode tries to confirm an action with the user.

If a key in ConfirmKeys is pressed, the action is confirmed (callback called w/ true) If a key in CancelKeys is pressed, the action is cancelled (callback called w/ false) If Escape is pressed, the callback is not called at all. If Enter is pressed, and Default is not nil, the default is taken.

func NewYesNoConfirmMode

func NewYesNoConfirmMode(
	s State,
	st Substate,
	prompt string,
	def *bool,
	callback func(bool)) *ConfirmMode

NewYesNoConfirmMode creates a new ConfirmMode for a yes/no confirmation.

func (*ConfirmMode) ChildState

func (s *ConfirmMode) ChildState() State

ChildState returns the contained state of the confirm mode.

func (*ConfirmMode) GetSubstate

func (s *ConfirmMode) GetSubstate() Substate

GetSubstate gets the substate of the current state.

func (*ConfirmMode) ProcessKeyPress

func (s *ConfirmMode) ProcessKeyPress(k RealKey) (State, bool)

ProcessKeyPress processes a key, and check if the confirmation was handled.

func (*ConfirmMode) SwapChildState

func (s *ConfirmMode) SwapChildState(newState State) ContainerState

SwapChildState swaps out the child state, returning the resulting container.

type ContainerState

type ContainerState interface {
	State
	ChildState() State
	SwapChildState(newState State) ContainerState
}

A ContainerState is a state which contains another state.

type InsertMode

type InsertMode struct {
	*StateIndependant
	Substate
}

InsertMode is a mode which ignores any keypresses, with the exception of the escape key,

func NewInsertMode

func NewInsertMode(s State, st Substate) *InsertMode

NewInsertMode basically just copies over the StateIndependant and returns a new InsertMode.

func (*InsertMode) GetStateIndependant

func (s *InsertMode) GetStateIndependant() *StateIndependant

GetStateIndependant gets the state independant associated with this state.

func (*InsertMode) GetSubstate

func (s *InsertMode) GetSubstate() Substate

GetSubstate gets the substate associated with this state.

func (*InsertMode) ProcessKeyPress

func (s *InsertMode) ProcessKeyPress(key RealKey) (State, bool)

ProcessKeyPress passes through any keys except escape, which it immediately swallows and switches to normal mode.

type Key

type Key interface {
	KeyType() KeyType
	Equals(Key, Modifiers) bool
	String() string
	StringSelective(bool) string
}

A Key is the representation of a single key, real or virtual.

func ImmutableAppend

func ImmutableAppend(keys []Key, app ...Key) []Key

ImmutableAppend functions like append for a slice of keys, except it is guaranteed to return a freshly allocated slice every time.

func NewKeyFromRune

func NewKeyFromRune(r rune) Key

NewKeyFromRune creates a new key object from a rune.

func NewKeyFromString

func NewKeyFromString(strOrig string) Key

NewKeyFromString creates a new key object from a string.

Note that Key objects created for modifier keys will be incorrectly flagged as not being modifiers. This functionality is at the time of writing not required.

If the string Starts with C-, A-, C-A- or A-C-, it will be interpreted as the modifiers control, alt, both or both being pressed respectively.

Beyond such a prefix, a key is either parsed as whichever key is associated with the single unicode rune remaining, (e.g. a or ! or £), or whichever key has the name of the string remaining (e.g. Escape, Enter, space)

Note the importance of capitalization.

If a real key cannot be derived in this way, a virtual one is used instead.

func ParseKeys

func ParseKeys(str string) []Key

ParseKeys parses a string into the slice of Keys it represents. Each individual key is parsed as in NewKeyFromString.

Each individual key is either in angled braces (e.g. <Escape>), or a single unicode rune (e.g. a, $, £). To avoid ambiguity, a left angle brace '<' is only parsed as a single key if no right angle braces follow it. If it is necessary to used it in such a situation, write out <left> instead.

type KeyType

type KeyType uint

A KeyType is the type of a specific key.

const (
	// KeyTypeNormal is a normal, physical key.
	KeyTypeNormal KeyType = iota
	// KeyTypeModifier is a modifier key.
	KeyTypeModifier
	// KeyTypeVirtual is a non-existant, virtual key.
	KeyTypeVirtual
)

type Modifiers

type Modifiers uint

A Modifiers is a mask of GDK modifier keys.

They are represented as a standard bitmask.

type NormalMode

type NormalMode struct {
	*StateIndependant
	Substate
	CurrentKeys []Key
	CurrentTree *BindingTree
	// contains filtered or unexported fields
}

NormalMode is a mode which mostly deals with key sequence bindings.

These sequences are user-defined and mapped to specific actions, which get executed if the key sequence is used.

func NewNormalMode

func NewNormalMode(s State) *NormalMode

NewNormalMode creates a baseline NormalMode state from a base state.

func NewNormalModeWithSubstate

func NewNormalModeWithSubstate(s State, st Substate) *NormalMode

NewNormalModeWithSubstate creates a new NormalMode with the specified substate.

func (*NormalMode) GetStateIndependant

func (s *NormalMode) GetStateIndependant() *StateIndependant

GetStateIndependant gets the state independant associated with this state.

func (*NormalMode) GetSubstate

func (s *NormalMode) GetSubstate() Substate

GetSubstate gets the substate associated with this state.

func (*NormalMode) PredictState

func (s *NormalMode) PredictState(keys []Key) *NormalMode

PredictState predicts the state if "fast forwarded" a slice of keys.

A few peculiarities are of note:

- No bindings are executed, under any circumstances.
- The virtual <num> key is not handled.

This method is primarily meant for creating states predicted through completion.

func (*NormalMode) ProcessKeyPress

func (s *NormalMode) ProcessKeyPress(key RealKey) (State, bool)

ProcessKeyPress processes exactly one key press in normal mode.

It returns the new state, and whether the key press was swallowed or not.

type RawBinding

type RawBinding struct {
	From string
	To   string
}

A RawBinding map one string (representing the keysequence to be pressed) to another (representing what the binding should do).

func (RawBinding) ParseBinding

func (b RawBinding) ParseBinding(
	builtins Builtins, runCmd func(string)) (*Binding, error)

ParseBinding parses a single binding string, as given to the bind command.

e.g. fg<Enter> builtin:foobar

The To part of the binding can be interpreted in several ways:

If it starts with 'builtin:' or 'b:' it maps directly to a builtin function.

If it starts with 'command:', 'cmd:' or 'c:' it maps to executing the following command. (This is implemented by running the builtin command 'runCmd' with the command as the single string argument)

No other prefixes are currently supported.

type RealKey

type RealKey struct {
	Keyval     uint
	Modifiers  Modifiers
	IsModifier bool
}

A RealKey is a keyval combined with the pressed modifiers.

It can be derived from a key event, or simply be an abstract representation or a key.

func NewKeyFromEventKey

func NewKeyFromEventKey(ek gdk.EventKey) RealKey

NewKeyFromEventKey converts a gdk key event into a Key.

func (RealKey) Equals

func (k RealKey) Equals(k2 Key, mods Modifiers) bool

Equals compares to another key for equality, respecting a particular modifier mask. (i.e. only these modifiers will be compared)

func (RealKey) IsNum

func (k RealKey) IsNum() bool

IsNum checks if a real key is a number key.

func (RealKey) KeyType

func (k RealKey) KeyType() KeyType

KeyType gets the type of the key.

func (RealKey) Normalize

func (k RealKey) Normalize() RealKey

Normalize keeps only Control and Alt modfiers of the key.

func (RealKey) NumVal

func (k RealKey) NumVal() (int, error)

NumVal retrieves the numeric value of a single key.

func (RealKey) String

func (k RealKey) String() string

String produces a string value associated with a key, forcing selected keys into their long form.

See Key.StringSelective

func (RealKey) StringSelective

func (k RealKey) StringSelective(selective bool) string

StringSelective produces a string value associated with a key, optionally forcing selected Keys into their long form.

In particular, if selective is true, '<' is written as <less> and ' ' is written as <space>

Keys can be in a short form ('a', '!', '/') or long form ('Escape', 'Tab', 'Enter').

The short form will be used for most Keys with an associated character, with the exception of whitespace (except the literal space, which depends on the selective parameter), and (again with the selective parameter) a '<'.

The long form will be used in all other cases.

If a Key has the control modifier pressed, 'C-' is prepended. Likewise, if alt is pressed, 'A-' is prepended. 'C-A-' is prepended if both are pressed.

type State

type State interface {
	// Processes a key.
	// Returns the new state and whether the key was swallowed or not.
	ProcessKeyPress(key RealKey) (State, bool)
	// Gets the StateIndependant.
	GetStateIndependant() *StateIndependant
	// Gets the code of the current substate.
	GetSubstate() Substate
}

The State of some window/program is... well, it's state (in regards to keypresses)

func NewState

func NewState(
	bindings map[Substate]*BindingTree,
	setState func(State),
	getState func() State,
	completer CompleterFunction) State

NewState creates a new state, in its original setting.

type StateIndependant

type StateIndependant struct {
	Bindings  map[Substate]*BindingTree
	SetState  func(s State)
	GetState  func() State
	Completer CompleterFunction
}

A StateIndependant encompasses all data indepentant of the state, avoiding copying it around every time the state is changed.

type StatusMode

type StatusMode struct {
	State
	Substate
	Status string
}

StatusMode is a mode which displays a single status line.

It keeps the previous state as a part of it, and does nothing itself. All methods called are directed to the previous that; most notably: any key press will revert out of StatusMode, and the old state will handle the key press as normal.

func NewStatusMode

func NewStatusMode(s State, st Substate, status string) *StatusMode

NewStatusMode creates a new StatusMode with a given state and status string.

func (*StatusMode) ChildState

func (s *StatusMode) ChildState() State

ChildState retrieves the status modes contained state.

func (*StatusMode) GetSubstate

func (s *StatusMode) GetSubstate() Substate

GetSubstate gets the substate associated with this state.

func (*StatusMode) SwapChildState

func (s *StatusMode) SwapChildState(newState State) ContainerState

SwapChildState swaps out the child state, returning the resulting container.

type Substate

type Substate uint

A Substate allows using the same state for several different purposes.

Substates are not defined in this module, with the exception of the SubstateDefault, and left for the main program to define.

const SubstateDefault Substate = 0

SubstateDefault is a substate marking that the "default" substate is being used. It is not defined more specifically (that is up to the application to decide), except that NormalMode's SubstateDefault should be the single state which the application has as its default "resting" state.

type VirtualKey

type VirtualKey string

A VirtualKey is the abstract notion of a named key.

func (VirtualKey) Equals

func (k VirtualKey) Equals(k2 Key, mods Modifiers) bool

Equals compares this virtual key with another.

func (VirtualKey) KeyType

func (k VirtualKey) KeyType() KeyType

KeyType retrieves the type of this key.

Will always return KeyTypeVirtual.

func (VirtualKey) String

func (k VirtualKey) String() string

String retrieves the string value of this key.

func (VirtualKey) StringSelective

func (k VirtualKey) StringSelective(selective bool) string

StringSelective retrieves the string value of this key, selectively printing certain keys in their long form.

Equivalent to String for VirtualKeys.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL