README
¶
go-candyjs 
CandyJS is an intent of create a fully transparent bridge between Go and the JavaScript engine duktape. Basicly is a syntax-sugar library built it on top of go-duktape using reflection techniques.
ok but what for ...
build extensible applications that allow to the user execute arbitrary code (let's say plugins) without the requirement of compile it.
Demo
Features
Embeddable Ecmascript E5/E5.1 compliant engine (duktape).
ctx := candyjs.NewContext()
ctx.EvalString(`
function factorial(n) {
if (n === 0) return 1;
return n * factorial(n - 1);
}
print(factorial(10));
`) //3628800
Call Go functions from JavaScript and vice versa.
ctx := candyjs.NewContext()
ctx.PushGlobalGoFunction("golangMultiply", func(a, b int) int {
return a * b
})
ctx.EvalString(`print(golangMultiply(5, 10));`) //50
Transparent interface between Go structs and JavaScript.
type MyStruct struct {
Number int
}
func (m *MyStruct) Multiply(x int) int {
return m.Number * x
}
...
ctx := candyjs.NewContext()
ctx.PushGlobalStruct("golangStruct", &MyStruct{10})
ctx.EvalString(`print(golangStruct.number);`) //10
ctx.EvalString(`print(golangStruct.multiply(5));`) //50
Import of Go packages into the JavaScript context.
//go:generate candyjs import fmt
...
ctx := candyjs.NewContext()
ctx.EvalString(`
var fmt = CandyJS.require('fmt');
fmt.printf('candyjs is %s', 'awesome')
`) // 'candyjs is awesome'
Installation
The recommended way to install go-candyjs is:
go get -u github.com/mcuadros/go-candyjs/...
CandyJS includes a binary tool used by go generate, please be sure that
$GOPATH/binis on your$PATH
Examples
JavaScript running a HTTP server
In this example a gin server is executed
and a small JSON is server. In CandyJS you can import Go packages directly if
they are defined
previously on the Go code.
Interpreter code (main.go)
...
//go:generate candyjs import time
//go:generate candyjs import github.com/gin-gonic/gin
func main() {
ctx := candyjs.NewContext()
ctx.PevalFile("example.js")
}
Program code (example.js)
var time = CandyJS.require('time');
var gin = CandyJS.require('github.com/gin-gonic/gin');
var engine = gin.default();
engine.get("/back", CandyJS.proxy(function(ctx) {
var future = time.date(2015, 10, 21, 4, 29 ,0, 0, time.UTC);
var now = time.now();
ctx.json(200, {
future: future.string(),
now: now.string(),
nsecs: future.sub(now)
});
}));
engine.run(':8080');
Caveats
Due to an incompatibility with Duktape's error handling system and Go, you can't throw errors from Go. All errors generated from Go functions are generic ones error error (rc -100)
License
MIT, see LICENSE
Documentation
¶
Index ¶
- Variables
- func RegisterPackagePusher(pckgName string, f PackagePusher)
- type Context
- func (ctx *Context) PushGlobalGoFunction(name string, f interface{}) (int, error)
- func (ctx *Context) PushGlobalInterface(name string, v interface{}) error
- func (ctx *Context) PushGlobalPackage(pckgName, alias string) error
- func (ctx *Context) PushGlobalProxy(name string, v interface{}) int
- func (ctx *Context) PushGlobalStruct(name string, s interface{}) (int, error)
- func (ctx *Context) PushGlobalType(name string, s interface{}) int
- func (ctx *Context) PushGoFunction(f interface{}) int
- func (ctx *Context) PushInterface(v interface{}) error
- func (ctx *Context) PushProxy(v interface{}) int
- func (ctx *Context) PushStruct(s interface{}) (int, error)
- func (ctx *Context) PushType(s interface{}) int
- func (ctx *Context) SetRequireFunction(f interface{}) int
- type PackagePusher
Constants ¶
This section is empty.
Variables ¶
var ErrPackageNotFound = errors.New("Unable to find the requested package")
PackageNotFound error is throw when a package cannot be found, usually this happend when a PackagePusher function was not registered using RegisterPackagePusher.
var ErrUndefinedProperty = errors.New("undefined property")
ErrUndefinedProperty is throw when a property for a given proxied object on javascript cannot be found, basically a valid method or field cannot found.
Functions ¶
func RegisterPackagePusher ¶
func RegisterPackagePusher(pckgName string, f PackagePusher)
RegisterPackagePusher registers a PackagePusher into the global storage, this storage is a private map defined on the candyjs package. The pushers are launch by the function PushGlobalPackage.
Types ¶
type Context ¶
type Context struct {
*duktape.Context
// contains filtered or unexported fields
}
Context represents a Duktape thread and its call and value stacks.
func (*Context) PushGlobalGoFunction ¶
PushGlobalGoFunction like PushGoFunction but pushed to the global object
func (*Context) PushGlobalInterface ¶
PushGlobalInterface like PushInterface but pushed to the global object
func (*Context) PushGlobalPackage ¶
PushGlobalPackage all the functions and types from the given package using the pre-registered PackagePusher function.
func (*Context) PushGlobalProxy ¶
PushGlobalProxy like PushProxy but pushed to the global object
func (*Context) PushGlobalStruct ¶
PushGlobalStruct like PushStruct but pushed to the global object
func (*Context) PushGlobalType ¶
PushGlobalType like PushType but pushed to the global object
func (*Context) PushGoFunction ¶
PushGoFunction push a native Go function of any signature to the stack. A pointer to the function is stored in the internals of the context and collected by the duktape GC removing any reference in Go also.
The most common types are supported as input arguments, also the variadic functions can be used.
You can use JS functions as arguments but you should wrapper it with the helper `CandyJS.proxy`. Example:
ctx.PushGlobalGoFunction("test", func(fn func(int, int) int) {
...
})
ctx.PevalString(`test(CandyJS.proxy(function(a, b) { return a * b; }));`)
The structs can be delivered to the functions in three ways:
- In-line representation as plain JS objects: `{'int':42}`
- Using a previous pushed type using `PushGlobalType`: `new MyModel`
- Using a previous pushed instance using `PushGlobalProxy`
All other types are loaded into Go using `json.Unmarshal` internally ¶
The following types are not supported chans, complex64 or complex128, and the types rune, byte and arrays are not tested.
The returns are handled in the following ways:
- The result of functions with a single return value like `func() int` is pushed directly to the stack.
- Functions with a n return values like `func() (int, int)` are pushed as an array. The errors are removed from this array.
- Returns of functions with a trailling error like `func() (string, err)`: if err is not nil an error is throw in the context, and the other values are discarded. IF err is nil, the values are pushed to the stack, following the previuos rules.
All the non erros returning values are pushed following the same rules of `PushInterface` method
func (*Context) PushInterface ¶
PushInterface push any type of value to the stack, the following types are supported:
- Bool
- Int, Int8, Int16, Int32, Uint, Uint8, Uint16, Uint32 and Uint64
- Float32 and Float64
- Strings and []byte
- Structs
- Functions with any signature
Please read carefully the following notes:
- The pointers are resolved and the value is pushed
- Structs are pushed ussing PushProxy, if you want to make a copy use PushStruct
- Int64 and UInt64 are supported but before push it to the stack are casted to float64
- Any unsuported value is pushed as a null
func (*Context) PushProxy ¶
PushProxy push a proxified pointer of the given value to the stack, this refence will be stored on an internal storage. The pushed objects has the exact same methods and properties from the original value. http://duktape.org/guide.html#virtualization-proxy-object
func (*Context) PushStruct ¶
PushStruct push a object to the stack with the same methods and properties the pushed object is a copy, any change made on JS is not reflected on the Go instance.
func (*Context) PushType ¶
PushType push a constructor for the type of the given value, this constructor returns an empty instance of the type. The value passed is discarded, only is used for retrieve the time, instead of require pass a `reflect.Type`.
func (*Context) SetRequireFunction ¶
SetRequireFunction sets the modSearch function into the Duktape JS object http://duktape.org/guide.html#builtin-duktape-modsearch-modloade
type PackagePusher ¶
type PackagePusher func(ctx *Context)
PackagePusher should be a function capable of register all functions and types contained on a golang packages. This functions are generated by the go generate tool `candyjs` a example of this header is:
//go:generate candyjs import time
Source Files
Directories