mirror of
https://github.com/rubyjs/therubyracer
synced 2023-03-27 23:21:42 -04:00
Change README to markdown, correct some bad information in it regarding default access policy.
This commit is contained in:
Charles Lowell
parent
7c002eaaad
commit
977bcbbeda
2 changed files with 158 additions and 143 deletions
158
README.md
Normal file
158
README.md
Normal file
|
|
@ -0,0 +1,158 @@
|
|||
# therubyracer
|
||||
|
||||
* http://github.com/cowboyd/therubyracer
|
||||
* http://groups.google.com/group/therubyracer
|
||||
* irc://irc.freenode.net/therubyracer
|
||||
|
||||
## DESCRIPTION:
|
||||
|
||||
Embed the V8 Javascript interpreter into Ruby.
|
||||
|
||||
|
||||
## FEATURES/PROBLEMS:
|
||||
|
||||
* Evaluate Javascript from with in Ruby
|
||||
* Embed your Ruby objects into the Javascript world
|
||||
* Manipulate JavaScript objects and call JavaScript functions from Ruby
|
||||
* API compatible with the The Ruby Rhino (for JRuby: http://github.com/cowboyd/therubyrhino)
|
||||
|
||||
## SYNOPSIS:
|
||||
|
||||
gem install therubyracer (stable)
|
||||
gem install therubyracer --pre (bleeding edge)
|
||||
|
||||
then in your ruby code
|
||||
|
||||
require 'v8'
|
||||
|
||||
evaluate some simple javascript
|
||||
|
||||
cxt = V8::Context.new
|
||||
cxt.eval('7 * 6') #=> 42
|
||||
|
||||
embed values into the scope of your context
|
||||
|
||||
cxt['foo'] = "bar"
|
||||
cxt.eval('foo') # => "bar"
|
||||
|
||||
embed ruby code into your scope and call it from javascript
|
||||
|
||||
cxt["say"] = lambda {|word, times| word * times}
|
||||
cxt.eval("say('Hello', 3)") #=> HelloHelloHello
|
||||
|
||||
embed a ruby object into your scope and access its properties/methods from javascript
|
||||
|
||||
class MyMath
|
||||
def plus(lhs, rhs)
|
||||
lhs + rhs
|
||||
end
|
||||
end
|
||||
|
||||
cxt['math'] = MyMath.new
|
||||
cxt.eval("math.plus(20,22)") #=> 42
|
||||
|
||||
make a ruby object *be* your global javascript scope.
|
||||
|
||||
math = MyMath.new
|
||||
V8::Context.new(:with => math) do |cxt|
|
||||
cxt.eval("plus(20,22)") #=> 42
|
||||
end
|
||||
|
||||
you can do the same thing with Object#eval_js
|
||||
|
||||
math.eval_js("plus(20,22)")
|
||||
|
||||
## Different ways of loading javascript source
|
||||
|
||||
In addition to just evaluating strings, you can also use streams such as files.
|
||||
|
||||
evaluate bytes read from any File/IO object:
|
||||
|
||||
File.open("mysource.js") do |file|
|
||||
cxt.eval(file, "mysource.js")
|
||||
end
|
||||
|
||||
or load it by filename
|
||||
|
||||
cxt.load("mysource.js")
|
||||
|
||||
|
||||
## Safe by default
|
||||
|
||||
The Ruby Racer is designed to let you evaluate javascript as safely as possible unless you tell it to do something more
|
||||
dangerous. The default context is a hermetically sealed javascript environment with only the standard javascript objects
|
||||
and functions. Nothing from the ruby world is accessible at all.
|
||||
|
||||
For ruby objects that you explicitly embed into javascript, by default only the _public_ methods _below_ `Object` are
|
||||
exposed by default. E.g.
|
||||
|
||||
class A
|
||||
def a
|
||||
"a"
|
||||
end
|
||||
|
||||
def to_s
|
||||
super
|
||||
end
|
||||
end
|
||||
|
||||
class B < A
|
||||
def b
|
||||
"b"
|
||||
end
|
||||
end
|
||||
|
||||
|
||||
V8::Context.new do |cxt|
|
||||
cxt['a'] = A.new
|
||||
cxt['b'] = B.new
|
||||
cxt.eval("a.a") # => 'a'
|
||||
cxt.eval("b.b") # => 'b'
|
||||
cxt.eval("b.a") # => 'a'
|
||||
cxt.eval("b.to_s") # => #<B:0x101776be8> (because A explicitly defined it)
|
||||
cxt.eval("b.object_id") #=> undefined, object_id is on Object
|
||||
end
|
||||
|
||||
|
||||
## Dangerous by Demand
|
||||
|
||||
All aspects of ruby embedding are pluggable on a per context basis, including
|
||||
the visibility of ruby libraries and classes. If needed, you can expose more aspects
|
||||
of the It is possible to override this
|
||||
safe behavior.
|
||||
|
||||
## REQUIREMENTS:
|
||||
|
||||
* python >= 2.5 (required to compile v8)
|
||||
* C++ compiler
|
||||
|
||||
|
||||
## DEVELOP
|
||||
* git clone git://github.com/cowboyd/therubyracer.git
|
||||
* cd therubyracer
|
||||
* rake compile
|
||||
|
||||
## LICENSE:
|
||||
|
||||
(The MIT License)
|
||||
|
||||
Copyright (c) 2009,2010,2011 Charles Lowell
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining
|
||||
a copy of this software and associated documentation files (the
|
||||
'Software'), to deal in the Software without restriction, including
|
||||
without limitation the rights to use, copy, modify, merge, publish,
|
||||
distribute, sublicense, and/or sell copies of the Software, and to
|
||||
permit persons to whom the Software is furnished to do so, subject to
|
||||
the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be
|
||||
included in all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
||||
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
||||
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
||||
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
||||
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
||||
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
143
README.rdoc
143
README.rdoc
|
|
@ -1,143 +0,0 @@
|
|||
= therubyracer
|
||||
|
||||
* http://github.com/cowboyd/therubyracer
|
||||
* http://groups.google.com/group/therubyracer
|
||||
* irc://irc.freenode.net/therubyracer
|
||||
|
||||
== DESCRIPTION:
|
||||
|
||||
Embed the V8 Javascript interpreter into Ruby.
|
||||
|
||||
|
||||
== FEATURES/PROBLEMS:
|
||||
|
||||
* Evaluate Javascript from with in Ruby
|
||||
* Embed your Ruby objects into the Javascript world
|
||||
* Manipulate JavaScript objects and call JavaScript functions from Ruby
|
||||
* API compatible with the The Ruby Rhino (for JRuby: http://github.com/cowboyd/therubyrhino)
|
||||
* Currently ALPHA software.
|
||||
|
||||
== SYNOPSIS:
|
||||
gem install therubyracer (stable)
|
||||
gem install therubyracer --pre (bleeding edge)
|
||||
|
||||
# then in your ruby code
|
||||
|
||||
require 'v8'
|
||||
|
||||
# evaluate some simple javascript
|
||||
|
||||
cxt = V8::Context.new
|
||||
cxt.eval('7 * 6') #=> 42
|
||||
|
||||
# embed values into the scope of your context
|
||||
|
||||
cxt['foo'] = "bar"
|
||||
cxt.eval('foo') # => "bar"
|
||||
|
||||
# embed ruby code into your scope and call it from javascript
|
||||
|
||||
cxt["say"] = lambda {|word, times| word * times}
|
||||
cxt.eval("say('Hello', 3)") #=> HelloHelloHello
|
||||
|
||||
# embed a ruby object into your scope and access its properties/methods from javascript
|
||||
|
||||
class MyMath
|
||||
def plus(lhs, rhs)
|
||||
lhs + rhs
|
||||
end
|
||||
end
|
||||
|
||||
cxt['math'] = MyMath.new
|
||||
cxt.eval("math.plus(20,22)") #=> 42
|
||||
|
||||
# make a ruby object *be* your global javascript scope.
|
||||
math = MyMath.new
|
||||
V8::Context.new(:with => math) do |cxt|
|
||||
cxt.eval("plus(20,22)") #=> 42
|
||||
end
|
||||
|
||||
#you can do the same thing with Object#eval_js
|
||||
|
||||
math.eval_js("plus(20,22)")
|
||||
|
||||
==== Different ways of loading javascript source
|
||||
|
||||
In addition to just evaluating strings, you can also use streams such as files.
|
||||
|
||||
# evaluate bytes read from any File/IO object:
|
||||
File.open("mysource.js") do |file|
|
||||
cxt.eval(file, "mysource.js")
|
||||
end
|
||||
|
||||
# or load it by filename
|
||||
|
||||
cxt.load("mysource.js")
|
||||
|
||||
=== Safe by default
|
||||
|
||||
The Ruby Racer is designed to let you evaluate javascript as safely as possible unless you tell it to do something more
|
||||
dangerous. The default context is a hermetically sealed javascript environment with only the standard javascript objects
|
||||
and functions. Nothing from the ruby world is accessible at all.
|
||||
|
||||
For ruby objects that you explicitly embed into javascript, only the +public+ methods *defined in their classes* are
|
||||
exposed by default. E.g.
|
||||
|
||||
class A
|
||||
def a
|
||||
"a"
|
||||
end
|
||||
end
|
||||
|
||||
class B < A
|
||||
def b
|
||||
"b"
|
||||
end
|
||||
end
|
||||
|
||||
|
||||
V8::Context.new do |cxt|
|
||||
cxt['a'] = A.new
|
||||
cxt['b'] = B.new
|
||||
cxt.eval("a.a") # => 'a'
|
||||
cxt.eval("b.b") # => 'b'
|
||||
cxt.eval("b.a") # => undef
|
||||
end
|
||||
|
||||
== REQUIREMENTS:
|
||||
|
||||
* python >= 2.5 (required to compile v8)
|
||||
* C++ compiler
|
||||
|
||||
== INSTALL:
|
||||
* gem install therubyracer
|
||||
|
||||
== DEVELOP
|
||||
* git clone git://github.com/cowboyd/therubyracer.git
|
||||
* cd therubyracer
|
||||
* rake compile
|
||||
|
||||
== LICENSE:
|
||||
|
||||
(The MIT License)
|
||||
|
||||
Copyright (c) 2009,2010 Charles Lowell
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining
|
||||
a copy of this software and associated documentation files (the
|
||||
'Software'), to deal in the Software without restriction, including
|
||||
without limitation the rights to use, copy, modify, merge, publish,
|
||||
distribute, sublicense, and/or sell copies of the Software, and to
|
||||
permit persons to whom the Software is furnished to do so, subject to
|
||||
the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be
|
||||
included in all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
||||
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
||||
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
||||
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
||||
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
||||
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
Loading…
Add table
Reference in a new issue