README.md
1[](https://travis-ci.org/gopherjs/jsbuiltin) [](http://godoc.org/github.com/gopherjs/jsbuiltin)
2
3jsbuiltin - Built-in JavaScript functions for GopherJS
4------------------------------------------------------
5
6JavaScript has a small number of [built-in
7functions](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects)
8to handle some common day-to-day tasks. This package providers wrappers around
9some of these functions for use in GopherJS.
10
11It is worth noting that in many cases, using Go's equivalent functionality
12(such as that found in the [net/url](https://golang.org/pkg/net/url/) package)
13may be preferable to using this package, and will be a necessity any time you
14wish to share functionality between front-end and back-end code.
15
16### What is supported?
17Not all JavaScript built-in functions make sense or are useful in a Go
18environment. The table below shows each of the JavaScript built-in functions,
19and its current state in this package.
20
21| Name | Supported | Comment |
22|----------------------|-----------|-----------------------------|
23| eval() | -- | |
24| uneval() | -- | |
25| isFinite() | yes | |
26| isNaN() | yes | |
27| parseFloat() | TODO? | See note below |
28| parseInt() | TODO? | See note below |
29| decodeURI() | yes | |
30| decodeURIComponent() | yes | |
31| encodeURI() | yes | |
32| encodeURIComponent() | yes | |
33| escape() | -- | deprecated circa 2000 |
34| Number() | -- | See note below |
35| String() | -- | Use js.Object.String() |
36| unescape() | -- | deprecated circa 2000 |
37| typeof operator | yes | |
38| instanceof operator | yes | |
39
40#### Notes on unmplemented functions
41
42* **eval()**: Is there ever a need to eval JS code from within Go?
43* **Number()**: This requires handling a bunch of corner cases which don't
44 normally exist in a strictly typed language such as Go. It seems that anyone
45 with a legitimate need for this function probably needs to write their own
46 wrapper to handle the cases that matter to them.
47* **parseInt()** and **parseFloat()**: These could be added, but doing so
48 will require answering some questions about the interfce. JavaScript has
49 effectively two relevant data types (int and float) where Go has has 12.
50 Deciding how to map JS's `parseInt()` to Go's `(u?)int(8|16|32|64)` types,
51 and JS's `parseFloat()` Go's `float(32|64)` or `complex(64|128)` needs to
52 be considered, as well as how to handle error cases (Go doesn't have a `NaN`
53 type, so any `NaN` result probably needs to be converted to a proper Go
54 error). If this matters to you, comments and/or PRs are welcome.
55
56### Installation and Usage
57Get or update this package and dependencies with:
58
59```
60go get -u -d -tags=js github.com/gopherjs/jsbuiltin
61```
62
63### Basic usage example
64
65This is a modified version of the Pet example in the main GopherJS documentation,
66to accept and return URI-encoded pet names using the jsbuiltin package.
67
68```go
69package main
70
71import (
72 "github.com/gopherjs/gopherjs/js"
73 "github.com/gopherjs/jsbuiltin"
74)
75
76func main() {
77 js.Global.Set("pet", map[string]interface{}{
78 "New": New,
79 })
80}
81
82type Pet struct {
83 name string
84}
85
86func New(name string) *js.Object {
87 return js.MakeWrapper(&Pet{name})
88}
89
90func (p *Pet) Name() string {
91 return jsbuiltin.EncodeURIComponent(p.name)
92}
93
94func (p *Pet) SetName(uriComponent string) error {
95 name, err := jsbuiltin.DecodeURIComponent(uriComponent)
96 if err != nil {
97 // Malformed UTF8 in uriComponent
98 return err
99 }
100 p.name = name
101 return nil
102}
103```
104
){kind=link}
){kind=link}