JSREPL README.md 中文翻译

一个兼容多种语言的浏览器 REPL 沙盒。

当前支持的语言

Javascript 系列
- Javascript
- CoffeeScript
- Kaffeine
- Move
- Traceur (JavaScript.next)
Esoteric
- Bloop
- Brainfuck
- LOLCODE
- Unlambda
- Emoticon
Classic
- Quick Basic
- Forth
Serious
- Scheme
- Lua
- Python
- Ruby (beta)

支持的浏览器

IE 9-10
Chrome 10+
Safari 5
Firefox 3.6+
Opera 11+
iOS 5 Safari

开始

建立 JSREPL

建立依赖

CoffeeScript

使用 npm 安装：sudo npm install -g coffee-script

获取源码

克隆仓库 (cloning the repository)

git clone git://github.com/replit/jsrepl.git

源码依赖

git submodule update --init --recursive

进行 Bake 操作

cake bake

引入 JSREPL

html<script src="jsrepl.js" id="jsrepl-script"></script>

实例化 JSREPL

javascriptvar jsrepl = new JSREPL({  
  input: inputCallback,  
  output: outputCallback,  
  result: resultCallback,  
  error: errorCallback,  
  progress: progressCallback,  
  timeout: {  
    time: 30000,  
    callback: timeoutCallback  
  }
});

inputCallback：一个回调函数，当语言解释器在请求用户输入时会被调用。
outputCallback：一个可选的回调函数，当引擎需要将输出发送到标准输出时会被调用。
resultCallback：一个可选的回调函数，当解释器成功地执行(evaluated)一条程序并产生结果时会被调用。
errorCallback：一个可选的函数，如果一条程序在被执行(evaluated)的过程中产生错误时会被调用。
progress：一个可选的函数，当加载一种语言时会被不断调用，用来显示进度条百分值。
timeout：为程序运行设置一个超时值。
- time：等待时间（毫秒）。
- callback：超时后会调用的回调函数。这个回调必须处理垃圾回收系统（比如说调用 jsrepl.loadLanguage 之类的）。必须返回 true 以停止超时的重复触发。

API

JSREPL::loadLanguage

它会加载一个语言解释器，并带有三个参数：
* 字符串 lang_name：需要加载的语言名。
* 方法 callback：回调函数，当语言成功加载后会被调用。
* 布尔值 worker_friendly (可选)：JSREPL 默认会尝试加载一个解释器到 Web Workers，这个参数会决定解释器是加载到 Worker(true) 还是加载到一个 iframe(false)。

例子：

coffeescript  jsrepl.loadLanguage('python', function () {  
    alert('Python loaded');  
  });

JSREPL::eval

在当前已加载的解释器中执行一条程序。带有一个参数：

字符串 command：需要执行的程序字符串。
例子:

javascript    jsrepl.eval('1+1');

JSREPL::getLangConfig

返回该语言相应的配置对象。带有一个参数：

字符串 lang_name：需要返回配置对象的语言。默认为当前语言名。

JSREPL::checkLineEnd

给定一条命令，决定是否准备好执行。因为有些情况是会导致暂时不准备执行的，比如缺少右括号。

字符串 command：字符串，一条程序。
方法 callback：回调函数，该回调函数会在命令(command)准备好执行时返回 true，在命令未完整时返回 false。

JSREPL::on

向一个或多个事件绑定一个监听器。带有两个参数：

字符串 | 数组 event_type：事件类型，表示需要监听的事件。
方法 callback：回调函数，事件被触发时将会被调用。调用时会带有事件提供的若干个参数。

JSREPL::off

解除某事件的一个或全部的监听器的绑定。带有两个参数：

字符串 | 数组 event_type：事件类型，表示需要解绑方法的事件。
方法 callback：回调函数，提供需要解绑的方法。如果不提供将会解除所有方法。

JSREPL::once

向一个或多个事件绑定一个只执行一次的监听器。带有两个参数：

字符串 | 数组 event_type：事件类型，表示需要监听的事件。
方法 callback：回调函数，事件被触发时将会被调用。调用时会带有事件提供的若干个参数。

事件

input (输入)

当当前的语言解释器请求输入时会被触发。参数：

方法 callback：回调函数，程序会连续执行这个回调函数。调用时必须带有用户输入的字符串。注意，这个回调函数只能被一个监听器调用。

output (输出)

当前的语言解释器每次向标准输出进行输出时都会被触发。参数：

字符串 data：数据，即输出的字符串。

result (返回)

当语言解释器有最终返回值时会被触发。参数：

字符串 data：数据，字符串的形式的最终返回值。

progress (进度)

当 JSREPL 在加载语言解释器时的进度百分比有变化时会被触发，用于报告进度。参数：

浮点型 percentage：百分比，表示加载了多少文件。

timeout (超时)

如果 JSREPL 在实例化时选择了 timeout ，当正在运行的程序在限定时间内未调用指定的回调函数（见实例化 JSREPL），那么将会触发此事件。

ready (已准备好)

当语言已经被加载完成并准备执行时，将会触发此事件。

一些标准输入的 hack

问题

编译时使用 Emscripten 的语言解释器期望输入的是一个阻塞式的调用（同步），要使之变成阻塞式调用的唯一方法是在浏览器里用 window.prompt 提示。虽然不理想，但它是可行的。然而，这种方法将会使我们失去在 Web Workers 中加载解释器的能力（因为 Workers 没有使用对话框）。

在 Workers 中加载解释器会有很多好处，包括当解释器初始化或工作时不阻塞主 UI 线程，以及拥有捕获无限循环的能力（见 timeout 事件）。尽管有这些优势，但为了能够输入，直到目前为止我们依然避免使用 Workers。所以我们加载阻塞式调用时应该使用 iframe 而不是 Worker。不过，在当前 Firefox 和 Chrome 的版本中打破了我们这个方法，因为我们再也不能做同步的二进制 XHR 操作了（比如去读取库文件）。

解决方案

Webkit 浏览器

在基于 Webkit 的浏览器中，我们可以利用非标准的 Web SQL 数据库在主线程和 worker 线程之间共享资源。例如它们提供的同步机制，使它可以访问主页面线程和 Worker（见 repl.coffee 和 sandbox.js）。

Firefox

遗憾，我们不能在 Firefox 进行同样的处理，因为它没有实现 Web SQL，而且仍然不支持标准的浏览器端数据库(IndexedDB)同步 API。相反，我们可以使用 XHR 在 Worker 和主线程之间进行同步通讯，而我们的服务器就是天然的代理。这里有一个样例服务器安装在 repl.it static server 。

许可

jsREPL 在 MIT 许可下使用。jsREPL 的开发者对语言解释器和修改过的 jsREPL 版本拥有自己的许可证，可以在它们的 extern/{语言名} 文件夹或子模块下找到。