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

創建依賴

node.js

npm

curl http://npmjs.org/install.sh | sh

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)。

例子：

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

JSREPL::eval

在當前已加載的解釋器中執行一條程序。帶有一個參數：

• 字符串 command：須要執行的程序字符串。
  例子:

javascriptjsrepl.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/{語言名} 文件夾或子模塊下找到。