itermctl

package
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: Aug 30, 2020 License: MIT Imports: 21 Imported by: 0

Documentation

Index

Examples

Constants

View Source 
const (
	AllSessions = "all"
)
View Source 
const DefaultProfileName = "Default"

Variables

View Source 
var (
	Socket                           = "~/Library/Application Support/iTerm2/private/socket"
	Subprotocol                      = "api.iterm2.com"
	AppName                          = "itermctl"
	LibraryVersion                   = "itermctl 0.0.3"
	Origin                           = "ws://localhost/"
	Url                              = url.URL{Scheme: "ws", Host: "localhost:1912"}
	ErrNoKnobs                       = fmt.Errorf("no argument named 'knobs'")
	ErrClosed                        = fmt.Errorf("connection is closed")
	ErrSessionNotFound               = fmt.Errorf("NotificationResponse_SESSION_NOT_FOUND")
	ErrRequestMalformed              = fmt.Errorf("NotificationResponse_REQUEST_MALFORMED")
	ErrNotSubscribed                 = fmt.Errorf("NotificationResponse_NOT_SUBSCRIBED")
	ErrAlreadySubscribed             = fmt.Errorf("NotificationResponse_ALREADY_SUBSCRIBED")
	ErrDuplicatedServerOriginatedRpc = fmt.Errorf("NotificationResponse_DUPLICATE_SERVER_ORIGINATED_RPC")
	ErrInvalidIdentifier             = fmt.Errorf("NotificationResponse_INVALID_IDENTIFIER")
	WaitResponseTimeout              = 5 * time.Second
)

Functions

func NewNotificationRequest 

func NewNotificationRequest(subscribe bool, nt iterm2.NotificationType, sessionId string) *iterm2.NotificationRequest

NewNotificationRequest creates a notification request to subscribe or unsubscribe for the given notification type. If an empty sessionId is given, the subscription is created for all sessions.

Types

type AcceptFunc 

type AcceptFunc func(msg *iterm2.ServerOriginatedMessage) bool

AcceptFunc is the function given to Connection.NewReceiver() to filter out uninteresting ServerOriginatedMessages.

func AcceptNotificationType 

func AcceptNotificationType(t iterm2.NotificationType) AcceptFunc

AcceptNotificationType filters ServerOriginatedMessages whose submessage is a Notification of the given type.

type Alert 

type Alert struct {
	// Title is the window's title.
	Title string
	// Subtitle is an informative text that can span multiple lines.
	Subtitle string
	// Buttons optionally specifies a list of button labels; if no button is given, the alert will show a default "OK"
	// button.
	Buttons []string
}

Alert is an app-modal or window-modal alert window. Use it with App.ShowAlert. See https://www.iterm2.com/python-api/alert.html#iterm2.Alert.

type App 

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

App provides methods to interact with the running iTerm2 Application.

func NewApp 

func NewApp(conn *Connection) (*App, error)

NewApp creates a new App bound to the given Connection.

func (*App) Activate 

func (a *App) Activate(raiseAllWindow bool, ignoringOtherApps bool) error

Activate iTerm2 (eg. gives it focus).

func (*App) ActivateTab 

func (a *App) ActivateTab(id string) error

ActivateTab brings a tab to the front.

func (*App) ActivateWindow 

func (a *App) ActivateWindow(id string) error

ActivateWindow brings a window to the front.

func (*App) Active 

func (a *App) Active() (bool, error)

Active tells if iTerm2 is currently active.

func (*App) ActiveSession added in v0.0.2 

func (a *App) ActiveSession() (*Session, error)

func (*App) ActiveSessionId 

func (a *App) ActiveSessionId() (string, error)

ActiveSessionId returns the ID of the currently active session through a getFocus call.

func (*App) ActiveTabId 

func (a *App) ActiveTabId() (string, error)

ActiveTabId returns the ID of the currently active window.

func (*App) ActiveWindowId 

func (a *App) ActiveWindowId() (string, error)

ActiveWindowId returns the ID of the currently active window.

func (*App) BeginTransaction added in v0.0.2 

func (a *App) BeginTransaction(ctx context.Context) error

func (*App) CloseTab 

func (a *App) CloseTab(force bool, tabIds ...string) error

CloseTab closes the tabs specified by the given IDs. An error is returned when iTerm2 reports an error closing at least one tab.

func (*App) CloseWindow 

func (a *App) CloseWindow(force bool, windowIds ...string) error

CloseWindow closes the windows specified by the given IDs. An error is returned when iTerm2 reports an error closing at least one window.

