mirror of
https://github.com/rubyjs/therubyrhino
synced 2023-03-27 23:21:34 -04:00
markdown-ize README/History
This commit is contained in:
kares
parent
ba9006baf2
commit
b169814ed9
3 changed files with 137 additions and 105 deletions
|
|
@ -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)
|
||||
* correct explicit Ruby equality == and eql? (JRuby 1.7.1 compat)
|
||||
* allow to set javascript version programatically - globally also allow
|
||||
reading it from system properties by default
|
||||
* allow to set optimization level globally also allow reading it from
|
||||
system properties by default
|
||||
* make sure Ruby function wrapper has (Ruby) #call semantics just like
|
||||
* allow to set optimization level globally also allow reading it from
|
||||
system properties by default
|
||||
* make sure Ruby function wrapper has (Ruby) #call semantics just like
|
||||
JavaScript functions exposed into the Ruby side
|
||||
* 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
|
||||
* jar-1.7.4 regression fix e.g when loading less (#25)
|
||||
* 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:
|
||||
https://developer.mozilla.org/en/New_in_Rhino_1.7R4
|
||||
|
||||
=== 2.0.0 2012-08-02
|
||||
This release is functionally the same as therubyrhino-1.73.5 as long
|
||||
## 2.0.0 2012-08-02
|
||||
|
||||
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.
|
||||
|
||||
* new versioning scheme - old scheme used for the 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
|
||||
|
||||
|
||||
=== 1.73.5 2012-07-25
|
||||
## 1.73.5 2012-07-25
|
||||
|
||||
* #to_s functionName typo fix for org.mozilla.javascript.ScriptStackElement
|
||||
* make sure thrown values are correctly raised from inside JS functions
|
||||
* a better #inspect for native rhino objects
|
||||
* 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
|
||||
* '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
|
||||
* make sure JSError#cause always points to native rhino cause (#19)
|
||||
* 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
|
||||
|
||||
* 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
|
||||
* 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
|
||||
|
||||
* 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)
|
||||
* 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
|
||||
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
|
||||
* 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
|
||||
* cache objects passed to context - same object passed twice ends up the same
|
||||
* properly map ruby Time objects to javascript Date
|
||||
* jruby --1.9 improvements
|
||||
|
||||
=== 1.72.8 2011-06-26
|
||||
## 1.72.8 2011-06-26
|
||||
|
||||
* fix passing of options hash to ruby.
|
||||
|
||||
=== 1.72.6 2009-11-30
|
||||
## 1.72.6 2009-11-30
|
||||
|
||||
* 2 major enhancements:
|
||||
* evaluate an IO object such as a file or an socket input stream
|
||||
* 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:
|
||||
* 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
|
||||
|
||||
=== 1.72.4 2009-11-12
|
||||
## 1.72.4 2009-11-12
|
||||
|
||||
* 3 major enhancements:
|
||||
* automatically wrap/unwrap ruby and javascript arrays
|
||||
* automatically convert ruby method objects and Proc objects into javascript functions
|
||||
* Make functions defined in javascript callable from ruby
|
||||
|
||||
=== 1.72.3 2009-11-11
|
||||
## 1.72.3 2009-11-11
|
||||
|
||||
* 4 major enhancements:
|
||||
* greatly simplified interface to context by unifying context and scope
|
||||
* remove Context#open_std()
|
||||
* remove Context#standard
|
||||
* remove Context#init_standard_objects
|
||||
|
||||
=== 1.72.2 2009-11-10
|
||||
## 1.72.2 2009-11-10
|
||||
|
||||
* 1 major enhancement:
|
||||
* ability to limit the instruction count for a context
|
||||
|
||||
=== 1.72.1 2009-11-09
|
||||
## 1.72.1 2009-11-09
|
||||
|
||||
* 4 major enhancements:
|
||||
* easily manipulate javascript objects from ruby (NativeObject)
|
||||
* make NativeObject Enumerable
|
||||
* to_h and to_json for NativeObject
|
||||
* embed ruby instances and call methods from javascript
|
||||
|
||||
=== 1.72.0 2009-09-24
|
||||
## 1.72.0 2009-09-24
|
||||
|
||||
* 2 major enhancements:
|
||||
* evaluate javascript in jruby
|
||||
|
|
@ -1,44 +1,54 @@
|
|||
= therubyrhino
|
||||
|
||||
* http://github.com/cowboyd/therubyrhino
|
||||
* irc://irc.freenode.net/therubyrhino
|
||||
|
||||
== DESCRIPTION:
|
||||
# therubyrhino
|
||||
|
||||
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
|
||||
* Embed your Ruby objects into the JavaScript world
|
||||
|
||||
== SYNOPSIS:
|
||||
## SYNOPSIS:
|
||||
|
||||
1. JavaScript goes into Ruby
|
||||
2. Ruby Objects goes into JavaScript
|
||||
3. Our shark's in the JavaScript!
|
||||
|
||||
```ruby
|
||||
require 'rhino'
|
||||
|
||||
# evaluate some simple javascript
|
||||
eval_js "7 * 6" #=> 42
|
||||
```
|
||||
|
||||
# that's quick and dirty, but if you want more control over your
|
||||
# environment, use a Context:
|
||||
* evaluate some simple JavaScript using `eval_js`:
|
||||
```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|
|
||||
cxt['foo'] = "bar"
|
||||
cxt.eval('foo') # => "bar"
|
||||
end
|
||||
```
|
||||
|
||||
# evaluate a ruby function from JS
|
||||
|
||||
* evaluate a Ruby function from JavaScript:
|
||||
```ruby
|
||||
Rhino::Context.open do |context|
|
||||
context["say"] = lambda {|word, times| word * times}
|
||||
context.eval("say("Hello", 3)") #=> HelloHelloHello
|
||||
end
|
||||
|
||||
# embed a ruby object into your JS environment
|
||||
```
|
||||
|
||||
* embed a Ruby object into your JavaScript environment
|
||||
```ruby
|
||||
class MyMath
|
||||
def plus(lhs, rhs)
|
||||
lhs + rhs
|
||||
|
|
@ -49,89 +59,103 @@ Embed the Mozilla Rhino JavaScript interpreter into Ruby
|
|||
context["math"] = MyMath.new
|
||||
context.eval("math.plus(20, 22)") #=> 42
|
||||
end
|
||||
|
||||
# make a ruby object *be* your JS environment
|
||||
```
|
||||
|
||||
* make a Ruby object *be* your JavaScript environment
|
||||
```ruby
|
||||
math = MyMath.new
|
||||
Rhino::Context.open(:with => math) do |context|
|
||||
context.eval("plus(20, 22)") #=> 42
|
||||
end
|
||||
|
||||
#or the equivalent
|
||||
|
||||
|
||||
# or the equivalent
|
||||
|
||||
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|
|
||||
context.eval("Object.prototype.toString = function() {}") # this is an error!
|
||||
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|
|
||||
context.eval("java.lang.System.exit()") # it's dangerous!
|
||||
end
|
||||
```
|
||||
|
||||
#limit the number of instructions that can be executed in order to prevent
|
||||
#rogue scripts
|
||||
* limit the number of instructions that can be executed to prevent rogue code:
|
||||
```ruby
|
||||
Rhino::Context.open(:restrictable => true) do |context|
|
||||
context.instruction_limit = 100000
|
||||
context.eval("while (true);") # => Rhino::RunawayScriptError
|
||||
end
|
||||
```
|
||||
|
||||
#limit the time a script executes
|
||||
#rogue scripts
|
||||
* limit the time a script executes (rogue scripts):
|
||||
```ruby
|
||||
Rhino::Context.open(:restrictable => true, :java => true) do |context|
|
||||
context.timeout_limit = 1.5 # seconds
|
||||
context.eval %Q{
|
||||
context.eval %Q{
|
||||
for (var i = 0; i < 100; i++) {
|
||||
java.lang.Thread.sleep(100);
|
||||
}
|
||||
} # => Rhino::ScriptTimeoutError
|
||||
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|
|
||||
eval_js file, "mysource.js"
|
||||
end
|
||||
```
|
||||
|
||||
# or load it by filename
|
||||
* or load it by filename:
|
||||
```ruby
|
||||
Rhino::Context.open do |context|
|
||||
context.load("mysource.js")
|
||||
end
|
||||
```
|
||||
|
||||
==== Configurable Ruby access
|
||||
### Configurable Ruby access
|
||||
|
||||
By default accessing Ruby objects from JavaScript is compatible with *therubyracer*:
|
||||
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:
|
||||
|
||||
```ruby
|
||||
Rhino::Context.open do |context|
|
||||
context['Time'] = Time
|
||||
context.eval('Time.now')
|
||||
end
|
||||
```
|
||||
|
||||
However, you can customize this behavior and there's another access implementation
|
||||
that attempts to mirror only attributes as properties as close as possible:
|
||||
|
||||
```ruby
|
||||
class Foo
|
||||
attr_accessor :bar
|
||||
|
||||
|
||||
def initialize
|
||||
@bar = "bar"
|
||||
end
|
||||
|
||||
|
||||
def check_bar
|
||||
bar == "bar"
|
||||
end
|
||||
end
|
||||
|
||||
|
||||
Rhino::Ruby::Scriptable.access = :attribute
|
||||
Rhino::Context.open do |context|
|
||||
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.check_bar()') # called like a function
|
||||
end
|
||||
```
|
||||
|
||||
If you happen to come up with your own access strategy, just set it directly :
|
||||
|
||||
```ruby
|
||||
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
|
||||
unless you tell it to do something more dangerous. The default context is a
|
||||
hermetically sealed JavaScript environment with only the standard objects and
|
||||
functions. Nothing from the Ruby world is accessible at all.
|
||||
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
|
||||
hermetically sealed JavaScript environment with only the standard objects and
|
||||
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.
|
||||
|
||||
```ruby
|
||||
class A
|
||||
def 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.a()") # => 'TypeError: undefined property 'a' is not a function'
|
||||
end
|
||||
|
||||
==== Using a custom Rhino version
|
||||
```
|
||||
|
||||
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. :
|
||||
|
||||
module Rhino
|
||||
JAR_PATH = File.expand_path('lib/rhino/build/rhino1_7R5pre/js.jar')
|
||||
end
|
||||
# ...
|
||||
require 'rhino'
|
||||
|
||||
==== Context customizations
|
||||
## Context Customizations
|
||||
|
||||
Just like the JVM packaged Rhino scripting engine, therubyrhino gem supports
|
||||
specifying JavaScript context properies (optimization level and language version)
|
||||
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 :
|
||||
|
||||
```ruby
|
||||
Rhino::Context.default_optimization_level = 1
|
||||
Rhino::Context.default_javascript_version = 1.6
|
||||
```
|
||||
|
||||
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
|
||||
Release downloads are available at http://www.mozilla.org/rhino/download.html
|
||||
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:
|
||||
|
||||
* jruby -S gem install therubyrhino
|
||||
|
||||
== LICENSE:
|
||||
## 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
|
||||
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
|
||||
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.
|
||||
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
|
@ -7,19 +7,19 @@ Gem::Specification.new do |s|
|
|||
s.version = Rhino::VERSION
|
||||
s.authors = ["Charles Lowell"]
|
||||
s.email = %q{cowboyd@thefrontside.net}
|
||||
|
||||
|
||||
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.homepage = %q{http://github.com/cowboyd/therubyrhino}
|
||||
s.rubyforge_project = %q{therubyrhino}
|
||||
s.extra_rdoc_files = ["README.rdoc"]
|
||||
|
||||
s.extra_rdoc_files = ["README.md"]
|
||||
|
||||
s.require_paths = ["lib"]
|
||||
s.files = `git ls-files`.split("\n").sort.
|
||||
reject { |file| file == 'therubyrhino_jar.gemspec' || file =~ /^jar\// }
|
||||
|
||||
s.add_dependency "therubyrhino_jar", '>= 1.7.3'
|
||||
|
||||
|
||||
s.add_development_dependency "rspec", "~> 2.13.0"
|
||||
s.add_development_dependency "mocha", "~> 0.13.3"
|
||||
end
|
||||
|
|
|
|||
Loading…
Reference in a new issue