jscall 1.0.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97c7ab8cd5d710cfca8c77f6e906643252b9c54cc5973709763b89aef3830dee
-  data.tar.gz: e205fad16cc87df640b186ac99190186374f2db821a7e3d499563add9016b097
+  metadata.gz: dad6ca4017b93ba7f1675b3d1e3727a143d5e413f86d9f000966f7eae9306d06
+  data.tar.gz: e50ef13d47441f195194e4a36886b506266f87339f9d7bbf7f5b9d79dc500814
 SHA512:
-  metadata.gz: f25ebf232e77432bb5c79f511c4fc99de78e2d7861e4d3831edcf3662e747021d5d4a207036c8a7add2fe1822c9fb8fdb7439b1e17e67627abea090c1285662c
-  data.tar.gz: 8e02fe7a9f3d7f0d82ac70f24d33335c2dffe1261133e2dec4a1c4ff65ec9b87bb9fad8f0049dee3fb681c20e7b3f47d9a97890b45958199f1e78c0b76fd69b5
+  metadata.gz: 16a7885d6e0e5ef993a9f8ea43a6dc2bcfe78624f20cd10517642c00f59525b1edab1a91ab99367f962d3f63ba5a5c6705bf7cad915673613fb9ee805358baeb
+  data.tar.gz: 1f7d95224652882839fd9bce1d4fd539021980018ecc1cca73aed56e598a2c034b8800cdfb88cc6ffd4b09f6488867e33335e8180f7e5e81aa29663ebdc6a5d4

data/README.md

@@ -1,5 +1,7 @@
 # Jscall
 
