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 (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
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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:
- Formatter is extended to do TCL-specific quoting on %q format specifier.
- Named abbrev is only allowed when there is one argument and the type of this argument is gothic.ArgMap.
Examples:
- gothic.Eval("%{0} = %{1} + %{1}", 10, 5) "10 = 5 + 5"
- gothic.Eval("%{} = %{%d} + %{1}", 20, 10) "20 = 10 + 10"
- gothic.Eval("%{0%.2f} and %{%.2f}", 3.1415) "3.14 and 3.14"
- gothic.Eval("[myfunction %{arg1} %{arg2}]", gothic.ArgMap{ "arg1": 5, "arg2": 10, }) "[myfunction 5 10]"
- 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
Source Files
Directories