markdown-ize README/History

History.md

@@ -1,4 +1,4 @@
-=== 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)
@@ -10,37 +10,38 @@
   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
+## 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
@@ -49,7 +50,8 @@ as the therubyrhino_jar-1.7.3 gem dependency is used along with it.
 * 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

README.md

@@ -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
+* 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:
+* 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,38 +59,46 @@ 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{
@@ -89,37 +107,43 @@ Embed the Mozilla Rhino JavaScript interpreter into Ruby
         }
     } # => 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,
 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
 
@@ -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.
+functions. Nothing from the Ruby world is accessible.
 
 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

therubyrhino.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |s|
   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.