Support creating a global ObjectTemplate into a context

[rogchap]

Provides creating a global object that can be initiated within each Context eg:

iso, _ := v8go.NewIsolate()
obj, _ := v8go.NewObjectTemplate(iso)
obj.Set("version", "v1.0.0", v8go.ReadOnly)
ctx, _ := v8go.NewContext(iso, obj)
val, _ := ctx.RunScript("version", "main.js")
fmt.Println(val)
// Output:
// v1.0.0

The same ObjectTemplate can be used in many Contexts as long as they are part of the same Isolate (VM).

This PR also adds the ability to create primitive values that can be properties on the global object.

This is the prerequisite to FunctionTemplates for the global context.

As a side-effect of this PR. The NewContext() API has changed to optionally accept a Isolate and a Global Template, this makes for a nice API as you see above, but also allows for this:

ctx, _ := v8go.NewContext()    // previously you would do v8go.NewContext(nil)

This is fully backwards compatible.

I've not updated the README.md to not confuse readers, until this is released into a new version.

[tmc]

This is looking great -- mostly minor comments.

[tmc]

mentioned in the diff inline but in the PR description as well, the Set call's attribute just being passed as "0" is a bit blah.

perhaps we should consider a different api to set the property attributes so that could be omitted in the normal case?

[rogchap]

Set call's attribute just being passed as "0" is a bit blah.
perhaps we should consider a different api to set the property attributes so that could be omitted in the normal case?

That's me just being lazy. I'll change the examples to use the enum/const.
I'm open to suggestions on the API, however this is the API that is provided by the C++ API, and I want to keep as true to that as possible.

For ObjectTemplate's it's more likely that you want to set ReadOnly rather than None anyway.

Ps. I'm not a huge fan of APIs that have prepositions (e.g. "For", "With", "At", "To") if they can be avoided; adding an argument to a method makes more sense unless the method has a distinct verb. The challenge is that Go does not have overloaded methods, but C++ does, so there will be some compromise needed here (from me).

[tmc]

That's fair, I think attempting to match the c++ makes sense (and I know it's stated goal).

It's just too bad that something as succinct as x.Set("foo", "bar") isn't possible with this PR due to the PropertyAttribute parameter. It seems as though it's going to be pretty rare for anything but ReadOnly, at least to start.

I'm curious about the use case in mind for exposing the properties here and if we can grow the api surface area at a later time.

[rogchap]

It's just too bad that something as succinct as x.Set("foo", "bar") isn't possible

The goals do state to match the C++ API, but still as idiomatic Go as possible (our get out of jail free card 😉 ).
What we could do is change this API to a variadic function, similar to what we are doing for Context.

This would make the property attribute optional and default to None.

Ps. the PropertyAttribute is also used for normal Objects (not template ones); so would have to do the same there too.

What do you think @tmc ?

[rogchap]

So thinking about this a bit more... rather than a varadic function with "SetOptions"... what about just doing a varadic function of PropertyAttributes, because they are flags that can be added together?

This is better explained via examples:

Current API

func (o *ObjectTemplate) Set(name string, val interface{}, attributes PropertyAttribute) error 

// the caller would do:
obj.Set("foo", "bar", v8go.ReadOnly)
// or for multiple:
obj.Set("foo", "bar, v8go.ReadOnly | v8go.DontEnum)

Proposed API (v2)

func (o *ObjectTemplate) Set(name string, val interface{}, attributes ...PropertyAttribute) error 

// previous examples would still be valid
obj.Set("foo", "bar", v8go.ReadOnly)
obj.Set("foo", "bar, v8go.ReadOnly | v8go.DontEnum)

// but would also allow for this
obj.Set("foo", "bar")
obj.Set("foo", "bar, v8go.ReadOnly, v8go.DontEnum)

In the last example the slice of attributes would be converted to OR ie.

var attrs PropertyAttribute
for _, a := range attributes {
    attrs |= a
}

// ie: 

obj.Set("foo", "bar, v8go.ReadOnly, v8go.DontEnum)
// is equal to 
obj.Set("foo", "bar, v8go.ReadOnly | v8go.DontEnum)

[tmc]

LGTM!