retoor/wren
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

UPdate.
WrenCI / mac (push) Waiting to run
Details
WrenCI / windows (push) Waiting to run
Details
WrenCI / linux (push) Failing after 55s
Details

Browse Source
This commit is contained in:
retoor
2026-01-26 05:12:14 +01:00
parent a59dbe1d55
commit fe2f087d9f
143 changed files with 13333 additions and 15112 deletions
Download Patch File Download Diff File Expand all files Collapse all files
manual_src/pages/getting-started/first-script.html
+203
View File
@@ -0,0 +1,203 @@
{# retoor <retoor@molodetz.nl> #}
{% extends 'page.html' %}
{% set page_title = "First Script" %}
{% set breadcrumb = [{"url": "getting-started/index.html", "title": "Getting Started"}, {"title": "First Script"}] %}
{% set prev_page = {"url": "getting-started/installation.html", "title": "Installation"} %}
{% set next_page = {"url": "getting-started/repl.html", "title": "Using the REPL"} %}
{% block article %}
<h1>First Script</h1>
<p>This guide walks you through creating and running your first Wren script. You will learn the basics of printing output, using variables, and importing modules.</p>
<h2>Hello World</h2>
<p>Create a file named <code>hello.wren</code> with the following content:</p>
<pre><code>System.print("Hello, World!")</code></pre>
<p>Run it:</p>
<pre><code>bin/wren_cli hello.wren</code></pre>
<div class="example-output">Hello, World!</div>
<p>The <code>System.print</code> method outputs text to the console followed by a newline.</p>
<h2>Variables and Types</h2>
<p>Wren is dynamically typed. Use <code>var</code> to declare variables:</p>
<pre><code>var name = "Wren"
var version = 0.4
var features = ["fast", "small", "class-based"]
var active = true
System.print("Language: %(name)")
System.print("Version: %(version)")
System.print("Features: %(features)")
System.print("Active: %(active)")</code></pre>
<div class="example-output">Language: Wren
Version: 0.4
Features: [fast, small, class-based]
Active: true</div>
<p>The <code>%(expression)</code> syntax is string interpolation. It evaluates the expression and inserts the result into the string.</p>
<h2>Working with Lists and Maps</h2>
<pre><code>var numbers = [1, 2, 3, 4, 5]
System.print("Count: %(numbers.count)")
System.print("First: %(numbers[0])")
System.print("Last: %(numbers[-1])")
var person = {
"name": "Alice",
"age": 30,
"city": "Amsterdam"
}
System.print("Name: %(person["name"])")</code></pre>
<div class="example-output">Count: 5
First: 1
Last: 5
Name: Alice</div>
<h2>Control Flow</h2>
<pre><code>var score = 85
if (score >= 90) {
System.print("Grade: A")
} else if (score >= 80) {
System.print("Grade: B")
} else {
System.print("Grade: C")
}
for (i in 1..5) {
System.print("Count: %(i)")
}</code></pre>
<div class="example-output">Grade: B
Count: 1
Count: 2
Count: 3
Count: 4
Count: 5</div>
<h2>Functions</h2>
<p>Functions in Wren are created using block syntax:</p>
<pre><code>var greet = Fn.new { |name|
return "Hello, %(name)!"
}
System.print(greet.call("World"))
var add = Fn.new { |a, b| a + b }
System.print(add.call(3, 4))</code></pre>
<div class="example-output">Hello, World!
7</div>
<h2>Classes</h2>
<pre><code>class Person {
construct new(name, age) {
_name = name
_age = age
}
name { _name }
age { _age }
greet() {
System.print("Hello, I'm %(_name)")
}
}
var alice = Person.new("Alice", 30)
alice.greet()
System.print("Age: %(alice.age)")</code></pre>
<div class="example-output">Hello, I'm Alice
Age: 30</div>
<h2>Using Modules</h2>
<p>Wren-CLI provides many built-in modules. Import them to use their functionality:</p>
<pre><code>import "io" for File
var content = File.read("hello.wren")
System.print("File contents:")
System.print(content)</code></pre>
<h3>Making HTTP Requests</h3>
<pre><code>import "http" for Http
import "json" for Json
var response = Http.get("https://httpbin.org/get")
System.print("Status: %(response.status)")
var data = Json.parse(response.body)
System.print("Origin: %(data["origin"])")</code></pre>
<h3>Working with JSON</h3>
<pre><code>import "json" for Json
var data = {
"name": "Wren",
"version": 0.4,
"features": ["fast", "small"]
}
var jsonString = Json.stringify(data)
System.print(jsonString)
var parsed = Json.parse(jsonString)
System.print("Name: %(parsed["name"])")</code></pre>
<h2>Error Handling</h2>
<p>Use <code>Fiber.try</code> to catch runtime errors:</p>
<pre><code>var fiber = Fiber.new {
var x = 1 / 0
}
var error = fiber.try()
if (error) {
System.print("Error: %(error)")
}</code></pre>
<h2>Script Arguments</h2>
<p>Access command-line arguments via <code>Process.arguments</code>:</p>
<pre><code>import "os" for Process
System.print("Script arguments:")
for (arg in Process.arguments) {
System.print(" %(arg)")
}</code></pre>
<p>Run with arguments:</p>
<pre><code>bin/wren_cli script.wren arg1 arg2 arg3</code></pre>
<h2>Exit Codes</h2>
<p>Wren-CLI uses these exit codes:</p>
<table>
<tr>
<th>Code</th>
<th>Meaning</th>
</tr>
<tr>
<td>0</td>
<td>Success</td>
</tr>
<tr>
<td>65</td>
<td>Compile error (syntax error)</td>
</tr>
<tr>
<td>70</td>
<td>Runtime error</td>
</tr>
</table>
<h2>Next Steps</h2>
<ul>
<li><a href="repl.html">Using the REPL</a> - Interactive experimentation</li>
<li><a href="../language/index.html">Language Reference</a> - Deep dive into Wren syntax</li>
<li><a href="../tutorials/index.html">Tutorials</a> - Build real applications</li>
</ul>
{% endblock %}
manual_src/pages/getting-started/index.html
+104
View File
@@ -0,0 +1,104 @@
{# retoor <retoor@molodetz.nl> #}
{% extends 'page.html' %}
{% set page_title = "Getting Started" %}
{% set breadcrumb = [{"title": "Getting Started"}] %}
{% set prev_page = {"url": "index.html", "title": "Home"} %}
{% set next_page = {"url": "getting-started/installation.html", "title": "Installation"} %}
{% block article %}
<h1>Getting Started</h1>
<p>Welcome to Wren-CLI, a command-line interface for the Wren programming language extended with powerful modules for networking, file I/O, databases, and more.</p>
<div class="toc">
<h4>In This Section</h4>
<ul>
<li><a href="installation.html">Installation</a> - Build from source on Linux, macOS, or FreeBSD</li>
<li><a href="first-script.html">First Script</a> - Write and run your first Wren program</li>
<li><a href="repl.html">Using the REPL</a> - Interactive experimentation</li>
</ul>
</div>
<h2>What is Wren?</h2>
<p>Wren is a small, fast, class-based scripting language. It has a familiar syntax, first-class functions, and a fiber-based concurrency model. Wren-CLI extends the core language with modules for:</p>
<ul>
<li>HTTP and WebSocket networking</li>
<li>File and directory operations</li>
<li>SQLite database access</li>
<li>JSON and regex processing</li>
<li>Template rendering (Jinja2-compatible)</li>
<li>Cryptographic operations</li>
<li>Process and signal handling</li>
</ul>
<h2>Quick Start</h2>
<p>If you want to dive right in, here is the fastest path to running your first script:</p>
<h3>1. Build</h3>
<pre><code>git clone https://github.com/wren-lang/wren-cli.git
cd wren-cli
cd projects/make && make</code></pre>
<h3>2. Create a Script</h3>
<p>Create a file named <code>hello.wren</code>:</p>
<pre><code>System.print("Hello, Wren!")</code></pre>
<h3>3. Run</h3>
<pre><code>bin/wren_cli hello.wren</code></pre>
<div class="example-output">Hello, Wren!</div>
<h2>Key Concepts</h2>
<p>Before diving deeper, understand these fundamental Wren concepts:</p>
<h3>Everything is an Object</h3>
<p>In Wren, everything is an object, including numbers, strings, and functions. Every object is an instance of a class.</p>
<pre><code>var name = "Wren"
System.print(name.count) // 4
System.print(name.bytes[0]) // 87 (ASCII for 'W')</code></pre>
<h3>Fibers for Concurrency</h3>
<p>Wren uses fibers (cooperative threads) for concurrency. The scheduler module manages async operations.</p>
<pre><code>import "timer" for Timer
Timer.sleep(1000) // Pauses for 1 second
System.print("Done waiting")</code></pre>
<h3>Module System</h3>
<p>Functionality is organized into modules that you import as needed:</p>
<pre><code>import "http" for Http
import "json" for Json
var response = Http.get("https://api.example.com/data")
var data = Json.parse(response.body)</code></pre>
<h2>System Requirements</h2>
<table>
<tr>
<th>Platform</th>
<th>Requirements</th>
</tr>
<tr>
<td>Linux</td>
<td>GCC, Make, OpenSSL development libraries</td>
</tr>
<tr>
<td>macOS</td>
<td>Xcode Command Line Tools, OpenSSL (via Homebrew)</td>
</tr>
<tr>
<td>FreeBSD</td>
<td>GCC or Clang, gmake, OpenSSL</td>
</tr>
</table>
<h2>Next Steps</h2>
<p>Continue with the following sections to learn more:</p>
<ul>
<li><a href="installation.html">Installation</a> - Detailed build instructions for all platforms</li>
<li><a href="first-script.html">First Script</a> - A more detailed walkthrough of your first program</li>
<li><a href="../language/index.html">Language Reference</a> - Learn the Wren language syntax</li>
<li><a href="../api/index.html">API Reference</a> - Explore all available modules</li>
</ul>
{% endblock %}
manual_src/pages/getting-started/installation.html
+160
View File
@@ -0,0 +1,160 @@
{# retoor <retoor@molodetz.nl> #}
{% extends 'page.html' %}
{% set page_title = "Installation" %}
{% set breadcrumb = [{"url": "getting-started/index.html", "title": "Getting Started"}, {"title": "Installation"}] %}
{% set prev_page = {"url": "getting-started/index.html", "title": "Overview"} %}
{% set next_page = {"url": "getting-started/first-script.html", "title": "First Script"} %}
{% block article %}
<h1>Installation</h1>
<p>Wren-CLI must be built from source. This page covers the build process for Linux, macOS, and FreeBSD.</p>
<div class="toc">
<h4>On This Page</h4>
<ul>
<li><a href="#prerequisites">Prerequisites</a></li>
<li><a href="#linux">Building on Linux</a></li>
<li><a href="#macos">Building on macOS</a></li>
<li><a href="#freebsd">Building on FreeBSD</a></li>
<li><a href="#configurations">Build Configurations</a></li>
<li><a href="#verification">Verifying Installation</a></li>
</ul>
</div>
<h2 id="prerequisites">Prerequisites</h2>
<p>All platforms require:</p>
<ul>
<li>Git</li>
<li>C compiler (GCC or Clang)</li>
<li>Make</li>
<li>OpenSSL development libraries (for TLS/HTTPS support)</li>
<li>Python 3 (for running tests)</li>
</ul>
<h2 id="linux">Building on Linux</h2>
<h3>Install Dependencies</h3>
<p>On Debian/Ubuntu:</p>
<pre><code>sudo apt-get update
sudo apt-get install build-essential libssl-dev git python3</code></pre>
<p>On Fedora/RHEL:</p>
<pre><code>sudo dnf install gcc make openssl-devel git python3</code></pre>
<p>On Arch Linux:</p>
<pre><code>sudo pacman -S base-devel openssl git python</code></pre>
<h3>Build</h3>
<pre><code>git clone https://github.com/wren-lang/wren-cli.git
cd wren-cli
make build</code></pre>
<p>The binary will be created at <code>bin/wren_cli</code>.</p>
<h3>Install System-Wide (Optional)</h3>
<pre><code>sudo cp bin/wren_cli /usr/local/bin/wren</code></pre>
<h2 id="macos">Building on macOS</h2>
<h3>Install Dependencies</h3>
<p>Install Xcode Command Line Tools:</p>
<pre><code>xcode-select --install</code></pre>
<p>Install OpenSSL via Homebrew:</p>
<pre><code>brew install openssl</code></pre>
<h3>Build</h3>
<pre><code>git clone https://github.com/wren-lang/wren-cli.git
cd wren-cli
cd projects/make.mac && make</code></pre>
<div class="admonition note">
<div class="admonition-title">Note</div>
<p>If OpenSSL is not found, you may need to set the library path:</p>
<pre><code>export LDFLAGS="-L/opt/homebrew/opt/openssl/lib"
export CPPFLAGS="-I/opt/homebrew/opt/openssl/include"</code></pre>
</div>
<h2 id="freebsd">Building on FreeBSD</h2>
<h3>Install Dependencies</h3>
<pre><code>sudo pkg install gmake git python3</code></pre>
<h3>Build</h3>
<pre><code>git clone https://github.com/wren-lang/wren-cli.git
cd wren-cli
cd projects/make.bsd && gmake</code></pre>
<h2 id="configurations">Build Configurations</h2>
<p>Several build configurations are available:</p>
<table>
<tr>
<th>Configuration</th>
<th>Description</th>
</tr>
<tr>
<td><code>release_64bit</code></td>
<td>Default optimized 64-bit build</td>
</tr>
<tr>
<td><code>release_32bit</code></td>
<td>Optimized 32-bit build</td>
</tr>
<tr>
<td><code>debug_64bit</code></td>
<td>Debug build with symbols</td>
</tr>
<tr>
<td><code>debug_32bit</code></td>
<td>32-bit debug build</td>
</tr>
<tr>
<td><code>release_64bit-no-nan-tagging</code></td>
<td>Without NaN tagging optimization</td>
</tr>
<tr>
<td><code>debug_64bit-no-nan-tagging</code></td>
<td>Debug without NaN tagging</td>
</tr>
</table>
<p>To use a specific configuration:</p>
<pre><code>make config=debug_64bit</code></pre>
<p>Debug builds output to <code>bin/wren_cli_d</code>.</p>
<h2 id="verification">Verifying Installation</h2>
<p>Verify the build was successful:</p>
<pre><code>bin/wren_cli --version</code></pre>
<p>Run the test suite:</p>
<pre><code>make tests</code></pre>
<p>Start the REPL:</p>
<pre><code>bin/wren_cli</code></pre>
<div class="example-output">> </div>
<p>Type <code>System.print("Hello")</code> and press Enter to verify the REPL works.</p>
<h2>Troubleshooting</h2>
<h3>OpenSSL Not Found</h3>
<p>If you see errors about missing OpenSSL headers:</p>
<ul>
<li>Verify OpenSSL development packages are installed</li>
<li>On macOS, ensure Homebrew OpenSSL path is in your environment</li>
</ul>
<h3>Build Errors</h3>
<p>Try cleaning and rebuilding:</p>
<pre><code>make clean
make build</code></pre>
<h3>Test Failures</h3>
<p>Run a specific test module to isolate issues:</p>
<pre><code>python3 util/test.py json</code></pre>
{% endblock %}
manual_src/pages/getting-started/repl.html
+151
View File
@@ -0,0 +1,151 @@
{# retoor <retoor@molodetz.nl> #}
{% extends 'page.html' %}
{% set page_title = "Using the REPL" %}
{% set breadcrumb = [{"url": "getting-started/index.html", "title": "Getting Started"}, {"title": "Using the REPL"}] %}
{% set prev_page = {"url": "getting-started/first-script.html", "title": "First Script"} %}
{% set next_page = {"url": "language/index.html", "title": "Language Reference"} %}
{% block article %}
<h1>Using the REPL</h1>
<p>The REPL (Read-Eval-Print Loop) is an interactive environment for experimenting with Wren code. It is useful for testing ideas, exploring APIs, and learning the language.</p>
<h2>Starting the REPL</h2>
<p>Run <code>wren_cli</code> without arguments to start the REPL:</p>
<pre><code>bin/wren_cli</code></pre>
<p>You will see a prompt:</p>
<div class="example-output">> </div>
<h2>Basic Usage</h2>
<p>Type expressions and press Enter to evaluate them:</p>
<pre><code>> 1 + 2
3
> "hello".count
5
> [1, 2, 3].map { |x| x * 2 }
[2, 4, 6]</code></pre>
<h2>Multi-line Input</h2>
<p>The REPL automatically detects incomplete expressions and waits for more input:</p>
<pre><code>> class Person {
| construct new(name) {
| _name = name
| }
| name { _name }
| }
null
> var p = Person.new("Alice")
null
> p.name
Alice</code></pre>
<p>The <code>|</code> prompt indicates the REPL is waiting for more input.</p>
<h2>Importing Modules</h2>
<p>Modules can be imported in the REPL just like in scripts:</p>
<pre><code>> import "json" for Json
null
> Json.stringify({"name": "Wren"})
{"name":"Wren"}
> import "math" for Math
null
> Math.sqrt(16)
4</code></pre>
<h2>Variables Persist</h2>
<p>Variables defined in the REPL persist across lines:</p>
<pre><code>> var x = 10
null
> var y = 20
null
> x + y
30</code></pre>
<h2>Examining Values</h2>
<p>Use <code>System.print</code> for formatted output:</p>
<pre><code>> var data = {"name": "Wren", "version": 0.4}
null
> System.print(data)
{name: Wren, version: 0.4}</code></pre>
<p>Check the type of a value:</p>
<pre><code>> 42.type
Num
> "hello".type
String
> [1, 2, 3].type
List</code></pre>
<h2>Exploring Classes</h2>
<p>Examine what methods a class provides:</p>
<pre><code>> String
String
> "test".bytes
[116, 101, 115, 116]
> "test".codePoints.toList
[116, 101, 115, 116]</code></pre>
<h2>Error Handling</h2>
<p>Errors are displayed but do not crash the REPL:</p>
<pre><code>> 1 / 0
infinity
> "test"[10]
Subscript out of bounds.
> undefined_variable
[repl line 1] Error at 'undefined_variable': Variable is used but not defined.</code></pre>
<p>You can continue using the REPL after errors.</p>
<h2>REPL Tips</h2>
<h3>Quick Testing</h3>
<p>Use the REPL to quickly test regular expressions:</p>
<pre><code>> import "regex" for Regex
null
> Regex.new("\\d+").test("abc123")
true
> Regex.new("\\d+").match("abc123def").text
123</code></pre>
<h3>Exploring APIs</h3>
<p>Test module functionality before using it in scripts:</p>
<pre><code>> import "base64" for Base64
null
> Base64.encode("Hello, World!")
SGVsbG8sIFdvcmxkIQ==
> Base64.decode("SGVsbG8sIFdvcmxkIQ==")
Hello, World!</code></pre>
<h3>Date and Time</h3>
<pre><code>> import "datetime" for DateTime
null
> DateTime.now
2024-01-15T10:30:45
> DateTime.now.year
2024</code></pre>
<h2>Exiting the REPL</h2>
<p>Exit the REPL by pressing <code>Ctrl+D</code> (Unix) or <code>Ctrl+Z</code> followed by Enter (Windows).</p>
<h2>Limitations</h2>
<ul>
<li>No command history navigation (arrow keys)</li>
<li>No tab completion</li>
<li>No line editing beyond basic backspace</li>
<li>Cannot redefine classes once defined</li>
</ul>
<div class="admonition tip">
<div class="admonition-title">Tip</div>
<p>For complex experimentation, write code in a file and run it with <code>wren_cli script.wren</code>. The REPL is best for quick tests and exploration.</p>
</div>
<h2>Next Steps</h2>
<ul>
<li><a href="../language/index.html">Language Reference</a> - Learn Wren syntax in detail</li>
<li><a href="../api/index.html">API Reference</a> - Explore available modules</li>
<li><a href="../tutorials/index.html">Tutorials</a> - Build real applications</li>
</ul>
{% endblock %}