jscall 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5fb1072aa12a5e884d9c92537f6ae7a5c632d4940715008865ec9760940f1c2
-  data.tar.gz: 597c3199f5ee21f98d80a42b05bf9822b729a22311d7c9f43e2cf45d54594983
+  metadata.gz: 1df05fa2e6cee8575b7cdf9a95d35c264422d66c1c793f71e620462380a891bc
+  data.tar.gz: 4bae39ef37ec190d8c6b87fb4541c0ec4f074b7c5b09eeecc1d92a4a47dd570c
 SHA512:
-  metadata.gz: 54c16c0015f2296309523ecf5d966bbf2071303136afef04e0bbdf139aa204c4b3db332a73ea65c0194fce7cea795503db17577805b4110a56edda796fca0a0b
-  data.tar.gz: ada3a68d6c19093c22087982e520ed18a0f3f3709584fc2c30978aed7909c1b6b8568eb48e24fde6c57cc759dc235b1a824524b1c0d43053d4d80512767339a8
+  metadata.gz: 16c12783ff80fefb85e4453ca09b54faf4b614895157f4e57108379a51ef0ebbacc2fb38ddff7d87faef50a5c3880a6690cfeb03dc5e5d67be447e36236475af
+  data.tar.gz: a5b57ae8e5d7d891648d457ed32f481ea1b0d528d973e693e164f5053e39f6bfce235148fc22990a53e52e5d7ceaa5eb91dc3297b4b89b8a7af90aa47b88ff54

data/README.md

@@ -18,7 +18,7 @@ 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 shallow-copied.
@@ -64,7 +64,7 @@ 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 mehtod on `Jscall`.
+To call a JavaScript function from Ruby, call a method on `Jscall`.
 For example,
 
 ```
@@ -90,7 +90,7 @@ Jscall.console.log('Hello')
 ```
 
 This prints `Hello` on a JavaScript console.  `Jscall.console` returns a remote
-refererence to the value of `console` in JavaScript.  Then, `.log('Hello')`
+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,
@@ -110,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,
 
 ```
@@ -261,7 +261,7 @@ 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 fullfilled.  Then Jscall passes
+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
@@ -270,7 +270,7 @@ 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 fullfilled.
+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.
@@ -288,6 +288,27 @@ 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
 
@@ -348,15 +369,45 @@ 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 enigine with a new configuration will be created.
+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.
 
 
+### 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 obtain more detailed error messages,
+set a debugging level to 10.
+In Ruby,
+
+```
+Jscall.debug = 10
+```
+
+In JavaScript,
+
+```
+Ruby.setDebugLevel(10)
+```
+
+The default debugging level is 0.
+
 To change the name of the node command,
 
 ```
@@ -415,7 +466,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/Rakefile

@@ -6,7 +6,11 @@ require "rake/testtask"
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["test/**/test_*.rb"]
+  files = FileList["test/**/test_*.rb"]
+  unless /linux/ =~ RbConfig::CONFIG['host_os']
+    files.exclude "test/test_sync_io.rb"
+  end
+  t.test_files = files
 end
 
 task default: :test

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/main.mjs

@@ -1,12 +1,19 @@
 // Copyright (C) 2022- Shigeru Chiba.  All rights reserved.
 
-const cmd_eval = 1
-const cmd_call = 2
-const cmd_reply = 3
-const cmd_async_call = 4
-const cmd_async_eval = 5
-const cmd_retry = 6
-const cmd_reject = 7
+let debug_level = 0
+
+// debug level is 0 (default) or 10.
+export const setDebugLevel = d => {
+    debug_level = d
+}
+
+export const cmd_eval = 1
+export const cmd_call = 2
+export const cmd_reply = 3
+export const cmd_async_call = 4
+export const cmd_async_eval = 5
+export const cmd_retry = 6
+export const cmd_reject = 7
 
 const param_array = 0
 const param_object = 1
@@ -185,12 +192,23 @@ const decode_obj = obj => {
     throw `decode_obj: unsupported value, ${obj}`
 }
 
+export const decode_obj_or_error = obj => {
+    const result = decode_obj(obj)
+    if (result instanceof RubyError)
+        return result.get()
+    else
+        return result
+}
+
 const js_eval = eval
 
