gothic

README

Tcl/Tk Go bindings.

VERSION NOTICE

Recently Tcl/Tk 8.6 were released. I use them as a default, if you still have
Tcl/Tk 8.5 use `go get -tags tcl85 github.com/nsf/gothic`.

DESCRIPTION

In its current state the bindings are a bit Tk-oriented. You can't create an
interpreter instance without Tk. In future it's likely it will be changed.

The API is very simple. In the package you have one type and one function:

type Interpreter struct
func NewInterpreter (init interface{}) *Interpreter

In order to launch an interpreter you have to call the "NewInterpreter"
function, it will make a new instance of a tcl/tk interpreter in a separate
goroutine, execute "init", block in Tk's main loop and then the function
returns a pointer to the new instance of an "Interpreter".

"init" could be a string with tcl commands that are executed before Tk's main
loop, or a function with this signature: "func (*Interpreter)". This function
gets executed the same way as the string, that is - before Tk's main loop.

Here are the methods of the "Interpreter":

func (*Interpreter) ErrorFilter(filt func(error) error)
func (*Interpreter) Eval(args ...interface{}) error
func (*Interpreter) EvalAs(out interface{}, args ...interface{}) error
func (*Interpreter) Set(name string, val interface{}) error
func (*Interpreter) UploadImage(name string, img image.Image) error
func (*Interpreter) RegisterCommand(name string, cbfunc interface{}) error
func (*Interpreter) UnregisterCommand(name string) error
func (*Interpreter) RegisterCommands(name string, val interface{}) error
func (*Interpreter) UnregisterCommands(name string) error

As it was stated before, the "Interpreter" is being executed in a separate
goroutine and each method is completely thread-safe. Also every method is
synchronous. It will queue commands for execution and wait for their
completion.

That's it. See "examples" directory it has the use cases for most of the API.

Documentation

Index

• func Quote(s string) string
• func QuoteRune(r rune) string
• type ArgMap
• type Interpreter
  • func NewInterpreter(init interface{}) *Interpreter
  • func (ir *Interpreter) ErrorFilter(filt func(error) error)
  • func (ir *Interpreter) Eval(format string, args ...interface{}) error
  • func (ir *Interpreter) EvalAs(out interface{}, format string, args ...interface{}) error
  • func (ir *Interpreter) EvalAsBool(format string, args ...interface{}) (bool, error)
  • func (ir *Interpreter) EvalAsFloat(format string, args ...interface{}) (float64, error)
  • func (ir *Interpreter) EvalAsInt(format string, args ...interface{}) (int, error)
  • func (ir *Interpreter) EvalAsString(format string, args ...interface{}) (string, error)
  • func (ir *Interpreter) EvalBytes(s []byte) error
  • func (ir *Interpreter) RegisterCommand(name string, cbfunc interface{}) error
  • func (ir *Interpreter) RegisterCommands(name string, val interface{}) error
  • func (ir *Interpreter) Set(name string, val interface{}) error
  • func (ir *Interpreter) UnregisterCommand(name string) error
  • func (ir *Interpreter) UnregisterCommands(name string) error
  • func (ir *Interpreter) UploadImage(name string, img image.Image) error

Functions

func Quote

func Quote(s string) string

Works exactly like Eval("%{%q}"), but instead of evaluating returns a quoted string.

func QuoteRune

func QuoteRune(r rune) string

Quotes the rune just like if it was passed through Quote, the result is the same as: Quote(string(r)).

Types

type ArgMap

type ArgMap map[string]interface{}

A special type which can be passed to Interpreter.Eval method family as the only argument and in that case you can use named abbreviations within format tags.

type Interpreter

type Interpreter struct {
	Done <-chan int
	// contains filtered or unexported fields
}

A handle that is used to manipulate a TCL interpreter. All handle methods can be safely invoked from different threads. Each method invocation is synchronous, it means that the method will be blocked until the action is actually executed.

`Done` field returns 0 when Tk's main loop exits.

func NewInterpreter

func NewInterpreter(init interface{}) *Interpreter

Creates a new instance of the *gothic.Interpreter. But before interpreter enters the Tk's main loop it will execute `init`. Init argument could be a string or a function with this signature: "func(*gothic.Interpreter)".

func (*Interpreter) ErrorFilter

func (ir *Interpreter) ErrorFilter(filt func(error) error)