func (*App) CreateTab 

func (a *App) CreateTab(windowId string, tabIndex uint32, profileName string) (*iterm2.CreateTabResponse, error)

CreateTab creates a new tab in the targeted window, at the specified index, with the Default or named profile.

func (*App) GetText 

func (a *App) GetText(alert TextInputAlert, windowId string) (string, error)

GetText shows the TextInputAlert and blocks until the user types some text and hits OK. The TextInputAlert is application-modal unless a windowId is given. Returns the user's input text.

func (*App) ListSessions 

func (a *App) ListSessions() (*iterm2.ListSessionsResponse, error)

ListSessions gets current sessions information.

func (*App) Session added in v0.0.2 

func (a *App) Session(id string) (*Session, error)

func (*App) ShowAlert 

func (a *App) ShowAlert(alert Alert, windowId string) (string, error)

ShowAlert shows the Alert and blocks until the user clicks one of the Alert's button. The Alert is application-modal unless a windowId is given. Returns the clicked button's text, or "OK" if the Alert has no custom button.

type ClickArgs added in v0.0.2 

type ClickArgs struct {
	SessionId string `arg.name:"session_id"`
}

type Connection 

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

Connection represents a connection to iTerm2, providing basic methods to send and read messages.

func Connect 

func Connect(appName, cookie, key string) (*Connection, error)

Connect connects to iTerm2's websocket using the optional credentials. AppName is used as a default app name if none is given.

func GetCredentialsAndConnect 

func GetCredentialsAndConnect(appName string, active bool) (*Connection, error)

GetCredentialsAndConnect checks if iTerm2 is configured to require authentication, retrieves the cookie and key if necessary, and then establishes the connection to iTerm2's websocket.

func NewConnection added in v0.0.2 

func NewConnection(ws *websocket.Conn) *Connection

NewConnection creates a new Connection wrapping around a *websocket.Conn.

func (*Connection) Close 

func (conn *Connection) Close()

Close initiates the connection's shutdown, causing all the receivers channels to be closed. It will also close the underlying websocket.

func (*Connection) GetResponse added in v0.0.2 

func (conn *Connection) GetResponse(ctx context.Context, req *iterm2.ClientOriginatedMessage) (*iterm2.ServerOriginatedMessage, error)

GetResponse sends a message to iTerm2, and waits up to WaitResponseTimeout for a message to be read from src and returns it. If the message is an error from iTerm2, a nil message and an error are returned. A nil message with an error will also be returned if WaitResponseTimeout expires before a message is received.

func (*Connection) InvokeFunction added in v0.0.2 

func (conn *Connection) InvokeFunction(invocation string, target interface{}) error

InvokeFunction invokes an RPC function and unmarshalls the result into target. If iTerm2's response to the invocation is an error, target is left untouched and an error is returned.

func (*Connection) MonitorCustomControlSequences added in v0.0.2 

func (conn *Connection) MonitorCustomControlSequences(ctx context.Context, identity string, re *regexp.Regexp, sessionId string) (<-chan CustomControlSequenceNotification, error)

MonitorCustomControlSequences subscribes to CustomControlSequenceNotification and writes each one that matches any of the given sessionId, identities and regex to the returned channel, until the context is done or the Connection is closed. An identity is a secret shared between the conn and iTerm2 and is required as a security mechanism. Note that filtering against unknown identities is done here on the client side. See https://www.iterm2.com/python-api/customcontrol.html.

func (*Connection) MonitorKeystrokes added in v0.0.2 

func (conn *Connection) MonitorKeystrokes(ctx context.Context, sessionId string) (<-chan *iterm2.KeystrokeNotification, error)

MonitorKeystrokes subscribes to KeystrokeNotification and writes each one to the returned channel, until the context is canceled or the Connection is closed.

func (*Connection) MonitorNewSessions added in v0.0.2 

func (conn *Connection) MonitorNewSessions(ctx context.Context) (<-chan *iterm2.NewSessionNotification, error)

MonitorNewSessions subscribes to NewSessionNotifications and forwards each one to the returned channel, until the given context is done or the Connection is shutdown.

func (*Connection) MonitorPrompts added in v0.0.2 

func (conn *Connection) MonitorPrompts(ctx context.Context, modes ...iterm2.PromptMonitorMode) (<-chan *iterm2.PromptNotification, error)