-const funcall_from_ruby = cmd => {
+export const funcall_from_ruby = cmd => {
     const receiver = decode_obj(cmd[2])
     const name = cmd[3]
     const args = cmd[4].map(e => decode_obj(e))
+    if (debug_level >= 10)
+        console.error(`RubyToJS> ${name} ${cmd[1]}`)
+
     if (name.endsWith('=')) {
         const name2 = name.substring(0, name.length - 1)
         if (receiver === null)
@@ -211,8 +229,8 @@ const funcall_from_ruby = cmd => {
     }
     else {
         const f = Reflect.get(receiver, name)
-        if (f)
-            if (typeof f === 'function')
+        if (f !== undefined)
+            if (typeof f === 'function' && !(f instanceof RemoteRef))
                 return Reflect.apply(f, receiver, args)
             else if (args.length === 0)
                 return f    // obtain a propety
@@ -221,7 +239,7 @@ const funcall_from_ruby = cmd => {
     throw `unknown JS function/method was called: ${name} on <${receiver}>`
 }
 
-let stdout_puts = console.log
+export let stdout_puts = console.log
 let num_generated_ids = 0
 
 const fresh_id = () => {
@@ -229,7 +247,7 @@ const fresh_id = () => {
     return num_generated_ids
 }
 
-const reply = (message_id, value, sync_mode) => {
+export const reply = (message_id, value, sync_mode) => {
     if (sync_mode && value instanceof Promise)
         value.then(result => { reply(message_id, result, true) })
              .catch(err => reply_error(message_id, err))
@@ -244,8 +262,10 @@ const reply = (message_id, value, sync_mode) => {
     }
 }
 
-const reply_error = (message_id, e) => {
-    const cmd = reply_with_piggyback([cmd_reply, message_id, encode_error(e)])
+export const reply_error = (message_id, error) => {
+    const msg = typeof error === 'string' ? error : error.toString() +
+                                                            '\n  ---\n' + error.stack
+    const cmd = reply_with_piggyback([cmd_reply, message_id, encode_error(msg)])
     stdout_puts(JSON.stringify(cmd))
 }
 
@@ -279,24 +299,39 @@ let reply_counter = 0
 
 export const exec = src => {
     return new Promise((resolve, reject) => {
-        const message_id = fresh_id()
-        const cmd = reply_with_piggyback([cmd_eval, message_id, src])
+        const cmd = make_cmd_eval(src)
+        const message_id = cmd[1]
         callback_stack.push([message_id, resolve, reject])
         stdout_puts(JSON.stringify(cmd))
     })
 }
 
-const funcall_to_ruby = (receiver_id, name, args) => {
+export const make_cmd_eval = src => {
+    const message_id = fresh_id()
+    return reply_with_piggyback([cmd_eval, message_id, src])
+}
+
+let funcall_to_ruby = (receiver_id, name, args) => {
     return new Promise((resolve, reject) => {
-        const message_id = fresh_id()
-        const receiver = [param_local_object, receiver_id]
-        const encoded_args = args.map(e => encode_obj(e))
-        const cmd = reply_with_piggyback([cmd_call, message_id, receiver, name, encoded_args])
+        const cmd = make_cmd_call(receiver_id, name, args)
+        const message_id = cmd[1]
         callback_stack.push([message_id, resolve, reject])
+        if (debug_level >= 10)
+            console.error(`JStoRuby< ${name} ${message_id}`)
+
         stdout_puts(JSON.stringify(cmd))
     })
 }
 
+export const set_funcall_to_ruby = f => { funcall_to_ruby = f }
+
+export const make_cmd_call = (receiver_id, name, args) => {
+    const message_id = fresh_id()
+    const receiver = [param_local_object, receiver_id]
+    const encoded_args = args.map(e => encode_obj(e))
+    return reply_with_piggyback([cmd_call, message_id, receiver, name, encoded_args])
+}
+
 const returned_from_callback = cmd => {
     const message_id = cmd[1]
     const result = decode_obj(cmd[2])
@@ -412,6 +447,10 @@ export class MessageReader {
     }
 }
 
+let make_message_reader = (stdin) => new MessageReader(stdin)
+
+export const set_make_message_reader = (f) => { make_message_reader = f }
+
 export const start = async (stdin, use_stdout) => {
     if (use_stdout)
         console.log = console.error         // on node.js
@@ -419,7 +458,7 @@ export const start = async (stdin, use_stdout) => {
         stdout_puts = (m) => stdin.puts(m)  // on browser
 
     stdin.setEncoding('utf8')
-    for await (const json_data of new MessageReader(stdin)) {
+    for await (const json_data of make_message_reader(stdin)) {
         let cmd
         try {
             cmd = JSON.parse(json_data)
@@ -451,9 +490,7 @@ export const start = async (stdin, use_stdout) => {
             else // cmd_retry and other unknown commands
                 reply_error(cmd[1], `invalid command ${cmd[0]}`)
         } catch (error) {
-            const msg = typeof error === 'string' ? error : error.toString() +
-                                                            '\n  ---\n' + error.stack
-            reply_error(cmd[1], msg)
+            reply_error(cmd[1], error)
         }
     }
 }

data/lib/jscall/synch.mjs

@@ -0,0 +1,185 @@
+// Copyright (C) 2022- Shigeru Chiba.  All rights reserved.
+// This works only with node.js on Linux
+
+import * as main from './main.mjs'
+import { readSync, openSync } from 'fs'
+
+class SynchronousStdin {
+    constructor() {
+        this.buf_size = 4096
+        this.buffer = Buffer.alloc(this.buf_size);
+        this.stdin = openSync('/dev/stdin', 'rs') 
+    }
+
+    *[Symbol.iterator]() {
+        let str
+        while ((str = this.readOne()) !== null)
+            yield str
+    }
+
+    readOne() {
+        while (true) {
+            try {
+                const nbytes = readSync(this.stdin, this.buffer, 0, this.buf_size)
+                if (nbytes > 0)
+                    return this.buffer.toString('utf-8', 0, nbytes)
+                else
+                    return null     // maybe EOF on macOS
+            }
+            catch (e) {
+                if (e.code === 'EOF')
+                    return null
+                else if (e.code !== 'EAGAIN')
+                    throw e
+            }
+        }
+    }
+}
+
+class SyncMessageReader extends main.MessageReader {
+    constructor(stream) {
+        super(stream)
+        this.stdin = new SynchronousStdin()
+        this.generator = null
+    }
+
+    gets_function() {
+        const iterator = this[Symbol.iterator]()
+        return () => {
+            const v = iterator.next()
+            if (v.done)
+                return null
+            else
+                return v.value
+        }
+    }
+
+    async *[Symbol.asyncIterator]() {
+        if (this.generator !== null) {
+            while (true) {
+                const v = this.generator.next()
+                if (v.done)
+                    break
+                else
+                    yield v.value
+            }
+        }
+        for await (const data of this.stream) {
+            this.acc += data
+            this.generator = this.generatorBody()
+            while (true) {
+                const v = this.generator.next()
+                if (v.done)
+                    break
+                else
+                    yield v.value
+            }
+        }
+        this.checkEOS()
+    }
+
+    *[Symbol.iterator]() {
+        if (this.generator !== null) {
+            while (true) {
+                const v = this.generator.next()
+                if (v.done)
+                    break
+                else
+                    yield v.value
+            }
+        }
+        for (const data of this.stdin) {
+            this.acc += data
+            this.generator = this.generatorBody()
+            while (true) {
+                const v = this.generator.next()
+                if (v.done)
+                    break
+                else
+                    yield v.value
+            }
+        }
+        this.checkEOS()
+    }
+
+    *generatorBody() {
+        let pos = 0
+        while (true) {
+            const result = this.iteratorBody(pos)
+            if (result[0] === false)
+                break
+            else if (result[0] !== true)
+                yield result[0]     // result[0] is a string
+
+            pos = result[1]
+            if (this.checkEmptiness(pos))
+                break
+        }
+    }
+}
+
+export const start = main.start
+
+let stdin_gets = null
+
+main.set_make_message_reader((stdin) => {
+    const reader = new SyncMessageReader(stdin)
+    stdin_gets = reader.gets_function()
+    return reader
+})
+
+const js_eval = eval
+const exported = main.get_exported_imported()[0]
+
+const event_loop = () => {
+    let json_data
+    while ((json_data = stdin_gets()) !== null) {
+        let cmd
+        try {
+            cmd = JSON.parse(json_data)
+
+            // scavenge remote references
+            if (cmd.length > 5)
+                cmd[5].forEach(i => exported.remove(i))
+
+            if (cmd[0] == main.cmd_eval || cmd[0] == main.cmd_async_eval) {
+                const result = js_eval(cmd[2])
+                main.reply(cmd[1], result, false)
+            }
+            else if (cmd[0] == main.cmd_call || cmd[0] == main.cmd_async_call) {
+                const result = main.funcall_from_ruby(cmd)
+                main.reply(cmd[1], result, false)
+            }
+            else if (cmd[0] == main.cmd_reply)
+                return main.decode_obj_or_error(cmd[2])
+            else { // cmd_retry, cmd_reject, and other unknown commands
+                console.error(`*** node.js; bad message received: ${json_data}`)
+                break
+            }
+        } catch (error) {
+            const msg = typeof error === 'string' ? error : error.toString() +
+                                                            '\n  ---\n' + error.stack
+            main.reply_error(cmd[1], msg)
+        }
+    }
+    return undefined
+}
+
+export const exec = src => {
+    const cmd = main.make_cmd_eval(src)
+    main.stdout_puts(JSON.stringify(cmd))
+    return event_loop()
+}
+
+main.set_funcall_to_ruby((receiver_id, name, args) => {
+    const cmd = main.make_cmd_call(receiver_id, name, args)
+    main.stdout_puts(JSON.stringify(cmd))
+    return event_loop()
+})
+
+export const scavenge_references = main.scavenge_references
+
+// for testing and debugging
+export const get_exported_imported = main.get_exported_imported
+
+export const dyn_import = main.dyn_import

data/lib/jscall/version.rb

@@ -3,5 +3,5 @@
 # Copyright (C) 2022- Shigeru Chiba.  All rights reserved.
 
 module Jscall
-  VERSION = "1.1.0"
+  VERSION = "1.3.0"
 end

data/lib/jscall.rb

@@ -231,7 +231,8 @@ module Jscall
                 script2 += "import * as m#{i + 2} from \"#{module_names[i][1]}#{module_names[i][2]}\"; globalThis.#{module_names[i][0]} = m#{i + 2}; "
             end
             script2 += "import { createRequire } from \"node:module\"; globalThis.require = createRequire(\"file://#{Dir.pwd}/\");"
-            script = "'import * as m1 from \"#{__dir__}/jscall/main.mjs\"; globalThis.Ruby = m1; #{script2}; Ruby.start(process.stdin, true)'"
+            main_js_file = if config[:sync] then "synch.mjs" else "main.mjs" end
+            script = "'import * as m1 from \"#{__dir__}/jscall/#{main_js_file}\"; globalThis.Ruby = m1; #{script2}; Ruby.start(process.stdin, true)'"
             @pipe = IO.popen("#{@@node_cmd} #{options} --input-type 'module' -e #{script}", "r+t")
             @pipe.autoclose = true
         end
@@ -392,13 +393,15 @@ module Jscall
                     if reply[1] != message_id
                         send_reply(reply[1], nil, false, CMD_REJECT)
                     else
-                        result = @pending_replies.delete(message_id)
-                        if result.nil?
-                            raise RuntimeError.new("bad CMD_RETRY: #{reply}")
-                        elsif result.is_a?(JavaScriptError)
-                            raise result
+                        if @pending_replies.key?(message_id)
+                            result = @pending_replies.delete(message_id)
+                            if result.is_a?(JavaScriptError)
+                                raise result
+                            else
+                                return result
+                            end
                         else
-                            return result
+                            raise RuntimeError.new("bad CMD_RETRY: #{reply}")
                         end
                     end
                 else
@@ -432,7 +435,7 @@ module Jscall
     @configurations = {}
     @pipeToJsClass = PipeToJs
 
-    #def self.config(module_names: [], options: '', browser: false)
+    #def self.config(module_names: [], options: '', browser: false, sync: false)
     def self.config(**kw)
         if kw.nil? || kw == {}
             @configurations = {}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jscall
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Shigeru Chiba
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-08-11 00:00:00.000000000 Z
+date: 2022-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: webrick
@@ -35,6 +35,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- examples/pdf-js.rb
 - jscall.gemspec
 - lib/jscall.rb
 - lib/jscall/apple-touch-icon.png
@@ -43,6 +44,7 @@ files:
 - lib/jscall/favicon.ico
 - lib/jscall/jscall.html
 - lib/jscall/main.mjs
+- lib/jscall/synch.mjs
 - lib/jscall/version.rb
 homepage: https://github.com/csg-tokyo/jscall
 licenses: