From 977bcbbeda0a636a6680499859abcf79e8e1890b Mon Sep 17 00:00:00 2001 From: Charles Lowell Date: Mon, 17 Jan 2011 13:58:18 -0600 Subject: [PATCH] Change README to markdown, correct some bad information in it regarding default access policy. --- README.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.rdoc | 143 ----------------------------------------------- 2 files changed, 158 insertions(+), 143 deletions(-) create mode 100644 README.md delete mode 100644 README.rdoc diff --git a/README.md b/README.md new file mode 100644 index 0000000..43382da --- /dev/null +++ b/README.md @@ -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") # => # (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. \ No newline at end of file diff --git a/README.rdoc b/README.rdoc deleted file mode 100644 index ab0b85a..0000000 --- a/README.rdoc +++ /dev/null @@ -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. \ No newline at end of file