MonitorPrompts subscribe to PromptNotification for the given modes, and writes them to the returned channel, until the given context is done or the Connection is shutdown. Note that iTerm2 can only detect prompts when shell integration is installed. See https://iterm2.com/python-api/prompt.html#iterm2.PromptMonitor.

func (*Connection) MonitorScreenUpdates added in v0.0.2 

func (conn *Connection) MonitorScreenUpdates(ctx context.Context, sessionId string) (<-chan *iterm2.ScreenUpdateNotification, error)

MonitorScreenUpdates subscribes to ScreenUpdateNotification and forwards each one to the returned channel. Subscription lasts until the given context is canceled or the conn's connection is closed. Use methods such as App.ScreenContents to retrieve the screen's contents.

func (*Connection) MonitorSessionsTermination added in v0.0.2 

func (conn *Connection) MonitorSessionsTermination(ctx context.Context) (<-chan *iterm2.TerminateSessionNotification, error)

MonitorSessionsTermination subscribes to TerminateSessionNotification and writes each one to the returned channel, until the given context is done or the Connection is shutdown.

func (*Connection) NewReceiver added in v0.0.2 

func (conn *Connection) NewReceiver(ctx context.Context, name string, f AcceptFunc) (*receiver, error)

NewReceiver returns a receiver for ServerOriginatedMessages. Messages can be read from the receiver's Ch() until the Connection is closed or the context is canceled. A context should be given only to interrupt receiving before the Connection is closed, and should not be the same as the one used to cancel the Connection. The receiver will receive a copy of any ServerOriginatedMessage being shipped on the Connection, but an AcceptFunc can be given to exclude uninteresting messages.

func (*Connection) RegisterRpc added in v0.0.2 

func (conn *Connection) RegisterRpc(ctx context.Context, rpc Rpc) error

RegisterRpc registers the Rpc, invokes its callback when requested by iTerm2 and writes back to iTerm2 the callback's return value or return error. Registration lasts until the context is canceled, or the underlying connection is closed. See https://www.iterm2.com/python-api/registration.html.

Example 
conn, err := GetCredentialsAndConnect("itermctl_docs_RegisterRpc_example", true)
if err != nil {
	panic(err)
}

type Args struct {
	BoolArg   bool    `arg.name:"bool_arg"`
	NumberArg float64 `arg.name:"number_arg"`
	// this will be injected with the value of the current session ID when invoked by iTerm2
	StringArg string `arg.name:"string_arg" arg.ref:"id"`
}

rpc := Rpc{
	Name: "itermctl_rpc_example",
	Args: Args{
		BoolArg:   true,
		StringArg: "some string",
		NumberArg: 42.0,
	},
	F: func(invocation *RpcInvocation) (interface{}, error) {
		args := Args{}
		if err := invocation.Args(args); err != nil {
			return nil, err
		}

		// do stuff with args.StringArg, etc. and maybe return something
		return nil, nil
	},
}

if err := conn.RegisterRpc(context.Background(), rpc); err != nil {
	panic(err)
}

Output:

func (*Connection) RegisterSessionTitleProvider added in v0.0.2 

func (conn *Connection) RegisterSessionTitleProvider(ctx context.Context, tp TitleProvider) error

RegisterSessionTitleProvider registers a Session Title Provider. Registration lasts until the context is canceled or the conn's connection shuts down. See https://www.iterm2.com/python-api/registration.html#iterm2.registration.TitleProviderRPC.

Example 
conn, err := GetCredentialsAndConnect("itermctl_docs_RegisterSessionTitleProvider_example", true)
if err != nil {
	panic(err)
}

var args struct {
	SessionId string `arg.name:"session_id" arg.ref:"id"`
}

tp := TitleProvider{
	DisplayName: "Title Provider",
	Identifier:  "io.mrz.itermctl.example.titleprovider",
	Rpc: Rpc{
		Name: "itermctl_title_provider_example",
		Args: args,
		F: func(invocation *RpcInvocation) (interface{}, error) {
			err := invocation.Args(&args)
			if err != nil {
				return nil, err
			}

			return fmt.Sprintf("Title for session %q", args.SessionId), nil
		},
	},
}

if err := conn.RegisterSessionTitleProvider(context.Background(), tp); err != nil {
	panic(err)
}

Output:

func (*Connection) RegisterStatusBarComponent added in v0.0.2 

func (conn *Connection) RegisterStatusBarComponent(ctx context.Context, cmp StatusBarComponent) error

RegisterStatusBarComponent registers a Status Bar Component. Registration lasts until the context is canceled or the connection is closed. See https://www.iterm2.com/python-api/registration.html#iterm2.registration.StatusBarRPC.

