dfhackrpc

README

DFHack RPC client (Go implementation)

Package dfhackrpc provides a DFHack RPC client.

For example code, see the dfhack-run command.

Documentation

Overview

Package dfhackrpc provides a DFHack RPC client.

Index

• type Client
  • func NewClient(w io.Writer) *Client
  • func NewClientColor(w io.Writer, color bool) *Client
  • func (c *Client) Call(method string, request, response proto.Message) (CommandResult, error)
  • func (c *Client) CallPlugin(plugin, method string, request, response proto.Message) (CommandResult, error)
  • func (c *Client) Close() error
  • func (c *Client) Connect() error
  • func (c *Client) ConnectAddr(addr string) error
  • func (c *Client) Lock()
  • func (c *Client) RunCommand(command string, args ...string) (CommandResult, error)
  • func (c *Client) RunLua(module, function string, args ...string) ([]string, CommandResult, error)
  • func (c *Client) Unlock()
• type CommandResult
  • func (rv CommandResult) Err() error
  • func (rv CommandResult) String() string

Types

type Client

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

Client is a DFHack RPC client. Use NewClient to create an instance of this type. All methods on Client can be called safely from multiple goroutines.

Client will automatically reconnect if a protocol error was encountered on the previous method call.

func NewClient

func NewClient(w io.Writer) *Client

NewClient constructs a client that writes output to w. The output will use colors if w is a terminal (TTY).

func NewClientColor

func NewClientColor(w io.Writer, color bool) *Client

NewClientColor constructs a client that writes output to w. The output will use colors if and only if color is set to true.

func (*Client) Call

func (c *Client) Call(method string, request, response proto.Message) (CommandResult, error)

Call runs an RPC method. It is an error to call a method with the wrong request or response type. If request or response are nil or their types do not match the types used the first time the method was called, Call will panic.

func (*Client) CallPlugin

func (c *Client) CallPlugin(plugin, method string, request, response proto.Message) (CommandResult, error)

CallPlugin runs an RPC method, similar to Call, but also allows you to specify a plugin name in order to call plugin methods API methods.

func (*Client) Close

func (c *Client) Close() error

Close disconnects the client. When this method returns, the client will be in a valid disconnected state regardless of the error returned.

func (*Client) Connect

func (c *Client) Connect() error

Connect connects to localhost on the port given by the DFHACK_PORT environment variable, or 5000 if it is not set to a positive integer.

func (*Client) ConnectAddr

func (c *Client) ConnectAddr(addr string) error

ConnectAddr connects to a specified TCP address. If the Client is already connected, an error is returned. If any error occurs while connecting, the client will be in a valid disconnected state when this method returns.

func (*Client) Lock

func (c *Client) Lock()

Lock is a convenience wrapper around the CoreSuspend RPC method. It implements the sync.Locker interface and panics if an error occurs.

func (*Client) RunCommand

func (c *Client) RunCommand(command string, args ...string) (CommandResult, error)

RunCommand is a convenience wrapper around the RunCommand RPC method.

func (*Client) RunLua

func (c *Client) RunLua(module, function string, args ...string) ([]string, CommandResult, error)

RunLua is a convenience wrapper around the RunLua RPC method.

func (*Client) Unlock

func (c *Client) Unlock()

Unlock is a convenience wrapper around the CoreResume RPC method. It implements the sync.Locker interface and panics if an error occurs.

type CommandResult

type CommandResult int

CommandResult is a DFHack command result.

const (
	// LinkFailure is a failure due to an I/O or protocol error.
	LinkFailure CommandResult = -3
	// NeedsConsole is a failure due to a command requiring an interactive
	// context.
	NeedsConsole CommandResult = -2
	// NotImplemented is a failure due to a command not being implemented
	// or a plugin not being loaded.
	NotImplemented CommandResult = -1
	// OK is success.
	OK CommandResult = 0
	// Failure is a generic failure code.
	Failure CommandResult = 1
	// WrongUsage is a failure due to passing the wrong arguments or using
	// a command at a time when it is not valid.
	WrongUsage CommandResult = 2
	// NotFound is a failure due to something being missing, usually a
	// method or command.
	NotFound CommandResult = 3
)

func (CommandResult) Err

func (rv CommandResult) Err() error

Err is a convenience function that returns an error with the value from rv.String(), or nil if rv is OK.

func (CommandResult) String

func (rv CommandResult) String() string

String implements fmt.Stringer