Every TCL error goes through the filter passed to this function. If you pass nil, then no error filter is set.

func (*Interpreter) Eval

func (ir *Interpreter) Eval(format string, args ...interface{}) error

Queue script for evaluation and wait for its completion. This function uses printf-like formatting style, except that all the formatting tags are enclosed within %{}. The reason for this is because tcl/tk uses %-based formatting tags for its own purposes. Also it provides several extensions like named and positional arguments. When no arguments are provided it will evaluate the format string as-is.

Another important difference between fmt.Sprintf and Eval is that when using Eval, invalid format/arguments combination results in an error, while fmt.Sprintf simply ignores misconfiguration. All the formatter generated errors go through ErrorFilter, just like any other tcl error.

The syntax for formatting tags is:

%{[<abbrev>[<format>]]}

Where:

<abbrev> could be a number of the function argument (starting from 0) or a
         name of the key in the provided gothic.ArgMap argument. It can
         also be empty, in this case it uses internal counter, takes the
         corresponding argument and increments that counter.

<format> Is the fmt.Sprintf format specifier, passed directly to
         fmt.Sprintf as is (except for %q, see additional notes).

Additional notes:

1. Formatter is extended to do TCL-specific quoting on %q format specifier.
2. Named abbrev is only allowed when there is one argument and the type of this argument is gothic.ArgMap.

Examples:

1. gothic.Eval("%{0} = %{1} + %{1}", 10, 5) "10 = 5 + 5"
2. gothic.Eval("%{} = %{%d} + %{1}", 20, 10) "20 = 10 + 10"
3. gothic.Eval("%{0%.2f} and %{%.2f}", 3.1415) "3.14 and 3.14"
4. gothic.Eval("[myfunction %{arg1} %{arg2}]", gothic.ArgMap{ "arg1": 5, "arg2": 10, }) "[myfunction 5 10]"
5. gothic.Eval("%{%q}", "[command $variable]") `"\[command \$variable\]"`

func (*Interpreter) EvalAs

func (ir *Interpreter) EvalAs(out interface{}, format string, args ...interface{}) error

Works exactly as Eval with exception that it writes the result of executed code into `out`.

func (*Interpreter) EvalAsBool

func (ir *Interpreter) EvalAsBool(format string, args ...interface{}) (bool, error)

Shortcut for `var b bool; err := EvalAs(&b, format, args...)`

func (*Interpreter) EvalAsFloat

func (ir *Interpreter) EvalAsFloat(format string, args ...interface{}) (float64, error)

Shortcut for `var f float64; err := EvalAs(&f, format, args...)`

func (*Interpreter) EvalAsInt

func (ir *Interpreter) EvalAsInt(format string, args ...interface{}) (int, error)

Shortcut for `var i int; err := EvalAs(&i, format, args...)`

func (*Interpreter) EvalAsString

func (ir *Interpreter) EvalAsString(format string, args ...interface{}) (string, error)

Shortcut for `var s string; err := EvalAs(&s, format, args...)`

func (*Interpreter) EvalBytes

func (ir *Interpreter) EvalBytes(s []byte) error

Works the same way as Eval("%{}", byte_slice), but avoids unnecessary buffering.

func (*Interpreter) RegisterCommand

func (ir *Interpreter) RegisterCommand(name string, cbfunc interface{}) error

Register a new TCL command called `name`.

func (*Interpreter) RegisterCommands

func (ir *Interpreter) RegisterCommands(name string, val interface{}) error

Register multiple TCL command within the `name` namespace. The method uses runtime reflection and registers only those methods of the `val` which have one of the following prefixes: "TCL" or "TCL_". The name of the resulting command doesn't include the prefix.

func (*Interpreter) Set

func (ir *Interpreter) Set(name string, val interface{}) error

Sets the TCL variable `name` to the `val`. Sometimes it's nice to be able to avoid going through TCL's syntax. Especially for things like passing a whole buffer of text to TCL.

func (*Interpreter) UnregisterCommand

func (ir *Interpreter) UnregisterCommand(name string) error

Unregisters (deletes) previously registered command `name`.

func (*Interpreter) UnregisterCommands

func (ir *Interpreter) UnregisterCommands(name string) error

Unregisters (deletes) previously registered command set within the `name` namespace.

func (*Interpreter) UploadImage

func (ir *Interpreter) UploadImage(name string, img image.Image) error