|
1 | 1 | # sheetruby |
2 | | -mruby VM in your spreadsheet |
| 2 | + |
| 3 | +Run Ruby code in Google Sheets using [mruby/edge](https://github.com/mrubyedge/mrubyedge) |
| 4 | + |
| 5 | +## What is sheetruby? |
| 6 | + |
| 7 | +sheetruby embeds the [mruby/edge](https://github.com/mrubyedge/mrubyedge) VM into Google Apps Script, allowing you to execute Ruby code directly in your spreadsheets. It compiles to WebAssembly and runs entirely within Google Sheets' Apps Script environment. |
| 8 | + |
| 9 | +## How to Use |
| 10 | + |
| 11 | +1. Open your Google Spreadsheet |
| 12 | +2. Go to **Extensions** → **Apps Script** |
| 13 | +3. Copy the contents of `combined.js` and paste it into the script editor |
| 14 | +4. Save the script |
| 15 | +5. Return to your spreadsheet - the `EVAL_RUBY_SCRIPT()` function is now available! |
| 16 | + |
| 17 | +## `EVAL_RUBY_SCRIPT()` Function Specification |
| 18 | + |
| 19 | +```javascript |
| 20 | +EVAL_RUBY_SCRIPT(ruby_code, [arg1], [arg2], [arg3]) |
| 21 | +``` |
| 22 | + |
| 23 | +### Parameters |
| 24 | + |
| 25 | +- **First argument (required)**: Ruby script code |
| 26 | + - Can be a string literal or reference to a cell |
| 27 | +- **Arguments 2-4 (optional)**: Data to pass to the Ruby script |
| 28 | + - Can reference cells or ranges |
| 29 | + - Accessible in Ruby as global variables `$arg1`, `$arg2`, `$arg3` |
| 30 | + - Currently supports up to 3 arguments |
| 31 | + |
| 32 | +### Type Handling |
| 33 | + |
| 34 | +- **Single cell**: Type is automatically inferred (number, string, boolean) |
| 35 | +- **Multiple cells**: Passed as a 2D array (Array of Arrays) |
| 36 | +- **Return value**: Type is automatically inferred from Ruby result via JSON serialization |
| 37 | + |
| 38 | +### Examples |
| 39 | + |
| 40 | +**Basic calculation:** |
| 41 | +```ruby |
| 42 | +=EVAL_RUBY_SCRIPT("1 + 2") |
| 43 | +# => 3 |
| 44 | +``` |
| 45 | + |
| 46 | +**Using cell references:** |
| 47 | +```ruby |
| 48 | +=EVAL_RUBY_SCRIPT("$arg1 * 2", A1) |
| 49 | +# If A1 = 21, returns 42 |
| 50 | +``` |
| 51 | + |
| 52 | +**Array processing:** |
| 53 | +```ruby |
| 54 | +=EVAL_RUBY_SCRIPT("$arg1.map { |x| x * $arg2 }", A1:A3, B1) |
| 55 | +# If A1:A3 = [[1], [2], [3]] and B1 = 10 |
| 56 | +# Returns [10, 20, 30] |
| 57 | +``` |
| 58 | + |
| 59 | +**Multiple arguments:** |
| 60 | +```ruby |
| 61 | +=EVAL_RUBY_SCRIPT("$arg1 + $arg2 + $arg3", A1, B1, C1) |
| 62 | +# Sum of three cells |
| 63 | +``` |
| 64 | + |
| 65 | +**String manipulation:** |
| 66 | +```ruby |
| 67 | +=EVAL_RUBY_SCRIPT("$arg1.upcase", A1) |
| 68 | +# If A1 = "hello", returns "HELLO" |
| 69 | +``` |
| 70 | + |
| 71 | +**Math functions (with mrubyedge-math):** |
| 72 | +```ruby |
| 73 | +=EVAL_RUBY_SCRIPT("Math.sqrt($arg1)", 16) |
| 74 | +# => 4.0 |
| 75 | +``` |
| 76 | + |
| 77 | +## Building from Source |
| 78 | + |
| 79 | +### Prerequisites |
| 80 | + |
| 81 | +1. Install [Emscripten SDK](https://emscripten.org/docs/getting_started/downloads.html) |
| 82 | + ```bash |
| 83 | + git clone https://github.com/emscripten-core/emsdk.git |
| 84 | + cd emsdk |
| 85 | + ./emsdk install latest |
| 86 | + ./emsdk activate latest |
| 87 | + source ./emsdk_env.sh |
| 88 | + ``` |
| 89 | + |
| 90 | +2. Install Rust with the `wasm32-unknown-emscripten` target: |
| 91 | + ```bash |
| 92 | + rustup target add wasm32-unknown-emscripten |
| 93 | + ``` |
| 94 | + |
| 95 | +3. Set the `BINDGEN_EXTRA_CLANG_ARGS` environment variable: |
| 96 | + ```bash |
| 97 | + export BINDGEN_EXTRA_CLANG_ARGS="--sysroot=$EMSDK/upstream/emscripten/cache/sysroot" |
| 98 | + ``` |
| 99 | + |
| 100 | +### Build |
| 101 | + |
| 102 | +```bash |
| 103 | +make build |
| 104 | +``` |
| 105 | + |
| 106 | +This will generate `combined.js` in the project root. |
| 107 | + |
| 108 | +## Contributing |
| 109 | + |
| 110 | +Bug reports and contributions are welcome! Please feel free to: |
| 111 | + |
| 112 | +- Report issues on [GitHub Issues](https://github.com/mrubyedge/sheetruby/issues) |
| 113 | +- Submit pull requests |
| 114 | +- Share your use cases and feedback |
| 115 | + |
| 116 | +## License |
| 117 | + |
| 118 | +See [LICENSE](LICENSE) file for details. |
0 commit comments