Example 
conn, err := GetCredentialsAndConnect("itermctl_docs_RegisterStatusBarComponent_example", true)
if err != nil {
	panic(err)
}

type Knobs struct {
	Checkbox bool    `knob.name:"Checkbox knob" json:"checkbox"`
	Text     string  `knob.name:"Text knob" knob.placeholder:"Enter some text" json:"text"`
	Number   float64 `knob.name:"Number knob" json:"number"`
}

cmp := StatusBarComponent{
	ShortDescription: "Component example",
	Description:      "Component example",
	Exemplar:         "[component]",
	UpdateCadence:    0,
	Identifier:       "io.mrz.itermctl.example.component",
	Rpc: Rpc{
		Name: "itermctl_component_example",
		F: func(invocation *RpcInvocation) (interface{}, error) {
			knobs := Knobs{}

			if err := invocation.Knobs(&knobs); err != nil {
				return nil, err
			}

			return fmt.Sprintf("checkbox: %t, number: %f, text:%s", knobs.Checkbox, knobs.Number, knobs.Text), nil
		},
	},
	Knobs: Knobs{
		// Values given here are used as default values in the configuration panel
		Checkbox: true,
		Text:     "some text",
		Number:   42.0,
	},
}

if err := conn.RegisterStatusBarComponent(context.Background(), cmp); err != nil {
	panic(err)
}

Output:

func (*Connection) Send added in v0.0.2 

func (conn *Connection) Send(msg *iterm2.ClientOriginatedMessage) error

Send sends a message to iTerm2, without waiting for a response. ErrClosed is returned when Send is called after the connection was closed.

func (*Connection) Subscribe added in v0.0.2 

func (conn *Connection) Subscribe(ctx context.Context, req *iterm2.NotificationRequest) (*receiver, error)

Subscribe uses the given NotificationRequest to subscribe with iTerm2, and returns a channel from which notifications of requested type can be read. The NotificationRequest will be modified to ensure the Subscribe field is set to true. The subscription will be canceled automatically as soon as the context is canceled. The subscription lasts until the give context is canceled or the conn connection is closed.

func (*Connection) Wait added in v0.0.2 

func (conn *Connection) Wait()

Wait blocks until the conn's shuts down.

type CustomControlSequenceEscaper added in v0.0.3 

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

func NewCustomControlSequenceEscaper added in v0.0.3 

func NewCustomControlSequenceEscaper(identity string) *CustomControlSequenceEscaper

NewCustomControlSequenceEscaper creates an CustomControlSequenceEscaper bound to the given identity.

func (*CustomControlSequenceEscaper) Escape added in v0.0.3 

func (e *CustomControlSequenceEscaper) Escape(format string, a ...interface{}) string

Escape wraps a formatted string in a Custom Control Sequence

type CustomControlSequenceNotification 

type CustomControlSequenceNotification struct {
	Matches      []string
	Notification *iterm2.CustomEscapeSequenceNotification
}

type GridSize added in v0.0.2 

type GridSize struct {
	Width  int32 `json:"width"`
	Height int32 `json:"height"`
}

type NumberOfLines added in v0.0.2 

type NumberOfLines struct {
	FirstVisible int32 `json:"first_visible"`
	Overflow     int32 `json:"overflow"`
	Grid         int32 `json:"grid"`
	History      int32 `json:"history"`
}

type Rpc 

type Rpc struct {
	// Name is the function's name and makes up the function signature, together with Args.
	Name string

	// Args define the function's expected arguments, given as a struct or *struct. Only fields of type bool, string and
	// float64 are considered, while fields of other types will be ignored. Each field can also be annotated with
	// arg.name and arg.ref to provide the argument's name and a default value as a reference to an iTerm2's built-in
	// variable. If there's no arg.name tag, the value of the json tag or the struct field in lower case are used as a
	// fallback.
	// See https://www.iterm2.com/documentation-variables.html.
	Args interface{}

	// F is the Rpc function implementation.
	F RpcFunc
}

Rpc is a function that can be registered with iTerm2 using RegisterRpc and will be invoked in response to some action or event, such as a keypress or a trigger.

type RpcFunc 

type RpcFunc func(invocation *RpcInvocation) (interface{}, error)

RpcFunc is the implementation of an Rpc function.

type RpcInvocation 

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

RpcInvocation contains all the arguments of the current invocation of a RpcFunc.

func (*RpcInvocation) Args 

