kotovalexarian-likes-github/therubyrhino
1
0
Fork 0
mirror of https://github.com/rubyjs/therubyrhino synced 2023-03-27 23:21:34 -04:00
Code Releases Activity

markdown-ize README/History

Browse source
This commit is contained in:
kares 2013-06-16 14:30:03 +02:00
parent ba9006baf2
commit b169814ed9
3 changed files with 137 additions and 105 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

59
History.txt → History.md
View file

@ -1,55 +1,57 @@
=== 2.0.2 2012-12-05 ## 2.0.2 2012-12-05
* handle Rhino's 64K code generation (method) limit on the fly (#23) * handle Rhino's 64K code generation (method) limit on the fly (#23)
* correct explicit Ruby equality == and eql? (JRuby 1.7.1 compat) * correct explicit Ruby equality == and eql? (JRuby 1.7.1 compat)
* allow to set javascript version programatically - globally also allow * allow to set javascript version programatically - globally also allow
reading it from system properties by default reading it from system properties by default
* allow to set optimization level globally also allow reading it from * allow to set optimization level globally also allow reading it from
system properties by default system properties by default
* make sure Ruby function wrapper has (Ruby) #call semantics just like * make sure Ruby function wrapper has (Ruby) #call semantics just like
JavaScript functions exposed into the Ruby side JavaScript functions exposed into the Ruby side
* function's return value should be converted to Ruby (Ruby #call style) * function's return value should be converted to Ruby (Ruby #call style)
=== 2.0.1 2012-08-24 ## 2.0.1 2012-08-24
* JSError improvement to preserve nested Ruby error message * JSError improvement to preserve nested Ruby error message
* jar-1.7.4 regression fix e.g when loading less (#25) * jar-1.7.4 regression fix e.g when loading less (#25)
* error.message should be a String value (1.9.3 compat) * error.message should be a String value (1.9.3 compat)
=== jar-1.7.4 2012-08-02 ## jar-1.7.4 2012-08-02
* updated to new Mozilla Rhino 1.7R4 release, notes: * updated to new Mozilla Rhino 1.7R4 release, notes:
https://developer.mozilla.org/en/New_in_Rhino_1.7R4 https://developer.mozilla.org/en/New_in_Rhino_1.7R4
=== 2.0.0 2012-08-02 ## 2.0.0 2012-08-02
This release is functionally the same as therubyrhino-1.73.5 as long
This release is functionally the same as therubyrhino-1.73.5 as long
as the therubyrhino_jar-1.7.3 gem dependency is used along with it. as the therubyrhino_jar-1.7.3 gem dependency is used along with it.
* new versioning scheme - old scheme used for the jar gem * new versioning scheme - old scheme used for the jar gem
* moved out the rhino.jar into a separate therubyrhino_jar gem * moved out the rhino.jar into a separate therubyrhino_jar gem
=== jar-1.7.3 2012-08-02 ## jar-1.7.3 2012-08-02
* therubyrhino_jar gem packaged with Mozilla Rhino 1.7R3 * therubyrhino_jar gem packaged with Mozilla Rhino 1.7R3
=== 1.73.5 2012-07-25 ## 1.73.5 2012-07-25
* #to_s functionName typo fix for org.mozilla.javascript.ScriptStackElement * #to_s functionName typo fix for org.mozilla.javascript.ScriptStackElement
* make sure thrown values are correctly raised from inside JS functions * make sure thrown values are correctly raised from inside JS functions
* a better #inspect for native rhino objects * a better #inspect for native rhino objects
* correct JavaScript error handling for Function#apply * correct JavaScript error handling for Function#apply
=== 1.73.4 2012-05-21 ## 1.73.4 2012-05-21
* allow rhino.jar path overrides with Rhino::JAR_PATH * allow rhino.jar path overrides with Rhino::JAR_PATH
* 'correct' JSError#inspect - show thrown value * 'correct' JSError#inspect - show thrown value
* fix JSError#javascript_backtrace to be an array and add it on top of the * fix JSError#javascript_backtrace to be an array and add it on top of the
(ruby) backtrace (ruby) backtrace
* make sure JSError#cause always points to native rhino cause (#19) * make sure JSError#cause always points to native rhino cause (#19)
* avoid using instance variables with 'native' JS::Context (JRuby 1.7 warnings) * avoid using instance variables with 'native' JS::Context (JRuby 1.7 warnings)
=== 1.73.3 2012-04-23 ## 1.73.3 2012-04-23
RedJS 0.4 compatible RedJS 0.4 compatible
* allow try-catch-ing ScriptError (besides StandardError) in JS * allow try-catch-ing ScriptError (besides StandardError) in JS
@ -59,7 +61,8 @@ RedJS 0.4 compatible
* Ruby StandardError wrapping so they can be try-catched as JS "error" values * Ruby StandardError wrapping so they can be try-catched as JS "error" values
* Rhino::Context.new is expected to yield when block passed * Rhino::Context.new is expected to yield when block passed
=== 1.73.2 2012-04-11 ## 1.73.2 2012-04-11
RedJS 0.2.1 compatible RedJS 0.2.1 compatible
* improve JSError#message + add JSError#value to reflect throw JS value * improve JSError#message + add JSError#value to reflect throw JS value
@ -69,7 +72,8 @@ RedJS 0.2.1 compatible
* restrictable limits now require Contex.new(:restrictable => true) * restrictable limits now require Contex.new(:restrictable => true)
* added Context#timeout_limit (to complete instruction_limit) * added Context#timeout_limit (to complete instruction_limit)
=== 1.73.1 2011-11-28 ## 1.73.1 2011-11-28
NOTE: this is a "major" code update from 1.73.0 with some incompatibilities NOTE: this is a "major" code update from 1.73.0 with some incompatibilities
although keeping the bits backward compatible as much as possible : although keeping the bits backward compatible as much as possible :
@ -90,51 +94,58 @@ although keeping the bits backward compatible as much as possible :
* support for setting JS version via Context.version * support for setting JS version via Context.version
* Rhino::J gets deprecated it's now know as Rhino::JS * Rhino::J gets deprecated it's now know as Rhino::JS
=== 1.73.0 2011-11-28 ## 1.73.0 2011-11-28
* upgrade to rhino-1.7R3 * upgrade to rhino-1.7R3
* cache objects passed to context - same object passed twice ends up the same * cache objects passed to context - same object passed twice ends up the same
* properly map ruby Time objects to javascript Date * properly map ruby Time objects to javascript Date
* jruby --1.9 improvements * jruby --1.9 improvements
=== 1.72.8 2011-06-26 ## 1.72.8 2011-06-26
* fix passing of options hash to ruby. * fix passing of options hash to ruby.
=== 1.72.6 2009-11-30 ## 1.72.6 2009-11-30
* 2 major enhancements: * 2 major enhancements:
* evaluate an IO object such as a file or an socket input stream * evaluate an IO object such as a file or an socket input stream
* load javascript sources directly into the context with the file system * load javascript sources directly into the context with the file system
=== 1.72.5 2009-11-12 ## 1.72.5 2009-11-12
* 2 major enhancements: * 2 major enhancements:
* evaluate javascript with a ruby object as it's scope using Context#open(:with => object) * evaluate javascript with a ruby object as it's scope using Context#open(:with => object)
* add eval_js() method to Object to evaluate in the context of that object * add eval_js() method to Object to evaluate in the context of that object
=== 1.72.4 2009-11-12 ## 1.72.4 2009-11-12
* 3 major enhancements: * 3 major enhancements:
* automatically wrap/unwrap ruby and javascript arrays * automatically wrap/unwrap ruby and javascript arrays
* automatically convert ruby method objects and Proc objects into javascript functions * automatically convert ruby method objects and Proc objects into javascript functions
* Make functions defined in javascript callable from ruby * Make functions defined in javascript callable from ruby
=== 1.72.3 2009-11-11 ## 1.72.3 2009-11-11
* 4 major enhancements: * 4 major enhancements:
* greatly simplified interface to context by unifying context and scope * greatly simplified interface to context by unifying context and scope
* remove Context#open_std() * remove Context#open_std()
* remove Context#standard * remove Context#standard
* remove Context#init_standard_objects * remove Context#init_standard_objects
=== 1.72.2 2009-11-10 ## 1.72.2 2009-11-10
* 1 major enhancement: * 1 major enhancement:
* ability to limit the instruction count for a context * ability to limit the instruction count for a context
=== 1.72.1 2009-11-09 ## 1.72.1 2009-11-09
* 4 major enhancements: * 4 major enhancements:
* easily manipulate javascript objects from ruby (NativeObject) * easily manipulate javascript objects from ruby (NativeObject)
* make NativeObject Enumerable * make NativeObject Enumerable
* to_h and to_json for NativeObject * to_h and to_json for NativeObject
* embed ruby instances and call methods from javascript * embed ruby instances and call methods from javascript
=== 1.72.0 2009-09-24 ## 1.72.0 2009-09-24
* 2 major enhancements: * 2 major enhancements:
* evaluate javascript in jruby * evaluate javascript in jruby

175
README.rdoc → README.md
View file

@ -1,44 +1,54 @@
= therubyrhino # therubyrhino
* http://github.com/cowboyd/therubyrhino
* irc://irc.freenode.net/therubyrhino
== DESCRIPTION:
Embed the Mozilla Rhino JavaScript interpreter into Ruby Embed the Mozilla Rhino JavaScript interpreter into Ruby
== FEATURES/PROBLEMS: ## REQUIREMENTS:
* JRuby >= 1.6.8
## INSTALL:
`jruby -S gem install therubyrhino`
## FEATURES/PROBLEMS:
* Evaluate JavaScript from with in Ruby * Evaluate JavaScript from with in Ruby
* Embed your Ruby objects into the JavaScript world * Embed your Ruby objects into the JavaScript world
== SYNOPSIS: ## SYNOPSIS:
1. JavaScript goes into Ruby 1. JavaScript goes into Ruby
2. Ruby Objects goes into JavaScript 2. Ruby Objects goes into JavaScript
3. Our shark's in the JavaScript! 3. Our shark's in the JavaScript!
```ruby
require 'rhino' require 'rhino'
```
# evaluate some simple javascript
eval_js "7 * 6" #=> 42
# that's quick and dirty, but if you want more control over your * evaluate some simple JavaScript using `eval_js`:
# environment, use a Context: ```ruby
eval_js "7 * 6" #=> 42
```
* that's quick and dirty, but if you want more control over your environment,
use a `Context`:
```ruby
Rhino::Context.open do |cxt| Rhino::Context.open do |cxt|
cxt['foo'] = "bar" cxt['foo'] = "bar"
cxt.eval('foo') # => "bar" cxt.eval('foo') # => "bar"
end end
```
# evaluate a ruby function from JS * evaluate a Ruby function from JavaScript:
```ruby
Rhino::Context.open do |context| Rhino::Context.open do |context|
context["say"] = lambda {|word, times| word * times} context["say"] = lambda {|word, times| word * times}
context.eval("say("Hello", 3)") #=> HelloHelloHello context.eval("say("Hello", 3)") #=> HelloHelloHello
end end
```
# embed a ruby object into your JS environment
* embed a Ruby object into your JavaScript environment
```ruby
class MyMath class MyMath
def plus(lhs, rhs) def plus(lhs, rhs)
lhs + rhs lhs + rhs
@ -49,89 +59,103 @@ Embed the Mozilla Rhino JavaScript interpreter into Ruby
context["math"] = MyMath.new context["math"] = MyMath.new
context.eval("math.plus(20, 22)") #=> 42 context.eval("math.plus(20, 22)") #=> 42
end end
```
# make a ruby object *be* your JS environment
* make a Ruby object *be* your JavaScript environment
```ruby
math = MyMath.new math = MyMath.new
Rhino::Context.open(:with => math) do |context| Rhino::Context.open(:with => math) do |context|
context.eval("plus(20, 22)") #=> 42 context.eval("plus(20, 22)") #=> 42
end end
#or the equivalent # or the equivalent
math.eval_js("plus(20, 22)") math.eval_js("plus(20, 22)")
```
# Configure your embedding setup * configure your embedding setup
# Make your standard objects (Object, String, etc...) immutable * make your standard objects (Object, String, etc...) immutable:
```ruby
Rhino::Context.open(:sealed => true) do |context| Rhino::Context.open(:sealed => true) do |context|
context.eval("Object.prototype.toString = function() {}") # this is an error! context.eval("Object.prototype.toString = function() {}") # this is an error!
end end
```
#Turn on Java integration from javascript (probably a bad idea)
* turn on Java integration from JavaScript (probably a bad idea):
```ruby
Rhino::Context.open(:java => true) do |context| Rhino::Context.open(:java => true) do |context|
context.eval("java.lang.System.exit()") # it's dangerous! context.eval("java.lang.System.exit()") # it's dangerous!
end end
```
#limit the number of instructions that can be executed in order to prevent * limit the number of instructions that can be executed to prevent rogue code:
#rogue scripts ```ruby
Rhino::Context.open(:restrictable => true) do |context| Rhino::Context.open(:restrictable => true) do |context|
context.instruction_limit = 100000 context.instruction_limit = 100000
context.eval("while (true);") # => Rhino::RunawayScriptError context.eval("while (true);") # => Rhino::RunawayScriptError
end end
```
#limit the time a script executes * limit the time a script executes (rogue scripts):
#rogue scripts ```ruby
Rhino::Context.open(:restrictable => true, :java => true) do |context| Rhino::Context.open(:restrictable => true, :java => true) do |context|
context.timeout_limit = 1.5 # seconds context.timeout_limit = 1.5 # seconds
context.eval %Q{ context.eval %Q{
for (var i = 0; i < 100; i++) { for (var i = 0; i < 100; i++) {
java.lang.Thread.sleep(100); java.lang.Thread.sleep(100);
} }
} # => Rhino::ScriptTimeoutError } # => Rhino::ScriptTimeoutError
end end
```
==== Different ways of loading JavaScript source ### Loading JavaScript source
In addition to just evaluating strings, you can also use streams such as files. In addition to just evaluating strings, you can also use streams such as files:
# evaluate bytes read from any File/IO object: * evaluate bytes read from any File/IO object:
```ruby
File.open("mysource.js") do |file| File.open("mysource.js") do |file|
eval_js file, "mysource.js" eval_js file, "mysource.js"
end end
```
# or load it by filename * or load it by filename:
```ruby
Rhino::Context.open do |context| Rhino::Context.open do |context|
context.load("mysource.js") context.load("mysource.js")
end end
```
==== Configurable Ruby access ### Configurable Ruby access
By default accessing Ruby objects from JavaScript is compatible with *therubyracer*: By default accessing Ruby objects from JavaScript is compatible with *therubyracer*:
https://github.com/cowboyd/therubyracer/wiki/Accessing-Ruby-Objects-From-JavaScript https://github.com/cowboyd/therubyracer/wiki/Accessing-Ruby-Objects-From-JavaScript
Thus you end-up calling arbitrary no-arg methods as if they were JavaScript properties, Thus you end-up calling arbitrary no-arg methods as if they were JavaScript properties,
since instance accessors (properties) and methods (functions) are indistinguishable: since instance accessors (properties) and methods (functions) are indistinguishable:
```ruby
Rhino::Context.open do |context| Rhino::Context.open do |context|
context['Time'] = Time context['Time'] = Time
context.eval('Time.now') context.eval('Time.now')
end end
```
However, you can customize this behavior and there's another access implementation However, you can customize this behavior and there's another access implementation
that attempts to mirror only attributes as properties as close as possible: that attempts to mirror only attributes as properties as close as possible:
```ruby
class Foo class Foo
attr_accessor :bar attr_accessor :bar
def initialize def initialize
@bar = "bar" @bar = "bar"
end end
def check_bar def check_bar
bar == "bar" bar == "bar"
end end
end end
Rhino::Ruby::Scriptable.access = :attribute Rhino::Ruby::Scriptable.access = :attribute
Rhino::Context.open do |context| Rhino::Context.open do |context|
context['Foo'] = Foo context['Foo'] = Foo
@ -140,21 +164,23 @@ that attempts to mirror only attributes as properties as close as possible:
context.eval('foo.bar = null') # set property using writer context.eval('foo.bar = null') # set property using writer
context.eval('foo.check_bar()') # called like a function context.eval('foo.check_bar()') # called like a function
end end
```
If you happen to come up with your own access strategy, just set it directly : If you happen to come up with your own access strategy, just set it directly :
```ruby
Rhino::Ruby::Scriptable.access = FooApp::BarAccess.instance Rhino::Ruby::Scriptable.access = FooApp::BarAccess.instance
```
=== Safe by default ## Safe by default
The Ruby Rhino is designed to let you evaluate JavaScript as safely as possible The Ruby Rhino 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 unless you tell it to do something more dangerous. The default context is a
hermetically sealed JavaScript environment with only the standard objects and hermetically sealed JavaScript environment with only the standard objects and
functions. Nothing from the Ruby world is accessible at all. functions. Nothing from the Ruby world is accessible.
For Ruby objects that you explicitly embed into JavaScript, only the +public+ For Ruby objects that you explicitly embed into JavaScript, only the +public+
methods "defined in their classes" are exposed by default e.g. methods "defined in their classes" are exposed by default e.g.
```ruby
class A class A
def a def a
"a" "a"
@ -175,56 +201,51 @@ methods "defined in their classes" are exposed by default e.g.
cxt.eval("b.b()") # => 'b' cxt.eval("b.b()") # => 'b'
cxt.eval("b.a()") # => 'TypeError: undefined property 'a' is not a function' cxt.eval("b.a()") # => 'TypeError: undefined property 'a' is not a function'
end end
```
==== Using a custom Rhino version
Officially supported versions of Rhino's _js.jar_ are packaged separately as ## Context Customizations
*therubyrhino_jar* gem. Make sure you're using the latest gem version if you
feel like missing something available with Rhino. For experimenters the jar can
be overriden by defining a +Rhino::JAR_PATH+ before +require 'rhino'+ e.g. :
module Rhino
JAR_PATH = File.expand_path('lib/rhino/build/rhino1_7R5pre/js.jar')
end
# ...
require 'rhino'
==== Context customizations
Just like the JVM packaged Rhino scripting engine, therubyrhino gem supports Just like the JVM packaged Rhino scripting engine, therubyrhino gem supports
specifying JavaScript context properies (optimization level and language version) specifying JavaScript context properies (optimization level and language version)
using system properties e.g. to force interpreted mode : using system properties e.g. to force interpreted mode :
jruby -J-Drhino.opt.level=-1 -rtherubyrhino -S ... `jruby -J-Drhino.opt.level=-1 -rtherubyrhino -S ...`
You might also set these programatically as a default for all created contexts : You might also set these programatically as a default for all created contexts :
```ruby
Rhino::Context.default_optimization_level = 1 Rhino::Context.default_optimization_level = 1
Rhino::Context.default_javascript_version = 1.6 Rhino::Context.default_javascript_version = 1.6
```
Or using plain old JAVA_OPTS e.g. when setting JavaScript version : Or using plain old JAVA_OPTS e.g. when setting JavaScript version :
-Drhino.js.version=1.7 `-Drhino.js.version=1.7`
== Rhino ## Rhino
Rhino is currently maintained at https://github.com/mozilla/rhino Rhino is currently maintained at https://github.com/mozilla/rhino
Release downloads are available at http://www.mozilla.org/rhino/download.html Release downloads are available at http://www.mozilla.org/rhino/download.html
Rhino is licensed under the MPL 1.1/GPL 2.0 license. Rhino is licensed under the MPL 1.1/GPL 2.0 license.
== REQUIREMENTS: ### Using a custom Rhino version
* JRuby >= 1.6 Officially supported versions of Rhino's _js.jar_ are packaged separately as
**therubyrhino_jar** gem. Make sure you're using the latest gem version if you
feel like missing something available with Rhino. For experimenters the jar can
be overriden by defining a `Rhino::JAR_PATH` before `require 'rhino'` e.g. :
```ruby
module Rhino
JAR_PATH = File.expand_path('lib/rhino/build/rhino1_7R5pre/js.jar')
end
# ...
require 'rhino'
```
== INSTALL: ## LICENSE:
* jruby -S gem install therubyrhino
== LICENSE:
(The MIT License) (The MIT License)
Copyright (c) 2009-2012 Charles Lowell Copyright (c) 2009-2013 Charles Lowell
Permission is hereby granted, free of charge, to any person obtaining Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the a copy of this software and associated documentation files (the
@ -243,4 +264,4 @@ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

8
therubyrhino.gemspec
View file

@ -7,19 +7,19 @@ Gem::Specification.new do |s|
s.version = Rhino::VERSION s.version = Rhino::VERSION
s.authors = ["Charles Lowell"] s.authors = ["Charles Lowell"]
s.email = %q{cowboyd@thefrontside.net} s.email = %q{cowboyd@thefrontside.net}
s.summary = %q{Embed the Rhino JavaScript interpreter into JRuby} s.summary = %q{Embed the Rhino JavaScript interpreter into JRuby}
s.description = %q{Call javascript code and manipulate javascript objects from ruby. Call ruby code and manipulate ruby objects from javascript.} s.description = %q{Call javascript code and manipulate javascript objects from ruby. Call ruby code and manipulate ruby objects from javascript.}
s.homepage = %q{http://github.com/cowboyd/therubyrhino} s.homepage = %q{http://github.com/cowboyd/therubyrhino}
s.rubyforge_project = %q{therubyrhino} s.rubyforge_project = %q{therubyrhino}
s.extra_rdoc_files = ["README.rdoc"] s.extra_rdoc_files = ["README.md"]
s.require_paths = ["lib"] s.require_paths = ["lib"]
s.files = `git ls-files`.split("\n").sort. s.files = `git ls-files`.split("\n").sort.
reject { |file| file == 'therubyrhino_jar.gemspec' || file =~ /^jar\// } reject { |file| file == 'therubyrhino_jar.gemspec' || file =~ /^jar\// }
s.add_dependency "therubyrhino_jar", '>= 1.7.3' s.add_dependency "therubyrhino_jar", '>= 1.7.3'
s.add_development_dependency "rspec", "~> 2.13.0" s.add_development_dependency "rspec", "~> 2.13.0"
s.add_development_dependency "mocha", "~> 0.13.3" s.add_development_dependency "mocha", "~> 0.13.3"
end end