+[![Ruby](https://github.com/csg-tokyo/jscall/actions/workflows/ruby.yml/badge.svg)](https://github.com/csg-tokyo/jscall/actions/workflows/ruby.yml)
+
 Jscall allows executing a program in JavaScript on node.js or a web browser.
 By default, node.js is used for the execution.
 To choose a web browser, call `Jscall.config`.
@@ -16,13 +18,17 @@ Jscall.exec '1 + 1'
 ```
 
 This returns `2`.  The argument passed to `Jscall.exec` can be
-multipe lines.  It is executed as source code written in JavaScript.
+multiple lines.  It is executed as source code written in JavaScript.
 
 `Jscall.exec` returns a resulting value.  Numbers, character strings (and symbols), boolean values, and `nil` (and `null`)
-are copied when passing between Ruby and JavaScript.  An array is also shallow-copied.
+are copied when passing between Ruby and JavaScript.  An array is shallow-copied.
 Other objects are not copied.  When they are passed, a remote reference is created at the destination.
+When a `Map` object is returned from JavaScript to Ruby, it is also
+shallow-copied but into a `Hash` object in Ruby.
 
-A remote reference is a proxy object.  A method call on a remote reference invokes a method on the corresponding object on the remote site.  For example,
+A remote reference is a local reference to a proxy object.
+A method call on a remote reference invokes a method on the corresponding
+object on the remote site.  For example,
 
 ```
 js_obj = Jscall.exec '({ foo: (x) => x + 1, bar: 7 })'
@@ -35,11 +41,30 @@ js_obj.baz       # 9
 The `foo` method is executed in JavaScript.
 Since `bar` is not a function, its value is returned to Ruby as it is.
 
-Setting a object property to a given value is also
+Setting an object property to a given value is also
 allowed.  The expression `js_obj.baz = 9` above sets
 the object property `baz` to 9.
 
-To call a JavaScript function from Ruby, call a mehtod on `Jscall`.
+An argument to a JavaScript method is copied from Ruby to
+JavaScript unless it is an object.  When an argument is a Ruby object,
+a proxy object is created in JavaScript.  The rule is the same as the
+rule for returning a value from JavaScript to Ruby.  A primitive
+value is copied but an object is not.  An array is shallow-copied.
+
+A `Hash` object in Ruby is also shallow-copied into JavaScript but a normal
+object is created in JavaScript.  Recall that a JavaScript object is
+regarded as an associative array, or a hash table as in Ruby.
+For example, in Ruby,
+
+```
+obj = { a: 2, b: 3 }
+```
+
+when this ruby object is passed to JavaScript as an argument,
+a normal object `{ a: 2, b: 3 }` is created as its copy in JavaScript
+and passed to a JavaScript method.
+
+To call a JavaScript function from Ruby, call a method on `Jscall`.
 For example,
 
 ```
@@ -54,9 +79,22 @@ Jscall.foo(7)    # 8
 `Jscall.foo(7)` invokes the JavaScript function with the name following `Jscall.`
 with the given argument.  In this case,
 the `foo` function is executed with the argument `7`.
+Arguments and a return value are passed to/from a function
+as they are passed to/from a method.
+
+`Jscall` can be used for obtaining a remote reference to access a global variable
+in JavaScript.  For example,
+
+```
+Jscall.console.log('Hello')
+```
+
+This prints `Hello` on a JavaScript console.  `Jscall.console` returns a remote
+reference to the value of `console` in JavaScript.  Then, `.log('Hello')`
+calls the `log` method on `console` in JavaScript.
 
 When a Ruby object is passed to a JavaScript function/method,
-it can call a method on the passed Ruby object.
+you can call a method on the passed Ruby object.
 
 ```
 Jscall.exec <<CODE
@@ -72,7 +110,7 @@ created in Ruby.
 Note that you must `await` every call to Ruby object since it is
 asynchronous call.
 
-In JavaScript, `Ruby.exec` is availale to run a program in Ruby.
+In JavaScript, `Ruby.exec` is available to run a program in Ruby.
 For example,
 
 ```
@@ -84,10 +122,19 @@ CODE
 Jscall.foo()
 ```
 
-`Jscall.foo()` returns the result of evaluating `RUBY_VERSION`
-in Ruby.
+`Jscall.foo()` returns the result of evaluating given Ruby code
+`RUBY_VERSION` in Ruby.
 Don't forget to `await` a call to `Ruby.exec`.
 
+### Remote references
+
+A remote reference is implemented by a local reference to a proxy
+object representing the remote object that the remote reference refers to.
+When a proxy object is passed as an argument or a return value
+from Ruby to JavaScript (or vice versa), the corresponding JavaScript
+(or Ruby) object is passed to the destination.  In other words,
+a remote reference passed is converted back to a local reference.
+
 Remote references will be automatically reclaimed when they are no
 longer used.  To reclaim them immediately, call:
 
@@ -95,6 +142,25 @@ longer used.  To reclaim them immediately, call:
 Jscall.scavenge_references
 ```
 
+As mentioned above, a remote reference is a local reference
+to a proxy object.  In Ruby,
+even a proxy object provides a number of methods inherited from `Object` class,
+such as `clone`, `to_s`, and `inspect`.  A call to such a method is not
+delegated to the corresponding JavaScript object.  To invoke such a method
+on a JavaScript object, call `send` on its proxy object.
+For example,
+
+```
+js_obj = Jscall.exec '({ to_s: (x, y) => x + y })'
+puts js_obj.to_s(3, 4)            # error
+puts js_obj.send('to_s', 3, 4)    # 7
+```
+
+The `send` method invokes the JavaScript method with the name specified
+by the first argument.  The remaining arguments passed to `send` are passed
+to that JavaScript method.
+
+
 ## DOM manipulation
 
 When JavaScript code is run on a browser, some utility methods
@@ -109,7 +175,16 @@ links `mystyle.css` in the current directory.
 - `Jscall.dom.print(msg)`
 
 This adds a `p` element to the DOM tree.
+Its inner text is the character string passed as `msg`.
 
+- `Jscall.dom.append_to_body(html_source)`
+
+This inserts the given `html_source` at the end of the `body` element.
+It is a shorthand for
+
+```
+Jscall.document.body.insertAdjacentHTML('beforeend', html_source)
+```
 
 ## Variable scope
 
@@ -142,16 +217,33 @@ for loading a CommonJS module.  For example,
 Jscall.exec "mime = require('./mime.js')"
 ```
 
-The file `./mime.js` is loaded and the module is bound to a global variable `mime`.
+The file `./mime.js` is loaded and the module is bound to a global variable `mime` in JavaScript.
 
-You may want to call `Jscall.dyn_import` in Ruby.
+You can directly call `require` on `Jscall` in Ruby.
+
+```
+parser = Jscall.require("@babel/parser")
+ast = parser.parse('const i = 3')
+Jscall.console.log(ast)
+```
+
+`require` will search `./node_modules/` for `@babel/parser`.
+This is equivalent to the following JavaScript code.
+
+```
+parser = require("@babel/parser")
+ast = parser.parse('const i = 3')
+console.log(ast)
+```
+
+Dynamic importing is also available.  Call `Jscall.dyn_import` in Ruby.
 
 ```
 fs = Jscall.dyn_import('fs')
 ```
 
 This executes dynamic importing in JavaScript.
-For node.js, the file name of the imported module should be a full path name.  For a web browser, the root directory is a current working directory.  So `Jscall.dyn_import('/mine.mjs')` loads the file `./mine.mjs`.
+For node.js, the file name of the imported module should be a full path name.  For a web browser, the root directory is the current working directory.  So `Jscall.dyn_import('/mine.mjs')` loads the file `./mine.mjs`.
 
 `Jscall.dyn_import` takes the second argument.  If it is given,
 a global variable in JavaScript is bound to the loaded module.
@@ -166,49 +258,147 @@ This is quite equivalent to the following JavaScript code:
 fs_module = await load('fs')
 ```
 
+## Promise
+
+If a program attempts to pass a `Promise` object from JavaScript to Ruby,
+it waits until the promise is fulfilled.  Then Jscall passes
+the value of that promise from JavaScript to Ruby instead of that
+promise itself (or a remote reference to that promise).  When that promise
+is rejected, an error object is passed to Ruby
+so that the error will be raised in Ruby.
+This design reflects the fact that an `async` function in JavaScript
+also returns a `Promise` object but this object must not be returned
+to Ruby as is when that `async` function is called from Ruby.
+Jscall cannot determine whether a promise should be passed as is to Ruby
+or its value must be passed to Ruby after the promise is fulfilled.
+
+When enforcing Jscall to pass a `Promise` object from JavaScript to Ruby,
+`.async` must be inserted between a receiver and a method name.
+
+```
+Jscall.exec(<<CODE)
+  function make_promise() {
+    return { a: Promise.resolve(7) }
+  }
+CODE
+
+obj = Jscall.make_promise
+result = obj.a                # 7
+prom = obj.async.a            # promise
+prom.then(->(r) { puts r })   # 7
+```
+
+## Synchronous calls
+
+You might want to avoid writing `await` when you call a method on a Ruby
+object or you execute Ruby code by `Ruby.exec` from JavaScript.
+For example, that call is included in library code and you might not
+be able to modify the library code so that `await` will be inserted.
+
+Jscall supports synchronous calls from JavaScript to Ruby only when
+the underlying JavaScript engine is node.js on Linux.
+In the mode of synchronous calls, you do not have to `await` a method call
+on a Ruby object or a call to `Ruby.exec`.
+It blocks until the return value comes back from Ruby.
+While it blocks, all calls from Ruby to JavaScript are
+synchronously processed.
+
+To change to the mode of synchronous calls,
+call `Jscall.config`:
+
+```
+Jscall.config(sync: true)
+```
 
 ## Configuration
 
-To import JavaScript modules when node.js starts,
+Jscall supports several configuration options.
+Call `Jscall.config` with necessary options.
+
+### module_names:
+
+To import JavaScript modules when node.js or a web browser starts,
 
 ```
-Jscall.config(module_names: [["Foo", "./foo.mjs"], ["Bar", "./bar.mjs"]], options: "--use-strict")
+Jscall.config(module_names: [["Foo", "./js", "/lib/foo.mjs"], ["Bar", "./js", "/lib/bar.mjs"]])
 ```
 
-This specifies that `./foo.mjs` and `./bar.mjs` are impoted when node.js starts.
+This specifies that `./js/lib/foo.mjs` and `./js/lib/bar.mjs` are imported
+at the beginning.
 This is equivalent to the following import declarations:
 
 ```
-import * as "Foo" from "./foo.mjs"
-import * as "Bar" from "./bar.mjs"
+import * as "Foo" from "./js/lib/foo.mjs"
+import * as "Bar" from "./js/lib/bar.mjs"
 ```
 
-`'--use-strict'` is passed to node.js as a command line argument.
+Note that each array element given to `module_names:` is
 
-`module_names:` and `options:` are optional arguments to `Jscall.config`.
+```
+[<module_name> <root> <path>]
+```
 
-To change the name of the node command,
+`<path>` must start with `/`.  It is used as a part of the URL when a browser
+accesses a module.
+When importing a module for node.js, `<root>` and `<path>` are concatenated
+to form a full path name.
+
+`<path>` must not start with `/jscall` or `/cmd`.  They are reserved for
+internal use.
+
+### options:
+
+To specify a command line argument passed to node.js,
 
 ```
-Jscall::PipeToJs.node_command = "node.exe"
+Jscall.config(options: '--use-strict')
 ```
 
-The default command name is `"node"`.
+This call specifies that
+`--use-strict` is passed as a command line argument.
+
+### browser: and port:
 
 When running JavaScript code on a web browser,
 
 ```
-Jscall.config(browser: true, options: {port: 10082})
+Jscall.config(browser: true, port: 10082)
 ```
 
-`options:` is an optional argument.
+Passing `true` for `browser:` switches the execution engine to a web browser.
+The default engine is node.js.
+To switch the engine back to node.js, pass `false` for `browser:`.
+Call `Jscall.close` to detach the current execution engine.
+A new engine with a new configuration will be created.
+
+`port:` specifies the port number of an http server.  It is optional.
 The example above specifies that Ruby receives http requests
 sent to http://localhost:10082 from JavaScript on a web browser.
 
-Passing `false` for `browser:` to `Jscall.config` switches
-the execution engine to node.js.
-Call `Jscall.close` to detach the current execution engine.
-A new enigine with a new configuration will be created.
+
+### Misc.
+
+To change to the mode of synchronous calls,
+
+```
+Jscall.config(sync: true)
+```
+
+To set all the configurations to the default ones,
+
+```
+Jscall.config()
+```
+
+### Other configurations
+
+To change the name of the node command,
+
+```
+Jscall::PipeToJs.node_command = "node.exe"
+```
+
+The default command name is `"node"`.
 
 To change the command for launching a web browser,
 
@@ -224,6 +414,12 @@ Jscall launches a web browser by the command like the following:
 open http://localhost:10082/jscall/jscall.html
 ```
 
+Jscall generates a verbose error message if its debug level is more than 0.
+
+```
+Jscall.debug = 1
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -254,7 +450,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/csg-to
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
-## Acknowledgement
+## Acknowledgment
 
 The icon image for jscall was created by partly using the Ruby logo, which was obtained
 from https://www.ruby-lang.org/en/about/logo/ under CC BY-SA 2.5.

data/examples/pdf-js.rb

@@ -0,0 +1,56 @@
+# Display a pdf file by using pdf.js
+
+require 'jscall'
+
+# Run a JavaScript program on a browser
+Jscall.config browser: true
+
+# Write HTML code on a blank web page.
+Jscall.dom.append_to_body(<<CODE)
+  <h1>PDF.js 'Hello, world!' example</h1>
+  <canvas id="the-canvas"></canvas>
+CODE
+
+# import pdf.js
+pdfjs = Jscall.dyn_import('https://mozilla.github.io/pdf.js/build/pdf.js')
+
+# A pdf file
+url = "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/examples/learning/helloworld.pdf"
+
+pdf = Jscall.exec 'window["pdfjs-dist/build/pdf"]'
+
+pdf.GlobalWorkerOptions.workerSrc = "https://mozilla.github.io/pdf.js/build/pdf.worker.js"
+
+loadingTask = pdf.getDocument(url)
+loadingTask.async.promise.then(-> (pdf) {
+    puts "PDF loaded"
+
+    # Fetch the first page
+    pageNumber = 1;
+    pdf.async.getPage(pageNumber).then(-> (page) {
+        puts "Page loaded"
+
+        scale = 1.5;
+        viewport = page.getViewport({ scale: scale })
+
+        canvas = Jscall.document.getElementById("the-canvas")
+        context = canvas.getContext("2d")
+        canvas.height = viewport.height
+        canvas.width = viewport.width
+    
+        # Render the pdf page
+        renderContext = {
+            canvasContext: context,
+            viewport: viewport,
+        }
+        renderTask = page.render(renderContext)
+        renderTask.async.promise.then(-> (r) {
+            # Print a message when the rendering succeeds.
+            puts "Page rendered #{r}"
+        })
+    })
+},
+-> (reason) {
+    # an error occurs.
+    puts reason  
+})

data/lib/jscall/browser.mjs

@@ -2,24 +2,27 @@
 
 export class HttpStream {
     constructor() {
-        this.send_buffer = ['start']
+        this.recv_buffer = []
         this.send_callback = null
+        this.fetching = null
+        this.call_queue = []
+        this.puts('start')
     }
 
     [Symbol.asyncIterator]() {
         const http_stream = this
         return {
             next() {
-                let msg = http_stream.send_buffer.shift()
-                if (msg === undefined)
+                let next_data = http_stream.recv_buffer.shift()
+                if (next_data === undefined)
                     return new Promise((resolve, reject) => {
                         if (http_stream.send_callback === null)
                             http_stream.send_callback = resolve
                         else
                             throw new Error('(fatal) send_callback is not null!')
-                    }).then(() => this.next())
+                    })
                 else
-                    return http_stream.do_fetch(msg)
+                    return next_data
             }
         }
     }
@@ -40,12 +43,30 @@ export class HttpStream {
     }
 
     puts(msg) {
-        this.send_buffer.push(msg)
-        if (this.send_callback !== null) {
-            const callback = this.send_callback
-            this.send_callback = null
-            callback()
-        }
+        if (this.fetching === null)
+            this.fetching = this.puts0(msg)
+        else
+            this.call_queue.push(msg)
+    }
+
+    puts0(msg) {
+        return this.do_fetch(msg)
+                .then((data) => {
+                    if (this.send_callback === null)
+                        this.recv_buffer.push(data)
+                    else {
+                        const callback = this.send_callback
+                        this.send_callback = null
+                        callback(data)
+                    }
+
+                    if (this.call_queue.length > 0) {
+                        const msg2 = this.call_queue.shift()
+                        this.fetching = this.puts0(msg2)
+                    }
+                    else
+                        this.fetching = null
+                })
     }
 
     setEncoding(encoding) {}
@@ -64,4 +85,8 @@ export const Jscall = new class {
         link.href = file_name
         document.head.append(link)
     }
+
+    append_to_body(html_source) {
+        document.body.insertAdjacentHTML('beforeend', html_source)
+    }
 }

data/lib/jscall/browser.rb

@@ -8,6 +8,7 @@ module Jscall
     WEBrick::HTTPUtils::DefaultMimeTypes['mjs'] ||= "application/javascript"
 
     class Dom
+        # see Jscall class in browser.mjs
         def method_missing(name, *args)
             Jscall.__getpipe__.funcall(nil, "Jscall.#{name}", args)
         end
@@ -23,13 +24,27 @@ module Jscall
     end
 
     class PipeToBrowser < PipeToJs
-        def startJS(module_names, options)
-            port = 10081
-            port = options[:port] if options.is_a?(Hash) && options.has_key?(:port)
-            @pipe = FetchServer.new(port)
+        def startJS(module_names, config)
+            urls = {}
+            module_names.each_index do |i|
+                mod = module_names[i]
+                urls[mod[2]] = mod
+            end
+            port = config[:port] || 10081
+            @pipe = FetchServer.new(port, urls)
             @pipe.open
         end
 
+        def setup(config)
+            if config[:browser]
+                module_names = config[:module_names] || []
+                module_names.each_index do |i|
+                    mod = module_names[i]
+                    Jscall.dyn_import(mod[2], mod[0])
+                end
+            end
+        end
+
         def close
             @pipe.shutdown
             sleep(0.5)
@@ -58,7 +73,8 @@ module Jscall
             @@run_cmd = name
         end
 
-        def initialize(port)
+        def initialize(port, urls)
+            @url_map = urls
             @send_buffer = Thread::Queue.new
             @receive_buffer = Thread::Queue.new
             @server_running = false
@@ -96,10 +112,16 @@ module Jscall
         end
 
         def read_file(req, res)
-            if req.path.start_with?('/jscall/')
+            path = req.path
+            if path.start_with?('/jscall/')
                 root = "#{__dir__}/../"
             else
-                root = @server.config[:DocumentRoot]
+                value = @url_map[path]
+                if value.nil?
+                    root = @server.config[:DocumentRoot]
+                else
+                    root = value[1]
+                end
             end
             WEBrick::HTTPServlet::FileHandler.new(@server, root).service(req, res)
         end