func (inv *RpcInvocation) Args(target interface{}) error

Args unmarshalls the invocation arguments into the given *struct, usually the same one used as the Rpc's arguments.

func (*RpcInvocation) Knobs 

func (inv *RpcInvocation) Knobs(target interface{}) error

Knobs unmarshalls the invocation's knobs into the given *struct, usually the same one used as the StatusBarComponent's knobs. Returns ErrNoKnobs when the 'knobs' argument is not found in this invocation (which usually means the Rpc was not registered as a StatusBarComponent).

func (*RpcInvocation) Name added in v0.0.2 

func (inv *RpcInvocation) Name() string

Name gives the name of used by iTerm2 to invoke this callback's parent Rpc.

func (*RpcInvocation) OpenPopover added in v0.0.2 

func (inv *RpcInvocation) OpenPopover(html string, width, height int32) error

type Session added in v0.0.2 

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

func (*Session) Activate added in v0.0.2 

func (s *Session) Activate() error

Activate brings a session to the front.

func (*Session) Active added in v0.0.2 

func (s *Session) Active() (bool, error)

func (*Session) Buried added in v0.0.2 

func (s *Session) Buried() (bool, error)

func (*Session) Close added in v0.0.2 

func (s *Session) Close(force bool) error

Close closes this session.

func (*Session) Id added in v0.0.2 

func (s *Session) Id() string

func (*Session) NumberOfLines added in v0.0.2 

func (s *Session) NumberOfLines() (NumberOfLines, error)

func (*Session) ScreenContents added in v0.0.2 

func (s *Session) ScreenContents() (*iterm2.GetBufferResponse, error)

ScreenContents returns the current screen's contents.

func (*Session) SendText added in v0.0.2 

func (s *Session) SendText(text string, useBroadcastIfEnabled bool) error

SendText sends text to the session, optionally broadcasting it if broadcast is enabled.

func (*Session) SplitPane added in v0.0.2 

func (s *Session) SplitPane(vertical bool, before bool) ([]string, error)

SplitPane splits the pane of the this session, returning the new session IDs on success.

func (*Session) TrailingLines added in v0.0.2 

func (s *Session) TrailingLines(n int32) (*iterm2.GetBufferResponse, error)

type StatusBarComponent 

type StatusBarComponent struct {
	// ShortDescription is shown below the component in the picker UI.
	ShortDescription string

	// Description is used in the tool tip for the component in the picker UI.
	Description string

	// Exemplar is the sample content of the component shown in the picker UI.
	Exemplar string

	// UpdateCadence defines how frequently iTerm2 should invoke the component's Rpc. Zero disables updates.
	UpdateCadence float32

	// Identifier is the unique identifier for the component. Use reverse domain name notation.
	Identifier string

	// Knobs defines the custom controls in the component's configuration panel, as a struct or *struct. Fields of
	// type string, bool and float64 are used in order to create StringKnobs, CheckboxKnob and
	// PositiveFloatingPointKnob, other field types are ignored. The field's name is used as the knob's name and
	// placeholder unless tagged with knob.name and knob.placeholder. The knob's key is set using the `json` tag.
	// TODO support for color knobs.
	Knobs interface{}

	// Rpc is the implementation of the component.
	Rpc Rpc

	OnClick RpcFunc
}

See https://iterm2.com/python-api/statusbar.html.

type TextInputAlert 

type TextInputAlert struct {
	// Title is the window's title.
	Title string
	// Subtitle is an informative text that can span multiple lines.
	Subtitle string

	// Placeholder is a text that appears when the alert's text field is empty
	Placeholder string

	// DefaultValue is the text field's initial content.
	DefaultValue string
}

TextInputAlert is an app-modal or window-modal alert window with a text input field. Use it with App.GetText. See https://www.iterm2.com/python-api/registration.html#iterm2.registration.StatusBarRPC.

type TitleProvider 

type TitleProvider struct {
	// DisplayName is shown in the title provider's drop down in a profile's preference panel.
	DisplayName string

	// Identifier is the unique identifier for the provider. Use reverse domain name notation.
	Identifier string

	// Rpc is the implementation of the provider.
	Rpc Rpc
}

TitleProvider is an Rpc that gets called to compute the title of a session, as frequently as iTerm2 deems necessary, for example when any argument that is a reference to a variable in the session's context changes. See https://iterm2.com/python-api/registration.html#iterm2.registration.TitleProviderRPC.

Source Files

View all Source files

Directories

Path Synopsis
internal
applescript
json
seq
shell
test

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.