「ioke Guide」の編集履歴(バックアップ)一覧はこちら
ioke Guide - (2009/05/04 (月) 03:18:01) の最新版との変更点
追加された行は緑色になります。
削除された行は赤色になります。
<div>
<blockquote>このページは<a href="http://ioke.org/wiki/index.php/Guide">http://ioke.org/wiki/index.php/Guide</a>からの引用です</blockquote>
</div>
<div id="globalWrapper">
<div id="column-content">
<div id="content"><a name="top"></a>
<h1 class="firstHeading">Guide</h1>
<div id="bodyContent">
<h3 id="siteSub">From IokeWiki</h3>
<div id="contentSub"> </div>
<div id="jump-to-nav">Jump to:<a href="#column-one">navigation</a>,<a href="#searchInput">search</a></div>
<table summary="Contents" class="toc" id="toc"><tbody><tr><td>
<div id="toctitle">
<h2>Contents</h2>
</div>
<ul><li class="toclevel-1"><a href="#Introduction"><span class="tocnumber">1</span><span class="toctext">Introduction</span></a>
<ul><li class="toclevel-2"><a href="#Vision"><span class="tocnumber">1.1</span><span class="toctext">Vision</span></a></li>
<li class="toclevel-2"><a href="#Getting_started"><span class="tocnumber">1.2</span><span class="toctext">Getting started</span></a>
<ul><li class="toclevel-3"><a href="#Building_Ioke"><span class="tocnumber">1.2.1</span><span class="toctext">Building Ioke</span></a></li>
<li class="toclevel-3"><a href="#Running_scripts"><span class="tocnumber">1.2.2</span><span class="toctext">Running scripts</span></a></li>
<li class="toclevel-3"><a href="#Interactive_mode"><span class="tocnumber">1.2.3</span><span class="toctext">Interactive mode</span></a></li>
</ul></li>
</ul></li>
<li class="toclevel-1"><a href="#Syntax"><span class="tocnumber">2</span><span class="toctext">Syntax</span></a>
<ul><li class="toclevel-2"><a href="#Literal_values"><span class="tocnumber">2.1</span><span class="toctext">Literal values</span></a>
<ul><li class="toclevel-3"><a href="#Text"><span class="tocnumber">2.1.1</span><span class="toctext">Text</span></a></li>
<li class="toclevel-3"><a href="#Regular_expressions"><span class="tocnumber">2.1.2</span><span class="toctext">Regular
expressions</span></a></li>
<li class="toclevel-3"><a href="#Integers"><span class="tocnumber">2.1.3</span><span class="toctext">Integers</span></a></li>
<li class="toclevel-3"><a href="#Decimals"><span class="tocnumber">2.1.4</span><span class="toctext">Decimals</span></a></li>
<li class="toclevel-3"><a href="#Symbols"><span class="tocnumber">2.1.5</span><span class="toctext">Symbols</span></a></li>
</ul></li>
<li class="toclevel-2"><a href="#Operator_shuffling"><span class="tocnumber">2.2</span><span class="toctext">Operator shuffling</span></a></li>
<li class="toclevel-2"><a href="#Assignment_shuffling"><span class="tocnumber">2.3</span><span class="toctext">Assignment
shuffling</span></a></li>
<li class="toclevel-2"><a href="#Inverted_operators"><span class="tocnumber">2.4</span><span class="toctext">Inverted operators</span></a></li>
</ul></li>
<li class="toclevel-1"><a href="#Execution_model"><span class="tocnumber">3</span><span class="toctext">Execution model</span></a></li>
<li class="toclevel-1"><a href="#Objects"><span class="tocnumber">4</span><span class="toctext">Objects</span></a>
<ul><li class="toclevel-2"><a href="#Base"><span class="tocnumber">4.1</span><span class="toctext">Base</span></a></li>
<li class="toclevel-2"><a href="#Ground"><span class="tocnumber">4.2</span><span class="toctext">Ground</span></a></li>
<li class="toclevel-2"><a href="#Origin"><span class="tocnumber">4.3</span><span class="toctext">Origin</span></a></li>
<li class="toclevel-2"><a href="#DefaultBehavior"><span class="tocnumber">4.4</span><span class="toctext">DefaultBehavior</span></a></li>
<li class="toclevel-2"><a href="#nil.2C_true.2C_false"><span class="tocnumber">4.5</span><span class="toctext">nil, true, false</span></a></li>
</ul></li>
<li class="toclevel-1"><a href="#Assignment"><span class="tocnumber">5</span><span class="toctext">Assignment</span></a>
<ul><li class="toclevel-2"><a href="#Let"><span class="tocnumber">5.1</span><span class="toctext">Let</span></a></li>
</ul></li>
<li class="toclevel-1"><a href="#Control_flow"><span class="tocnumber">6</span><span class="toctext">Control flow</span></a>
<ul><li class="toclevel-2"><a href="#Comparison"><span class="tocnumber">6.1</span><span class="toctext">Comparison</span></a></li>
<li class="toclevel-2"><a href="#Conditionals"><span class="tocnumber">6.2</span><span class="toctext">Conditionals</span></a>
<ul><li class="toclevel-3"><a href="#cond"><span class="tocnumber">6.2.1</span><span class="toctext">cond</span></a></li>
<li class="toclevel-3"><a href="#case"><span class="tocnumber">6.2.2</span><span class="toctext">case</span></a></li>
</ul></li>
<li class="toclevel-2"><a href="#Iteration"><span class="tocnumber">6.3</span><span class="toctext">Iteration</span></a>
<ul><li class="toclevel-3"><a href="#loop"><span class="tocnumber">6.3.1</span><span class="toctext">loop</span></a></li>
<li class="toclevel-3"><a href="#while"><span class="tocnumber">6.3.2</span><span class="toctext">while</span></a></li>
<li class="toclevel-3"><a href="#until"><span class="tocnumber">6.3.3</span><span class="toctext">until</span></a></li>
<li class="toclevel-3"><a href="#times"><span class="tocnumber">6.3.4</span><span class="toctext">times</span></a></li>
<li class="toclevel-3"><a href="#each"><span class="tocnumber">6.3.5</span><span class="toctext">each</span></a></li>
<li class="toclevel-3"><a href="#break.2C_continue"><span class="tocnumber">6.3.6</span><span class="toctext">break, continue</span></a></li>
</ul></li>
<li class="toclevel-2"><a href="#Comprehensions"><span class="tocnumber">6.4</span><span class="toctext">Comprehensions</span></a></li>
</ul></li>
<li class="toclevel-1"><a href="#Code"><span class="tocnumber">7</span><span class="toctext">Code</span></a>
<ul><li class="toclevel-2"><a href="#Methods"><span class="tocnumber">7.1</span><span class="toctext">Methods</span></a></li>
<li class="toclevel-2"><a href="#Macros"><span class="tocnumber">7.2</span><span class="toctext">Macros</span></a></li>
<li class="toclevel-2"><a href="#Blocks"><span class="tocnumber">7.3</span><span class="toctext">Blocks</span></a></li>
<li class="toclevel-2"><a href="#Lecros"><span class="tocnumber">7.4</span><span class="toctext">Lecros</span></a></li>
<li class="toclevel-2"><a href="#Syntax_2"><span class="tocnumber">7.5</span><span class="toctext">Syntax</span></a></li>
<li class="toclevel-2"><a href="#Destructuring"><span class="tocnumber">7.6</span><span class="toctext">Destructuring</span></a></li>
<li class="toclevel-2"><a href="#Message_chains"><span class="tocnumber">7.7</span><span class="toctext">Message chains</span></a></li>
</ul></li>
<li class="toclevel-1"><a href="#Introspection_and_reflection"><span class="tocnumber">8</span><span class="toctext">Introspection and
reflection</span></a></li>
<li class="toclevel-1"><a href="#Aspects"><span class="tocnumber">9</span><span class="toctext">Aspects</span></a></li>
<li class="toclevel-1"><a href="#Importing"><span class="tocnumber">10</span><span class="toctext">Importing</span></a></li>
<li class="toclevel-1"><a href="#Core_kinds"><span class="tocnumber">11</span><span class="toctext">Core kinds</span></a>
<ul><li class="toclevel-2"><a href="#Conditions"><span class="tocnumber">11.1</span><span class="toctext">Conditions</span></a></li>
<li class="toclevel-2"><a href="#Text_2"><span class="tocnumber">11.2</span><span class="toctext">Text</span></a></li>
<li class="toclevel-2"><a href="#Numbers"><span class="tocnumber">11.3</span><span class="toctext">Numbers</span></a></li>
<li class="toclevel-2"><a href="#Lists"><span class="tocnumber">11.4</span><span class="toctext">Lists</span></a></li>
<li class="toclevel-2"><a href="#Dicts"><span class="tocnumber">11.5</span><span class="toctext">Dicts</span></a>
<ul><li class="toclevel-3"><a href="#Sets"><span class="tocnumber">11.5.1</span><span class="toctext">Sets</span></a></li>
<li class="toclevel-3"><a href="#Ranges_and_Pairs"><span class="tocnumber">11.5.2</span><span class="toctext">Ranges and Pairs</span></a></li>
</ul></li>
<li class="toclevel-2"><a href="#Enumerable"><span class="tocnumber">11.6</span><span class="toctext">Enumerable</span></a></li>
<li class="toclevel-2"><a href="#Regexps"><span class="tocnumber">11.7</span><span class="toctext">Regexps</span></a></li>
<li class="toclevel-2"><a href="#FileSystem"><span class="tocnumber">11.8</span><span class="toctext">FileSystem</span></a></li>
<li class="toclevel-2"><a href="#Other_things"><span class="tocnumber">11.9</span><span class="toctext">Other things</span></a></li>
</ul></li>
<li class="toclevel-1"><a href="#Java_integration"><span class="tocnumber">12</span><span class="toctext">Java integration</span></a>
<ul><li class="toclevel-2"><a href="#Casts"><span class="tocnumber">12.1</span><span class="toctext">Casts</span></a></li>
<li class="toclevel-2"><a href="#Class_methods"><span class="tocnumber">12.2</span><span class="toctext">Class methods</span></a></li>
<li class="toclevel-2"><a href="#Fields"><span class="tocnumber">12.3</span><span class="toctext">Fields</span></a></li>
<li class="toclevel-2"><a href="#Importing_2"><span class="tocnumber">12.4</span><span class="toctext">Importing</span></a></li>
<li class="toclevel-2"><a href="#Java_native_arrays"><span class="tocnumber">12.5</span><span class="toctext">Java native arrays</span></a></li>
<li class="toclevel-2"><a href="#Adding_jar-files_to_the_CLASSPATH"><span class="tocnumber">12.6</span><span class="toctext">Adding
jar-files to the CLASSPATH</span></a></li>
<li class="toclevel-2"><a href="#Implementing_and_extending_Java_types"><span class="tocnumber">12.7</span><span class="toctext">Implementing and extending Java
types</span></a>
<ul><li class="toclevel-3"><a href="#Coercing_lexical_blocks_to_interfaces"><span class="tocnumber">12.7.1</span><span class="toctext">Coercing lexical blocks to
interfaces</span></a></li>
</ul></li>
</ul></li>
<li class="toclevel-1"><a href="#Libraries"><span class="tocnumber">13</span><span class="toctext">Libraries</span></a>
<ul><li class="toclevel-2"><a href="#IIk"><span class="tocnumber">13.1</span><span class="toctext">IIk</span></a></li>
<li class="toclevel-2"><a href="#ISpec"><span class="tocnumber">13.2</span><span class="toctext">ISpec</span></a></li>
<li class="toclevel-2"><a href="#DokGen"><span class="tocnumber">13.3</span><span class="toctext">DokGen</span></a></li>
</ul></li>
<li class="toclevel-1"><a href="#What_is_missing"><span class="tocnumber">14</span><span class="toctext">What is missing</span></a></li>
<li class="toclevel-1"><a href="#Future_plans"><span class="tocnumber">15</span><span class="toctext">Future plans</span></a></li>
</ul></td>
</tr></tbody></table><a name="Introduction"></a>
<h1><span class="mw-headline">Introduction</span></h1>
<p>Ioke is a general purpose language. It is a strongly typed, extremely
dynamic, prototype object oriented language. It is<a title="http://en.wikipedia.org/wiki/Homoiconicity" class="external text" href="http://en.wikipedia.org/wiki/Homoiconicity">homoiconic</a>and its closest
ancestors are<a title="http://iolanguage.com" class="external text" href="http://iolanguage.com">Io</a>,<a title="http://www.smalltalk.org" class="external text" href="http://www.smalltalk.org">Smalltalk</a>,<a title="http://www.ruby-lang.org" class="external text" href="http://www.ruby-lang.org">Ruby</a>and<a title="http://en.wikipedia.org/wiki/Lisp_programming_language" class="external text" href="http://en.wikipedia.org/wiki/Lisp_programming_language">Lisp</a>- but
it's quite a distance from all of them. It looks a lot like Io, to a limit.</p>
<p>Ioke is a<em>folding</em>language. This means it folds in on itself. You can
create new abstractions covering any of the existing abstractions in the
language. You can abstract over these, over and over again, until you have a
language that lets you express what you want to express in a succinct and
readable way. Ioke allows you to fold your code.</p>
<p>Ioke is targeted at the Java Virtual Machine and is tightly integrated with
the platform. Why the JVM? It's available everywhere, it gives several
important features such as world class garbage collectors, capable thread
schedulers and an amazing JIT compiler. All of these are things that serve Ioke
well, without requiring direct development resources from the Ioke team. Access
to the Java platform also means access to all existing libraries and
functionality, with all that entails. The JVM is just a very pragmatic
choice.</p>
<p>You're probably reading this guide at<a title="http://ioke.org/guide.html" class="external text" href="http://ioke.org/guide.html">ioke.org</a>. That is
the official home of the project, although some of the project functionality is
hosted at<a title="http://ioke.kenai.com" class="external text" href="http://ioke.kenai.com">Kenai</a>, where such things as mailing lists and a bug
tracker is available. The canonical source repository for Ioke is on<a title="http://github.org/olabini/ioke/tree/master" class="external text" href="http://github.org/olabini/ioke/tree/master">GitHub</a>.</p>
<p>The current version of Ioke is called<a title="Ioke E" href="/wiki/index.php/Ioke_E">Ioke E</a>. The naming of Ioke will change regularly
with major revisions. There are two different versions in play here.<a title="Ioke E" href="/wiki/index.php/Ioke_E">Ioke E</a>is the name and version of the
language and core libraries. The initial implementation for<a title="Ioke E" href="/wiki/index.php/Ioke_E">Ioke E</a>is called<tt>ikj 0.3.0</tt>, and the
version numbers are not interdependent. The next major version of Ioke will be
called<a title="Ioke P (not yet written)" class="new" href="/wiki/index.php?title=Ioke_P&action=edit&redlink=1">Ioke P</a>, and
you can find information about it in the chapter on<a title="" href="#Future_plans">future plans</a>.</p>
<p>This programming guide -- together with the reference for your current
version -- should be the complete document needed to understand<a title="Ioke E" href="/wiki/index.php/Ioke_E">Ioke E</a>, how to program in it, how to
understand the names and concepts used, and also give an initial inkling on
what I think is good taste.</p>
<p>Note that I will use many names that aren't necessarily the same as the ones
traditional programming languages use. These names will be made clear sooner or
later in this document, but it might help some to jump forward to<a title="" href="#Objects">Objects</a>, skim that bit, and then start over once words
like<em>Origin</em>,<em>cell</em>and<em>mimic</em>make sense.</p>
<a name="Vision"></a>
<h2><span class="mw-headline">Vision</span></h2>
<p>The evolution of programming languages is a steady progression of finding
new ways to express abstractions naturally - in a way that doesn't stray too
far away from the smaller details. A programming language has to make it
possible to abstract away common things, while making it easy to customize
these abstractions in very detailed ways. A programming language should be able
to do this well without sacrificing readability and understandability. This
tension lies at the core of programming.</p>
<p>How do you create a language that makes it easy to express powerful concepts
in a succinct way, while still making it easy to maintain and work with after
the fact, without turning it into a new compression mode? How do you make it
easy for a programmer to express high level abstractions that are abstractions
of abstractions of abstractions?</p>
<p>There are many open problems in programming language design. Concurrency is
one of them, performance another. These are two areas Ioke does not address.
Instead, Ioke is a remodeling of the core concepts and ideas embodied in other
programming languages.</p>
<p>Are Lisp and Smalltalk still the most powerful languages around, or are
there ways of providing more expressiveness without sacrificing
understandability? Is there a way to combine all the lessons learned from
languages like Ruby and Python, and patch them back into a Lisp and Smalltalk
core? Is it possible to do this while taking some of the benefits of Io? Can a
language be both small, regular, homoiconic, reflective and easy to understand?
I hope that Ioke is just that.</p>
<p>Simplicity doesn't mean lack of power. Small, simple, orthogonal
functionality can be more powerful than larger, complicated abstractions that
don't fit together.</p>
<p>Io explicitly states that the goal of the language is to refocus attention
on expressiveness, and with Ioke I want to take that philosophy one step
further.</p>
<p>It's important to realize that an experiment like this doesn't necessarily
have to mean the language can't be used for real projects. By wedding Ioke to
the Java Virtual Machine, I make it easy to get access to good libraries and
existing implementations on most platforms. In that way, Ioke can be used to
create real systems, even though the ecosystem will initially be very small.
And I think that this is necessary. How can you know if a language really is
worthwhile or not, if you can't use it as a general purpose programming
language? The Java platform makes this possible.</p>
<a name="Getting_started"></a>
<h2><span class="mw-headline">Getting started</span></h2>
<p>Ioke is very easy to get started with. The first step is to download a
package. Which one you choose depends on what platform you're on, and whether
you want to build Ioke yourself, or just start using it. This guide will only
cover using a prebuilt version. Go to the<a title="http://ioke.org/download.html" class="external text" href="http://ioke.org/download.html">download page</a>, and grab one of the
distributions. At the time of writing the full version of Ioke is Ioke E ikj
0.3.0. Choose the latest download in the 0.3-series for this document to
apply.</p>
<p>Once you have downloaded the distribution, you need to unpack it somewhere,
and finally add the<tt>bin</tt>directory to your<tt>PATH</tt>environment
variable. There is also a<tt>jar</tt>download that can be run directly. If you
choose this option you don't get the benefits of having a home for Ioke, which
in some cases might be inconvenient. Ioke can be run directly from the jar
file, though.</p>
<a name="Building_Ioke"></a>
<h3><span class="mw-headline">Building Ioke</span></h3>
<p>If you'd like to build Ioke from source, make sure you have a recent version
of the<a title="http://java.sun.com/javase/downloads/index.jsp" class="external text" href="http://java.sun.com/javase/downloads/index.jsp">Java
Development Kit</a>installed (1.5.0 or higher, preferrably 1.6.0) and<a title="http://ant.apache.org" class="external text" href="http://ant.apache.org">Apache Ant</a>. You must have the<tt>ant</tt>script
reachable from your<tt>PATH</tt>variable. Then, simply check out the source
code from the<a title="http://github.org/olabini/ioke/tree/master" class="external text" href="http://github.org/olabini/ioke/tree/master">main
repository</a>, and build it using<tt>ant</tt>. That should run all the
compilation steps and tests, and allow the<tt>bin/ioke</tt>script to run. Just
proceed as if you had unpacked the distribution, adding
the<tt>bin</tt>directory to the<tt>PATH</tt>.</p>
<a name="Running_scripts"></a>
<h3><span class="mw-headline">Running scripts</span></h3>
<p>To run an Ioke script, you can generally just use
the<tt>ioke</tt>command:</p>
<pre>
$ ioke helloWorld.ik Hello world
</pre>
<p>You can also execute snippets of code on the command line using
the<tt>-e</tt>argument to the<tt>ioke</tt>command. You can have several of
these in the same line too:</p>
<pre>
$ ioke -e'"Hello world" println' -e'"Goodbye world" println' Hello world Goodbye world
</pre>
<p>When using<tt>-e</tt>, be careful about what quoting style you use, since
the shell sometimes can munge up your commands if you don't surround them
correctly.</p>
<p>The<tt>ioke</tt>command has several helpful command line options, which can
change what happens during execution. These are:</p>
<dl><dt>-Cdirectory</dt>
<dd>Switch to directory before executing any files and command line scripts.
This will make the directory the initial current working directory for Ioke
during the execution of the JVM.</dd>
<dt>-d</dt>
<dd>Enable debug output.</dd>
<dt>-e script</dt>
<dd>Execute script, as describe above. May occur more than once on a command
line.</dd>
<dt>-h<br /></dt>
</dl><p>--help</p>
<dl><dd>Display help information, including descriptions of these command line
options.</dd>
<dt>-Idirectory</dt>
<dd>Add directory to the load path of Ioke. May occur more than once on a
command line.</dd>
<dt>-JjvmOptions</dt>
<dd>Pass on options to the JVM. This can be used to change any runtime
parameters that your JVM takes. May occur more than once. The options are
provided directly after the -J, so if you want to change the maximum amount of
memory used, you can do that writing -J-Xmx128M.</dd>
<dt>--copyright</dt>
<dd>Print copyright information and exit.</dd>
<dt>--version</dt>
<dd>Print version information and exit</dd>
<dt>--server</dt>
<dd>Run the JVM in server Hotspot mode</dd>
<dt>--client</dt>
<dd>Run the JVM in client Hotspot mode (the default)</dd>
<dt>--</dt>
<dd>Mark the end of options to the<tt>ioke</tt>script, anything after this are
options to be sent to the code running.</dd>
</dl><p>If you provide the name of a script file on the command line, it should come
after all the arguments to the<tt>ioke</tt>script. Everything after the script
will be added as data to the<code>System programArguments</code>cell. You can
use both one-line scripts with<tt>-e</tt>and specify a script file. If so, the
script file will be run after the one-line scripts.</p>
<a name="Interactive_mode"></a>
<h3><span class="mw-headline">Interactive mode</span></h3>
<p>If no code to execute has been specified to the<tt>ioke</tt>script,<a title="IIk" class="mw-redirect" href="/wiki/index.php/IIk">IIk - Interactive
Ioke</a>- will start. This is a REPL that allows the execution of arbitrary
code in a shell that immediately displays the result. The main difference
between running Ioke from a file and interactively is that the interactive
prompt will show a notice of the result of the last operation after each
execution. IIk will also invoke a debugger when a<a title="Conditions (not yet written)" class="new" href="/wiki/index.php?title=Conditions&action=edit&redlink=1">condition</a>is
encountered. This debugger gives you the possibility to inspect what happened
more closely. The final difference with IIk is that it does not execute code
directly in Ground - which the top level inside an Ioke script will do. This
difference is crucial, when considering namespacing issues.</p>
<p>IIk will try to use Readline through JLine if your platform supports it.</p>
<p>IIk will be more closely described later, but just to give you a glimpse,
this is how a small session could look like:</p>
<pre>
iik> "hello world" println hello world +> nil iik> 10 * 20 +> 200 iik> 3/2 +> 3/2 iik> 3/2 + 3/2 +> 3 iik> 3/2 * 3 +> 9/2 iik> foo = "hello" +> "hello" iik> foo +> "hello" iik> exit Bye.
</pre>
<p>When you see the prompt "iik>", you know that IIk is waiting for input.
The result of a computation is shown after the "+>" sigil. You can exit from
IIk by calling either "exit" or "quit". There is also a restart named "quit"
that can be invoked to quit IIk.</p>
<a name="Syntax"></a>
<h1><span class="mw-headline">Syntax</span></h1>
<p>Ioke has no keywords or statements. Everything is an expression composed of
a chain of messages. A piece of code is represented as a chain of messages that
links to the next message. The result of one message will be the receiver of
the next message, until a "." message is received. The "." message is a
terminator that throws away the current receiver. A newline will serve as a "."
message in the circumstances where it feels natural.</p>
<p>An informal BNF description of Ioke looks like this:</p>
<pre>
program ::= messageChain? messageChain ::= expression+ expression ::= message | brackets | literal | terminator literal ::= Text | Regexp | Number | Decimal | Unit message ::= Identifier ( "(" commated? ")" )? commated ::= messageChain ( "," messageChain )* brackets ::= ( "[" commated? "]" ) | ( "{" commated? "}" ) terminator ::= "." | "\n" comment ::= ";" .* "\n"
</pre>
<p>What isn't visible here is that all whitespace -- except for newlines --
will work only as separators of messages, and is otherwise ignored. That means
that message sending does not use the dot, as in most other languages. A phrase
such as<code>foo().bar(quux(42)).baaz()</code>would be expressed as<code>foo()
bar(quux(42)) baaz()</code>, or more succinctly<code>foo bar(quux(42))
baaz</code>in Ioke.</p>
<p>All the types of literals are actually turned into a message to create that
literal, so the canonical form of the message chain contains no literals, just
a message to create that literal. Any message can have zero or more arguments
given to it. Arguments are separated with comma. If there are no arguments to a
message, the parenthesis can be left off, but they need to be there if there
are arguments. Mostly any combination of characters can be used as an
Identifier, with some exceptions.</p>
<p>There used to be a parsing element called operators, but these have now been
included into identifiers. They are not parsed differently at all, but the
operator shuffling step will handle them differently. Specifically, operators
can be used in infix, including having different precedence rules. Assignment
is a specific form of operator which gets its own kind of shuffling. These are
both described below.</p>
<p>An identifier in Ioke can be one of several things. Ioke takes the rules for
Java identifiers, and adds some more to them. All Unicode letters and digits
can be part of an identifier, except for the first entry. Underscores are
allowed, just like in Java. Ioke also allows colons as an identifier.
Exclamation mark and question mark is allowed anywhere in the identifier except
for in the beginning. Identifiers can be broadly classified into identifiers
and operators, where operators can be any combination of several sigils. There
are also some special operators that have restrictions. These are: Opening and
close brackets are not allowed, except together with its counterpart, so [ is
not a valid identifier, while [] is. So is {}. () is not valid either. Two or
more dots is a valid identifier. A hash sign can be followed by any operator
char, but isn't parsed as an identifier by itself. Slash is not an operator
char, but can be used as it except in combinations that look like regular
expressions. The operator chars are: +, -, *, %, <, >, !, ?, ~, &, |,
^, $, =, @, ', ` and :. These can be combined together in any order, and any
number, except for the caveats noted before. That means the available operator
space is infinite, and very wide. Combinations of letters and operator
characters are generally not allowed, except for the exceptions with :, !
and ?. This is to make it possible to have infix operations without spaces in
some situations.</p>
<p>The two forms of brackets will get turned into a canonical form. Surrounding
comma-separated message chains with square brackets is the same as calling the
method [], giving it those message chains as argument. So [foo, bar, quux] is
exactly the same as [](foo, bar, quux). The same is true for curly
brackets.</p>
<p>Comments start with semicolon and end at the first newline. They can be used
mostly anywhere, except inside of literal texts. The hash sign followed by an
exclamation mark is also a comment, to allow the shebang line in Unix
scripts.</p>
<p>How and when the actual evaluation of messages happen depend on what kind
the message type is. If it's inactive, the value reflecting that cell will be
returned. If it's active, the cell will be activated and the result of that
activation returned. How the activation depends on what kind of code the cell
contains. The various kinds of code is described more closely in the chapter
about<a title="Guide:Code" href="/wiki/index.php/Guide:Code">code</a>.</p>
<a name="Literal_values"></a>
<h2><span class="mw-headline">Literal values</span></h2>
<p>Ioke currently contains four different kinds of literals. There is a fifth
quasi literal, that isn't exactly parsed as a literal, but will be evaluated
differently based on its name. These literals are texts, regular expressions,
integers and decimal numbers. Symbols are actually parsed as regular
identifiers, but they are handled a bit differently during evaluation.</p>
<a name="Text"></a>
<h3><span class="mw-headline">Text</span></h3>
<p>A literal text in Ioke is what is generally called strings in most
languages. As in most languages, text is written inside of double quotes. Any
characters are valid inside of those double quotes. That includes newlines - so
you can write a literal text that extends to several lines. There is an
alternate syntax for text when the value contains a lot of double quotes. As in
most other languages, several escapes are valid inside of a text. Escapes are
preceded by the backslash, and insert the character corresponding to the escape
values. These escapes are:</p>
<dl><dt>\b</dt>
<dd>Inserts the backspace character, that is represented in ASCII by the
decimal value 8.</dd>
<dt>\e</dt>
<dd>Inserts the character that is represented in ASCII by the decimal value 27.
This value is used for sending escape values to the TTYs in some operating
systems.</dd>
<dt>\t</dt>
<dd>Inserts the TAB character - ASCII decimal 9.</dd>
<dt>\n</dt>
<dd>Inserts the newline character - ASCII decimal 10.</dd>
<dt>\f</dt>
<dd>Inserts the form feed character - ASCII decimal 12.</dd>
<dt>\r</dt>
<dd>Inserts the carriage return character - ASCII decimal 13.</dd>
<dt>\"</dt>
<dd>Inserts the double quote character - ASCII decimal 34.</dd>
<dt>\\</dt>
<dd>Inserts the backslash character - ASCII decimal 92.</dd>
<dt>\[newline]</dt>
<dd>Inserts nothing at all. Used to escape necessary newlines, without having
them show up in the output text.</dd>
<dt>\#</dt>
<dd>Inserts a literal hash character - ASCII decimal 35.</dd>
<dt>\uABCD</dt>
<dd>Inserts the Unicode codepoint corresponding to the hexadecimal value of the
four characters following the "u". All four hexadecimal characters need to be
specified.</dd>
<dt>\7, \12, \316</dt>
<dd>Inserts the Unicode codepoint corresponding to the octal value of the one,
two or three octal characters. The maximum value allowed is \377, and the
minimum is obviously \0.</dd>
</dl><p>Ioke also supports an alternative text syntax that can be used when the text
in question contains many scare quotes. The alternative syntax starts with #[
and ends with ]. A right bracket will have to be escaped, but scare quotes
doesn't have to be.</p>
<p>The parsing of text will generate a message with name "internal:createText".
This message will get one argument that is the raw Java String corresponding to
the text.</p>
<p>Ioke allows automatic interpolation of arbitrary values in the same manner
as Ruby. It uses the same syntax for this, which is the #{} syntax inside a
text. These can be nested in any way. The elements will be parsed and sent as
arguments to the message with name "internal:concatenateText". So an Ioke text
such as "foo bar#{flux} will #{1+2}" will generate the message
internal:concatenateText("foo bar", flux, " will ", 1+(2), ""). As you can see,
there is a small amount of waste in the way this is generated -- but the simple
model makes it easy to understand. It's not guaranteed that this will remain
the same, although the message will definitely remain.</p>
<p>Some examples:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="st0">"foo"</span> <span class="st0">"flax<span class="es0">\</span>mux"</span> <span class="st0">"one two #{three}<span class="es0">\b</span>four"</span> <span class="sy0">#</span><span class="br0">[</span>you don't really <span class="st0">"#{1+2+3}"</span>believe that?<span class="br0">]</span>
</pre></div>
</div>
<a name="Regular_expressions"></a>
<h3><span class="mw-headline">Regular expressions</span></h3>
<p>Ioke has very capable regular expressions. Exactly what you can do with them
can be found further down in this guide. The literal syntax allows regular
expressions to be embedded in code directly. The syntax for this starts with a
#/ and ends with another /. The last slash can optionally be followed by some
flags that change the behavior of the expression. Regular expressions can also
use an alternative syntax that starts with #r[ and ends with ]. Just as with
Text, regular expressions can contain interpolation. This interpolation will be
transformed into regular expressions and then combined with the outer regular
expression. A few examples might be in order here:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="sy0">#//</span><span class="sy0">#</span>r<span class="br0">[</span><span class="br0">]</span> <span class="sy0">#/</span>foo<span class="sy0">/</span><span class="sy0">#</span>r<span class="br0">[</span>foo<span class="br0">]</span> <span class="sy0">#/</span>fo<span class="sy0">+/</span>x<span class="sy0">#</span>r<span class="br0">[</span>fo<span class="sy0">+</span><span class="br0">]</span>x <span class="sy0">#/</span>bla<span class="sy0">#</span><span class="br0">{</span><span class="st0">"foo"</span><span class="br0">}</span>bar<span class="sy0">/</span><span class="sy0">#</span>r<span class="br0">[</span>bla<span class="sy0">#</span><span class="br0">{</span><span class="st0">"foo"</span><span class="br0">}</span>bar<span class="br0">]</span>
</pre></div>
</div>
<p>The first example is an empty regular expression. The second is an
expression matching the word "foo". The third expression matches an "f"
followed with one or more "o". It also allows extended regular expression
syntax, due to the x flag. The flags supported in Ioke are x, i, u, m and s.
The meaning of these match the meaning of corresponding Ruby flags. Regular
expressions allow most of the same escapes as Ioke text. Specifically, these
escapes are supported: b, t, n, f, r, /, \ and newline. Unicode and octal
escapes also work. The fourth example shows the insertion of a literal text
inside of a regular expression.</p>
<p>Ioke regular expressions will be transformed into a call to
internal:createRegexp. This message expects two Java strings, one with the
actual pattern, and one with the flags.</p>
<a name="Integers"></a>
<h3><span class="mw-headline">Integers</span></h3>
<p>Ioke supports arbitrarily sized numbers. It also contains a numerical tower
that can be more closely explored in the reference documentation. The numerical
tower is based in Number. Number Real mimics Number. Number Rational mimics
Number Real, and so does Number Decimal. Finally, Number Integer and Number
Ratio both mimics Number Rational. The interesting parts of this tower is
Number Integer, which corresponds to integers, Number Ratio, which is any ratio
between two integers, and Number Decimal, which corresponds to decimal numbers.
These are arbitrarily sized and exact. There are no floats or doubles in Ioke.
There is also a potential place for Number Complex at the same layer as Number
Real, although complex numbers are not currently implemented. There are also
plans for implementing a unit system further down the line.</p>
<p>Literal integers can be written using either decimal or hexadecimal
notation. Hexadecimal notation begins with 0x or 0X and are then followed by
one or more hexadecimal letters. They can be either upper or lower case. A
decimal literal number is written using one or more decimal letters, but
nothing else.</p>
<p>There is no literal to create ratios - these can only be created by division
of integers. Negative numbers have no literal syntax, but preceding a number
with a minus sign will call the message - on the number and generate the
negative value.</p>
<p>A literal integer will be transformed into a call to internal:createNumber,
which takes one native Java String from which to create the number.</p>
<p>Some examples:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="nu0">1234444444444444444444444444444444444444235234534534</span> <span class="nu0">0</span> <span class="re1">0xFFFFF</span>
</pre></div>
</div>
<a name="Decimals"></a>
<h3><span class="mw-headline">Decimals</span></h3>
<p>Literal decimal values can be written either using exponential notation, or
using a decimal dot. A decimal dot notation can be combined with exponential
notation. Exponential notation starts with a number or a decimal number,
followed by lower or upper case E, followed by an optional sign, and then
followed by one or more decimal letters.</p>
<p>A literal decimal will be transformed into a call to internal:createDecimal,
which takes one native Java String from which to create the decimal.</p>
<p>Some examples:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="nu0">0.0</span> <span class="re2"><span class="re3">1E</span>6</span> <span class="re3">1E</span><span class="re0">-</span><span class="nu0">32</span> <span class="re2"><span class="nu0">23.444</span><span class="re3">5e</span>10</span>
</pre></div>
</div>
<a name="Symbols"></a>
<h3><span class="mw-headline">Symbols</span></h3>
<p>Symbols aren't exactly syntax, but they aren't exactly messages either. Or
rather, they are messages that will evaluate to the symbol that represent
themselves. Symbol is a kind in Ioke. There are two kinds of symbols - the
first one is simple symbols that can be parsed as is. The second is symbols
that can't be parsed as is. Symbols are preceded by a colon and then directly
followed by the symbol text. If it can't be parsed correctly, the value should
be surrounded by quotes, and this will be turned into a call to the method :,
which takes the text as argument. That means that you can actually get dynamic
symbols by calling the : method.</p>
<p>Some examples:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="re12"><span class="re13">:</span>foo</span> <span class="re12"><span class="re13">:</span>flaxBarFoo</span> <span class="re13">:</span><span class="st0">""</span> <span class="re13">:</span><span class="st0">"mux mex mox<span class="es0">\n</span>::::::::"</span>
</pre></div>
</div>
<a name="Operator_shuffling"></a>
<h2><span class="mw-headline">Operator shuffling</span></h2>
<p>One exception to the way message handling works in Ioke is operators. All
the so called operators in this section is possible to call directly in message
passing position too -- but to make it possible to use them in a more natural
way, the parsing step will handle them a bit differently, and then do a
shuffling step that actually takes operator precedence into account. So all the
common operators will generally work as you expect them to -- although I
recommend adding parenthesis when something is possibly unclear.</p>
<p>Ioke has a slightly larger amount of operators than most other languages.
Most of these are currently unused, but they are certainly available for use
for any purpose the programmer wants to use it for. Many adherents of other
languages (Java, I'm looking at you) claim that operator overloading is evil. I
don't believe that is true, seeing as how it works so well in Ruby, so Ioke
instead allow you quite large freedom with regards to operators.</p>
<p>The precedence rules for regular operators can be found in the cell 'Message
OperatorTable operators', which is a regular Dict that can be updated with new
values. The new values will obviously not take effect until the current code
has run, and a new parse is started.</p>
<p>Note that the below is only the operators that have defined precedence
rules. As noted in the section on syntax, you can use any operator you want
really. It is easy to add new precedences to the table, either temporarily or
permanently.</p>
<p>At the time of writing, the available operators - in order of precedence -
are these:</p>
<ul><li> !</li>
<li> ?</li>
<li>$</li>
<li>~</li>
<li>#</li>
<li>**</li>
<li>*</li>
<li>/</li>
<li> %</li>
<li>+</li>
<li>-</li>
<li><<</li>
<li>>></li>
<li><=></li>
<li>></li>
<li><</li>
<li><=</li>
<li>>=</li>
<li><></li>
<li><>></li>
<li>==</li>
<li> !=</li>
<li>===</li>
<li>=~</li>
<li> !~</li>
<li>&</li>
<li>^</li>
<li>|</li>
<li>&&</li>
<li> ?&</li>
<li>||</li>
<li> ?|</li>
<li>..</li>
<li>...</li>
<li>=></li>
<li><-></li>
<li>-></li>
<li>+></li>
<li> !></li>
<li>&></li>
<li> %></li>
<li>#></li>
<li>@></li>
<li>/></li>
<li>*></li>
<li> ?></li>
<li>|></li>
<li>^></li>
<li>~></li>
<li>->></li>
<li>+>></li>
<li> !>></li>
<li>&>></li>
<li> %>></li>
<li>#>></li>
<li>@>></li>
<li>/>></li>
<li>*>></li>
<li> ?>></li>
<li>|>></li>
<li>^>></li>
<li>~>></li>
<li>=>></li>
<li>**></li>
<li>**>></li>
<li>&&></li>
<li>&&>></li>
<li>||></li>
<li>||>></li>
<li>$></li>
<li>$>></li>
<li>+=</li>
<li>-=</li>
<li>**=</li>
<li>*=</li>
<li>/=</li>
<li> %=</li>
<li>and</li>
<li>nand</li>
<li>&=</li>
<li>&&=</li>
<li>^=</li>
<li>or</li>
<li>xor</li>
<li>nor</li>
<li>|=</li>
<li>||=</li>
<li><<=</li>
<li>>>=</li>
<li><-</li>
<li>return</li>
</ul><p>And as mentioned above, all of these can be used for your own purpose,
although some of them already have reserved meanings. This document will cover
most of the used operators, while the rest can be found in the reference.</p>
<p>Since this operator shuffling happens, that also means that an Ioke program
has a canonical inner form that can differ from the source text. When you use
introspection of any kind, you will get back that canonical form which might
not look exactly like you expected. Similarly, if you ask some code to print
itself, it will use the canonical form instead of the operator skin. Macros
that modify message chains should work against the canonical form, and nothing
else.</p>
<p>What an operator does depends on the result of sending the message of that
name to the receiver, just like regular messages. In fact, to Ioke there really
isn't any difference, except that the parsing takes special notice about
operators and assignment operators.</p>
<a name="Assignment_shuffling"></a>
<h2><span class="mw-headline">Assignment shuffling</span></h2>
<p>Much like with regular operators, trinary - assignment - operators are
subject to a kind of shuffling. This shuffling differs from regular operator
shuffling, in that it will shuffle around two things - the left hand side and
the right hand side. This is true for every assignment operator except for the
unary ones, which will only reshuffle one message.</p>
<p>A few examples might make the translation easier to perceive. The first item
is the readable form, while the second form is the canonical form:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
foo<span class="sy0">=</span><span class="nu0">1</span><span class="sy0">+</span><span class="nu0">2</span><span class="sy0">=</span><span class="br0">(</span>foo,<span class="nu0">1</span><span class="sy0">+</span><span class="br0">(</span><span class="nu0">2</span><span class="br0">)</span><span class="br0">)</span> <span class="re9"><span class="re11">Ground</span></span>foo<span class="sy0">*=</span><span class="st0">"text"</span><span class="re9"><span class="re11">Ground</span></span><span class="sy0">*=</span><span class="br0">(</span>foo,<span class="st0">"text"</span><span class="br0">)</span> bar foo<span class="br0">(</span><span class="nu0">123</span><span class="br0">)</span><span class="sy0">=</span><span class="nu0">42</span>bar<span class="sy0">=</span><span class="br0">(</span>foo<span class="br0">(</span><span class="nu0">123</span><span class="br0">)</span>,<span class="nu0">42</span><span class="br0">)</span> flux<span class="sy0">++</span><span class="sy0">++</span><span class="br0">(</span>flux<span class="br0">)</span>
</pre></div>
</div>
<p>These examples show some more advanced details -- specifically the fact that
assignment operators generally work on "places", not on names or cells. This
will be more explored in the chapter on<a title="Guide:Assignment" href="/wiki/index.php/Guide:Assignment">assignment</a>. The important thing to
notice from the above examples is that for most assignments two things will be
rearranged. For the unary operators only one thing will be moved.</p>
<p>Just as with regular operators, the assignment operators have information in
the 'Message OperatorTable' cell. The specific cell is 'Message OperatorTable
trinaryOperators', and it matches an assignment operator to either the integer
1, or the integer 2. Everything with 1 will be matched as being unary
assignment.</p>
<p>The currently available assignment operators are:</p>
<ul><li>=</li>
<li>++</li>
<li>--</li>
<li>+=</li>
<li>-=</li>
<li>/=</li>
<li>**=</li>
<li>*=</li>
<li> %=</li>
<li>&=</li>
<li>&&=</li>
<li>|=</li>
<li>||=</li>
<li>^=</li>
<li><<=</li>
<li>>>=</li>
</ul><p>Just as with regular operators, what an assignment operator does depend on
what the result is from sending the message of that name to the receiver
object, just like with any type of message.</p>
<a name="Inverted_operators"></a>
<h2><span class="mw-headline">Inverted operators</span></h2>
<p>In addition to the regular binary operators and the trinary assignment
operators, Ioke also sports inverted operators. These aren't actually used
anywhere in the core distribution, but they might be useful at some time or
another. The basic idea is that sometimes you want to have the right hand side
of an expresssion become the receiver of an operator call, and the left hand
side become the argument to the operator. Inverted operators allow this.</p>
<p>As with both the binary and trinary operators, you can find and update
information about inverted operators in the cell 'Message OperatorTable
invertedOperators'. To make this a little less abstract, let us look at two
simple examples and what they translate into:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="st0">"foo"</span><span class="re13">:</span><span class="re13">:</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span><span class="br0">]</span>map<span class="br0">(</span>asText<span class="br0">)</span><span class="co1">;; will be translated to</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span><span class="br0">]</span>map<span class="br0">(</span>asText<span class="br0">)</span><span class="re13">:</span><span class="re12"><span class="re13">:</span><span class="br0">(</span></span><span class="st0">"foo"</span><span class="br0">)</span> <span class="co1">;; provided we have an inverted</span><span class="co1">;; operator called 'doit'</span>abc foo quux doit another time<span class="co1">;; will be translated to</span>another time doit<span class="br0">(</span>abc foo quux<span class="br0">)</span>
</pre></div>
</div>
<a name="Execution_model"></a>
<h1><span class="mw-headline">Execution model</span></h1>
<p>The way an Ioke program works is very simple. Everything executes based on
two things. The first is the context, or the ground, and the second is the
receiver. The first message sent in each message chain will have the ground as
receiver. The default ground in Ioke source files is an object
called<code>Ground</code>. This object is in the mimic chain for most regular
objects created in Ioke, which means that things defined at the top level will
generally be available in most objects. Inside of methods and blocks, the
ground will be different. Exactly in what way is defined by the type of code
executing.</p>
<p>Every message in a chain will be sent to the receiver of that message. That
receiver is the result of the last message, or the current ground if there was
no previous message, or if that previous message was a terminator. So Ioke code
like<code>foo bar(flux bar) quux</code>involves 5 different messages.</p>
<ol><li>The message<code>foo</code>is sent to<code>Ground</code>, which is the
current ground and also the default receiver.</li>
<li>The message<code>bar</code>is sent to the result of
the<code>foo</code>message. The value returned will be activated.</li>
<li>The cell<code>bar</code>contains a method in this case, and that method
expects one argument, so that forces evaluation of the arguments.</li>
<li>The message<code>flux</code>is sent to<code>Ground</code>, since it's the
ground and there is no prior message inside of an argument list.</li>
<li>The message<code>bar</code>is sent to the result of
the<code>flux</code>message.</li>
<li>The result of the<code>bar</code>message is used as the argument value
given to the outside<code>bar</code>method.</li>
<li>The message<code>quux</code>is sent to the result of the
initial<code>bar</code>message.</li>
<li>The result of the<code>quux</code>message is thrown away, unless this code
is part of a larger piece of code.</li>
</ol><p>This description generally describes what happens in the case of this code.
The more general control flow is this:</p>
<ol><li>A message is encountered</li>
<li>If the message is a symbol message, the corresponding symbol will be
returned.</li>
<li>Otherwise the name of the message will be looked up in the receiver, or in
the receivers mimics.</li>
<li>If the name is found and is not activatable, the value of that name (the
cell) is returned.</li>
<li>If the name is found and is activatable, it will be activated, with the
current ground, receiver and message sent to the activatable object.</li>
<li>If the name is not found, a second search is done for the
name<code>pass</code>. If a pass is found, use that instead of the name of the
original message, and go back to 4.</li>
<li>If a pass is not found, signal a<a title="http://ioke.org/dok/kinds/Condition/Error/NoSuchCell.html" class="external text" href="http://ioke.org/dok/kinds/Condition/Error/NoSuchCell.html"><code>Condition
Error NoSuchCell</code></a>condition.</li>
</ol><p>Exactly what happens when an object is activated depends on what kind of
code gets activated. It's really up to the method, block or macro to handle
evaluation of arguments in any way it likes - including not evaluating them.
For a description of the default models available, see the chapter on<a title="Guide:Code" href="/wiki/index.php/Guide:Code">code</a>.</p>
<a name="Objects"></a>
<h1><span class="mw-headline">Objects</span></h1>
<p>The object model of Ioke is quite simple. Everything in Ioke is an object
that follows these same rules. An object is something with an identity. It can
have zero or more mimics, and zero or more cells. An object can also have a
documentation text. Some objects can have a native data component. This acts
more or less like a hidden cell that contains information that can't be
directly represented in Ioke - for example the actual text in a Text. Or the
actual number in a Number. Or the actual regular expression in a Regexp. These
objects are the core types that contain primitive information.</p>
<p>A cell is the main way of representing data in Ioke. A cell has a name and a
value. Every value in Ioke is a cell - every time you send a message, a cell is
looked up for the value of that cell. Cells can contain any kind of data. In
other languages, cells are generally called properties or slots. They are quite
close to instance variables that also can contain methods. Cells can be added
and removed at any time during runtime.</p>
<p>A mimic could also be called the parent of the object. Ioke is a prototype
based language, which means that there is no distinction between classes of
objects, and the objects themselves. In fact, any object can be used as the
"class" of a new object. The word for that is mimicking, since the word "class"
loses it's meaning in this kind of language. It's most common for an object to
mimic one other object, at least initially. It's impossible to create an object
that doesn't mimic anything, but you can remove all mimics for an object after
the fact. You can also add more mimics. This turns out to be useful to
represent shared functionality in the manner of Ruby mixins, for example. The
actual effect of a mimic is that when a cell can't be found in the current
object, all mimics will be searched for that cell (depth-first). So all cells
available in an object's mimic is available to the object too. This is the
inheritance part of Object-Oriented Programming.</p>
<p>In many places you will find the word "kind" being used. A Kind is by
convention an object that is used primarily to use as a mimic for other
objects. The convention is that kinds are named with an initial upper case
letter, while everything else starts with a lower case letter. The assignment
process of Ioke also uses this convention to automatically set a cell called
"kind" on any object that gets assigned to a name matching this convention.</p>
<p>The rest of this chapter will discuss the kinds that are the basis of the
object system.</p>
<a name="Base"></a>
<h2><span class="mw-headline">Base</span></h2>
<p>The kind called Base is the top of the mimic chain. It's not generally
useful in itself as it only defines the bare minimum of cells to make it
possible to add new cells to it, mimic it, and so on. But if you want an object
that is possible to use but not include most of the other stuff, Base is place
to begin. Be careful when defining methods in Base, since it doesn't have
access to most of the namespace. In fact, it doesn't even know about its own
name. Base can act as a kind of blank slate, if needed, but it's probably
easier to just create a regular object and remove all mimics from it after the
fact.</p>
<p>Base defines these cells:</p>
<dl><dt>kind</dt>
<dd>returns the kind of the object, which is "Base".</dd>
<dt>notice</dt>
<dd>returns the short notice of the object, which is "Base". Refer to<a title="http://ioke.org/#introspection" class="external text" href="http://ioke.org/#introspection">Introspection</a>for more information about
notice.</dd>
<dt>=</dt>
<dd>Takes two values, the first a place and the second a value, and assigns the
place named to that value. Refer to<a title="http://ioke.org/#assignment" class="external text" href="http://ioke.org/#assignment">Assignment</a>for more
information about it.</dd>
<dt>==</dt>
<dd>Compares this object against the argument. Returns true if they are the
same, otherwise false.</dd>
<dt>cell</dt>
<dd>Takes one argument that should be the name of a cell that exists, and
returns the value of the cell unactivated.</dd>
<dt>cell=</dt>
<dd>Sets a cell to a specific value. Used to set cells that can't be set using
the regular assignment model. Refer to<a title="http://ioke.org/#assignment" class="external text" href="http://ioke.org/#assignment">Assignment</a>for more
information about it.</dd>
<dt>cell?</dt>
<dd>Takes one argument that should be the name of a cell to check if it exists
in this objects mimic chain.</dd>
<dt>cellNames</dt>
<dd>Returns a List containing the names of all cells this object contains.</dd>
<dt>cells</dt>
<dd>Returns a Dict with all cells this object contains. The key is the name and
the value is the cell value.</dd>
<dt>cellOwner</dt>
<dd>Returns the closest mimic that has a cell with the name given as argument
to the message. A condition will be signalled if you try to find the owner of a
cell that doesn't exist in this mimic tree. This method will only return the
closest cell owner for the named cell. It will not use "pass", so it's the
responsibility of pass-implementers to make it return a correct result for
those names.</dd>
<dt>cellOwner?</dt>
<dd>Takes the name of a cell and returns true if the receiver of the message
defines a cell by that name, otherwise false. Note that there can be more than
one cell owner in a message chain. This just returns true if the current
receiver is the closest one.</dd>
<dt>removeCell!</dt>
<dd>Removes the named cell from the current object. This means that if the
current cell shadowed cells in mimics, those can be called again. It only
removes a cell if the receiver is the owner of that cell. Otherwise it is an
error to call this method.</dd>
<dt>undefineCell!</dt>
<dd>Makes it impossible to find a cell from the receiver. In all ways it looks
like this cell doesn't exist in the mimic chain at all, even if mimics define
several implementations of it. The use of undefining can make an object
conceptually totally clean from cells, although it might be hard to use the
objec after that. An interesting side-effect of the way these methods work is
that removeCell! can be used to remove the undefine. So if you call removeCell!
with a cell name and a receiver that has been called with undefine earlier,
that undefine-status will be removed, and access to mimic versions of the cell
will be possible again. Look at the specs for a better understanding.</dd>
<dt>documentation</dt>
<dd>Returns the documentation text for this object, or nil if no documentation
exists for it.</dd>
<dt>documentation=</dt>
<dd>Sets the documentation text for this object.</dd>
<dt>mimic</dt>
<dd>Returns a newly created object that has the receiver as mimic. This is the
magic way of creation new objects in Ioke. It is also the<em>ONLY</em>way to do
it.</dd>
</dl><p>All of these methods are described further in the reference.</p>
<a name="Ground"></a>
<h2><span class="mw-headline">Ground</span></h2>
<p>As mentioned above, Ground is the default ground/context for evaluation.
Ground IokeGround and JavaGround, and IokeGround mimics Base and
DefaultBehavior. IokeGround is special in that this is the place where all top
level kinds are defined. If you want to create a top level kind, you should put
it in IokeGround. If you take a look in IokeGround, you will see that it
contains cells for Text, Dict, List, Base, Origin, itself and many other. Ioke
doesn't have any global state at all, but IokeGround is as close as it gets.
IokeGround and Ground should in most cases not be mimicked directly.</p>
<p>JavaGround is the place where all Java integration support is integrated
into Ioke.</p>
<a name="Origin"></a>
<h2><span class="mw-headline">Origin</span></h2>
<p>Origin should be the place where most objects in Ioke start from. It is
specifically created to be the origin of objects. As such it doesn't contain
many cells for itself, but it mimics Ground and has access to everything from
Base, DefaultBehavior and Ground in that way. When adding new more or less
global functionality, Origin is probably the best place to put it. Currently,
the only cells Origin contains is for purposes of printing itself.</p>
<p>Origin also happens to be the point where initialization is defined. This is
really done as an aspect on 'mimic'. If you want an object to be able to be
initialized every time a new mimic of it is created, just create a method
called initialize in your kind. It will be called by the mimic-aspect. Any
arguments given to mimic will be ignored and passed along to initialize. An
example:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="re11">Foo</span><span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span><span class="re11">Foo</span>initialize<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span><span class="st0">"New foo created!"</span>println<span class="br0">)</span><span class="re11">Foo</span><span class="re6">mimic</span><span class="re11">Foo</span><span class="re6">mimic</span> <span class="re11">Foo</span>initialize<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>arg1, key<span class="re12"><span class="re13">:</span>,</span><span class="re6">self</span>value<span class="sy0">=</span><span class="br0">[</span>arg1, key<span class="br0">]</span><span class="br0">)</span><span class="re11">Foo</span><span class="re6">mimic</span><span class="br0">(</span><span class="nu0">42</span>, key<span class="re13">:</span><span class="nu0">15</span><span class="br0">)</span><span class="re11">Foo</span><span class="re6">mimic</span><span class="br0">(</span>key<span class="re13">:</span><span class="st0">"blarg"</span>,<span class="nu0">42</span><span class="br0">)</span>
</pre></div>
</div>
<p>There is nothing special with the initialize method, so if you want more
initialization to happen in a deep hierarchy, you will have to use super-calls
and so on.</p>
<a name="DefaultBehavior"></a>
<h2><span class="mw-headline">DefaultBehavior</span></h2>
<p>DefaultBehavior is a mixin - meaning it should never be the sole mimic of an
object. Mixins are generally not grounded in Base, and doesn't contain most of
the things you would expect from an object. DefaultBehavior contain almost all
the general methods you use when programming Ioke. It contains the internal
methods to create values from literals, and most other functionality specified
in this document. In short, DefaultBehavior is the work horse, and you should
have a pretty good reason to not have it in the mimic chain of an object. Since
Ground mimics DefaultBehavior, any object you create from Origin, will have
DefaultBehavior in its mimic chain.</p>
<a name="nil.2C_true.2C_false"></a>
<h2><span class="mw-headline">nil, true, false</span></h2>
<p>The three values nil, true and false are the only values that are considered
kinds, even though they start with lower case letters. They are not like the
other kinds in the other important way either - these values can not be
mimicked, and you will get a condition if you try it. The reason is that Ioke's
basic boolean system revolves around these values. It is not entirely certrain
that these values will forever be the only boolean values, but for now they
are. nil should be used to represent the absence of a value, including the
absence of a reasonable return value. false is the quintessential false value,
and true is the quintessential true value. The value true isn't strictly
necessary since any value except for nil and false are true. This notion of
truthness mimics Ruby. The cells nil, true and false are defined in Ground, and
they can actually be overridden or changed - but I don't recommend it. I can
guarantee lots of chaos and non-working programs from doing it. More info on
how these values interact can be found in the section on<a title="http://ioke.org/#comparison" class="external text" href="http://ioke.org/#comparison">Comparison</a>.</p>
<a name="Assignment"></a>
<h1><span class="mw-headline">Assignment</span></h1>
<p>Superficially, Ioke's assignment model is quite simple. But there exists
some subtleties too. One of the main reasons for this is that assigning a cell
that doesn't exist will create that cell. Where it gets created is different
based on what kind of context the assignment happens in. The main difference
here is between a method activation context, or a lexical block context.</p>
<p>Ioke also supports assignment of places, which makes assigning much more
flexible. A third feature of Ioke assignment is that it will check for the
existence of an assignment method before assigning a specific name. This
chapter will make all these things clear, and show some examples.</p>
<p>Let's start with a small example of simple assignment:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
foo<span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span>foo x<span class="sy0">=</span><span class="nu0">42</span>foo y<span class="sy0">=</span><span class="nu0">13</span>foo x<span class="sy0">+=</span><span class="nu0">2</span>
</pre></div>
</div>
<p>The first line creates a new Origin mimic, and then assigns that to the name
foo. Since this code executes at the top level, "foo" will be a new cell
created in Ground. The second line creates a new cell called "x" inside the
"foo" object. It gets assigned the value 42. The third line creates a "y" cell,
and the fourth line sends the += message, which will first call +, and then
assign using =. So at the end of this program, "foo" will contain two cells:
"x" with value 44, and "y" with value 13. As mentioned above, cells get created
the first time they are assigned to. If you need to create a cell in a specific
object, just namespace it. For example, if you want to make sure that you
create a cell in Ground, just do "Ground foo = 42".</p>
<p>Inside of a method, the situation is exactly the same. If you assign
something, it will be assigned in the current context, which is the local
activation context (meaning it's the place where local variables are
available). There are two situations where this doesn't hold true. The first
one is within the special method "do". This method will take any code as
argument and execute that with the receiver of the "do" message as the
ground/context of the code inside it. That means "do" is a good way to create
new cells inside an object.</p>
<p>This is a bit academic, so lets take a look at an example:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="re11">Foo</span><span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span><span class="re11">Foo</span>x<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span> <span class="co1">;; this creates a local variable in the method activation</span> foo<span class="sy0">=</span><span class="nu0">42</span><span class="br0">)</span> <span class="re11">Foo</span><span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span><span class="re11">Foo</span>do<span class="br0">(</span> <span class="co1">;; this creates the cell foo inside of Foo</span> foo<span class="sy0">=</span><span class="nu0">42</span><span class="br0">)</span>
</pre></div>
</div>
<p>Here you can see a method defined called x. This method will just create a
new local cell, which means calling the method will not make any difference on
its receiver at all. The call to "do" in contrast will immediately execute the
code inside it, and this code will create the cell "foo" inside of "Foo".</p>
<p>The second exception to the general rule is when executing inside of a
lexical context. A lexical context is basically established inside of a block,
but can also be created transparently when sending code to a method. A lexical
block will try to not create new cells. When you assign a cell without a
specific place to assign it, a lexical block will first see if there is any
cell with that name further out, and if so it will make the assignment there
instead. Only when no such cell exists, a new cell will be created in the
lexical context. This code shows this in action:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
x<span class="sy0">=</span><span class="nu0">42</span><span class="re8">fn</span><span class="br0">(</span>x<span class="sy0">=</span>43. y<span class="sy0">=</span><span class="nu0">42</span><span class="br0">)</span>call x<span class="co1">;; => 43</span>y<span class="co1">;; => Condition Error NoSuchCell</span>
</pre></div>
</div>
<p>The "fn" message creates a new lexical block. The chapter on<a title="http://ioke.org/#code" class="external text" href="http://ioke.org/#code">code</a>will talk more about this. But as you can see,
this block assigns 43 to the cell "x", and 42 to the cell "y". But since the
cell "y" doesn't exist, it will only be created inside the lexical context,
while "x" exists outside, and will be assigned a new value instead. The basic
idea is that code like this should behave like you expect it to behave.</p>
<p>The canonical form of assignment is a bit different from the way you usually
write code in Ioke. The section on the syntax of assignments talked a bit about
this. Specifically, something like "foo = 42" will get translated into "=(foo,
42)". That also means that assignment is just a regular method call, and can be
overridden or removed just like any other method. That is exactly how both
lexical context, and local method context make it possible to have different
logic here. This is true for all assignment operators.</p>
<p>All assignment operators take as their first argument the place to assign
to. This place will be unevaluated. Only the second argument to an assignment
will be evaluated. In most cases, a place is the same thing as a cell name, but
it doesn't have to be. Let's look at the case of assigning a cell with a
strange name. Say we want to assign the cell with the no name. We can do it
like this:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
cell<span class="br0">(</span><span class="st0">""</span><span class="br0">)</span><span class="sy0">=</span><span class="nu0">42</span>
</pre></div>
</div>
<p>What happens here is a bit subtle. Since the left hand side of the
assignment takes arguments, the "=" method figures out that the assignment is
not to a simple cell name, but to a place. The parsing step will change
"cell("") = 42" into "=(cell(""), 42)". Notice here that the argument comes
along into the specification of the place. When this happens, the assignment
operator will not try to create or assign a cell - instead it will in this case
call the method cell=. So "cell("") = 42" will ultimately end up being the same
as "cell=("", 42)". This way of transforming the name will work the same for
all cases, so you can have as many arguments as you want to the place on the
left hand side. The equals sign will be added to the method name, and a message
will be sent to that instead.</p>
<p>This makes assignment of places highly flexible, and the only thing you need
to do is implement methods with the right names. This feature is used
extensively in Lists and Dicts to make it easy to assign to specific indexes.
So, say we have a list called x. Then this code: "x[13] = 42" will be
transformed into "x =([](13), 42)" which will in turn be transformed into "x
[]=(13, 42)". Ioke lists also has an at= method, so you can do "x at(13) = 42"
which will call at=, of course.</p>
<p>The second transformation that might happen is that if you try to assign a
cell that has an assigner, you will call that assigner instead of actually
assigning a cell. So, for example, if you do "foo documentation = 42", this
will not actually create or assign the cell "documentation". Instead it will
find that Base has a cell called "documentation=", and instead send that
message. So the prior code would actually be equivalent to "foo
documentation=(42)".</p>
<p>All of these assignment processes together make it really easy to take
control over assignment, while still making it very obvious and natural in most
cases.</p>
<a name="Let"></a>
<h2><span class="mw-headline">Let</span></h2>
<p>Sometimes you really need to change the value of something temporarily, but
then make sure that the value gets set back to the original value afterwards.
Other situations often arise when you want to have a new name bound to
something, but maybe not for a complete method. This might be really useful to
create closures, and also to create localized helper methods. For example, the
Ioke implementations for Enumerable use a helper syntax macro. This macro is
bound temporarily, using a let form. This ensures that the syntax doesn't stay
around and pollute the namespace.</p>
<p>A let in Ioke can do two different things, that on the surface look mostly
the same but are really very different operations. The first one is to
introduce new lexical bindings, and the second is to do a dynamic rebind of a
specific place. The easiest way of thinking about it is that the lexical
binding introduces a local change or addition to the available names you're
currently using, while a dynamic rebinding will change the global state
temporarily, and then set it back.</p>
<p>This sounds really academic, so let us go for some examples. We begin with
lexical bindings.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="co1">;; put everything in a method to show explicit scope</span>foo<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>x, y, x println<span class="co1">; => argument value of x</span> let<span class="br0">(</span>x,<span class="nu0">14</span>, x println<span class="co1">; => 14</span> <span class="br0">)</span> x println<span class="co1">; => argument value of x</span> y println<span class="co1">; => argument value of y</span> y<span class="sy0">=</span><span class="nu0">13</span> y println<span class="co1">; => 13</span> let<span class="br0">(</span>y,<span class="nu0">14</span>, y println<span class="co1">; => 14</span> <span class="br0">)</span> y println<span class="co1">; => 13</span> z println<span class="co1">; will signal condition</span> let<span class="br0">(</span>z,<span class="nu0">42</span>, z println<span class="co1">; => 42</span> <span class="br0">)</span> z println<span class="co1">; will signal condition</span><span class="br0">)</span>
</pre></div>
</div>
<p>Here a new method is created that has two arguments, x and y. The first
let-expression will create a new scope where a binding from x to 14 is
established. This binding is valid until the end of the let-form (but it can be
changed, doing an assignment will set the value to something else, but only
until the end of the let form). The same thing is true with y. We can change
the value of y outside of the let form. That changes the actual argument
variable. But a let form that binds y will only have it active for a limited
time. Finally, a let form can also create totally new variables, as when
creating z.</p>
<p>I didn't show any example of it, but the first part of a let-name can be any
kind of place, not just a simple name. Anything you can use with =, can be used
as a name for let. So you could do something like let(cell(""), 42, nil) if you
wanted to.</p>
<p>OK, so that's lexical binding. What about dynamic rebinding? The main
difference in a dynamic binding is that the scope you work in is something that
is referencable from other scopes. In most cases this will be global places,
but not necessarily. You can also rebind cells inside of other objects with the
dynamic binding feature.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
bar<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span> let<span class="br0">(</span><span class="re9"><span class="re11">Origin</span></span>foo,<span class="re8">method</span><span class="br0">(</span><span class="st0">"haha"</span>println<span class="br0">)</span>, <span class="st0">"x"</span>foo <span class="re9"><span class="re11">Origin</span></span>foo <span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">]</span>foo <span class="br0">)</span> let<span class="br0">(</span><span class="re9"><span class="re11">Text</span></span>something,<span class="nu0">42</span>, <span class="st0">"abc"</span>something println<span class="co1">; => 42</span> <span class="br0">)</span> <span class="st0">"abc"</span>something println<span class="co1">; will signal condition</span> let<span class="br0">(</span><span class="re9"><span class="re11">Text</span></span>inspect,<span class="st0">"HAHA"</span>, <span class="st0">"foo bar qux"</span>inspect println<span class="co1">; => "HAHA"</span> <span class="br0">)</span> <span class="st0">"foo bar qux"</span>inspect println<span class="co1">; => #["foo bar qux"]</span> let<span class="br0">(</span><span class="re9"><span class="re11">Text</span></span>asRational,<span class="re8">method</span><span class="br0">(</span><span class="nu0">42</span><span class="br0">)</span>, <span class="br0">(</span><span class="nu0">3</span><span class="sy0">+</span><span class="st0">"haha"</span><span class="br0">)</span>println<span class="co1">; => 45</span> <span class="br0">)</span><span class="br0">)</span>
</pre></div>
</div>
<p>This example actually changes things quite a lot. The first and second
examples introduce new cells into existing places, uses them and then doesn't
do anything. The third example actually overrides an existing cell in Text -
inspect - and then uses it inside of the let code. Finally, after the let block
is over, we see that the original method is back. The fourth example shows that
our changes with let actually are global. There is no asRational on Text, but
we add it temporarily and can then use it in arithmetic with numbers. This is
once again a temporary change that will disappear afterwards.</p>
<p>Ioke's let-form is incredibly powerful, and it allows very nice temporal and
localized changes. Of course, it's a power that can be abused, but it gives
lots of interesting possibilities for expression.</p>
<a name="Control_flow"></a>
<h1><span class="mw-headline">Control flow</span></h1>
<p>Ioke has some standard control flow operators, like most other languages. In
Ioke, all of these are regular method calls though, and they can usually be
implemented in terms of Ioke. This chapter will chiefly talk about comparisons,
conditionals and iteration constructs.</p>
<a name="Comparison"></a>
<h2><span class="mw-headline">Comparison</span></h2>
<p>There are several comparison operators in Ioke, but the most important is
called the spaceship operator. This operator is <=>. It takes one
argument and returns -1, 0 or 1 depending on the ordering of the receiver and
the argument. If the two objects can't be compared, it returns nil. If you
implement this operator and mixin Mixins Comparing, you get the operators
==, !=, <, <=, > and >= implemented in terms of the spaceship
operator. There are two other common operators in Ioke. The first =~, which can
also be called the match operator. It's only implemented for Regexp right now.
The === operator also exists, but isn't implemented for most objects. This
operator doesn't do much right now, but is planned to be the basis of a
Ruby-like case-statement further down the line. The contract of comparison
operators is that they should return a true value (not necessarily the true) if
the comparison is true, and otherwise return either false or nil.</p>
<p>The contract for === should be matching or not matching. It is among other
things used in Ranges to see if something is included in that range or not.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
iik<span class="sy0">></span><span class="nu0">1</span><span class="sy0">+</span><span class="nu0">2</span><span class="sy0"><</span><span class="nu0">4</span><span class="sy0">+></span><span class="re6"><span class="re7">true</span></span> iik<span class="sy0">></span><span class="nu0">3</span><span class="sy0">+</span><span class="nu0">2</span><span class="sy0"><</span><span class="nu0">4</span><span class="sy0">+></span><span class="re6"><span class="re7">false</span></span> iik<span class="sy0">></span><span class="st0">"foo"</span><span class="sy0"><=></span><span class="st0">"fop"</span><span class="sy0">+></span><span class="re0">-</span><span class="nu0">1</span>
</pre></div>
</div>
<a name="Conditionals"></a>
<h2><span class="mw-headline">Conditionals</span></h2>
<p>Ioke has two different ways of doing conditionals. The first one is the
default, and is also the traditional conditional from other languages. The
second version looks more like Smalltalk conditionals.</p>
<p>As with everything else, these conditionals are all methods, and can be
overridden and changed if need be. They can also be polymorphic.</p>
<p>The default conditionals are called "if" and "unless". They both take an
initial evaluated argument that is used to check which branch should be taken.
The "if" method will execute it's second argument if the first argument is
true, and the third argument if the first argument is false. The "unless"
method does the inverse -- executing the second argument if the first argument
is false, and the third argument if the first argument is true. One or both of
the branches can be left out from the statement. If no else-part is around and
the conditional part evaluates to a false value, that false value will be
returned.</p>
<p>A few examples are in order:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
if<span class="br0">(</span><span class="nu0">42</span><span class="sy0"><</span><span class="nu0">43</span>, <span class="st0">"wow, math comparison works"</span>println, <span class="st0">"we have some serious trouble"</span>println<span class="br0">)</span> if<span class="br0">(</span><span class="nu0">42</span><span class="sy0"><</span><span class="nu0">43</span>, <span class="st0">"wow, math comparison works"</span>, <span class="st0">"we have some serious trouble"</span><span class="br0">)</span>println <span class="re7">unless</span><span class="br0">(</span><span class="nu0">42</span><span class="sy0"><</span><span class="nu0">43</span>, <span class="st0">"convoluted math"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>It is good style to not use "unless" with an else branch. It generally tends
to not be so readable that way. Remember that "if" and "unless" return their
values, which means they are expressions like everything else. The middle
example show that you can just call println on the result of the if-call,
instead of doing it twice inside. This is also good style. Assigning the result
of an if-call is likewise not a problem.</p>
<p>In some languages you see a pattern such as "if(foo =
someExpensiveMethodCall(), foo println)", where a variable is assigned in the
condition evaluation so the value doesn't have to be evaluated twice. This
works in Ioke too, but there is a more idiomatic way of doing it. Both "if" and
"unless" establish a lexical context, where a variable called "it" is
available. This variable will be bound to the result of the conditional. So the
above idiom could instead be written "if(someExpensiveMethodCall(), it
println)". This is the preferred way of handling regular expression
matching.</p>
<p>The Smalltalk inspired way of doing conditionals rest on the methods called
ifTrue and ifFalse. Both of these methods are only defined on true and false,
which means they are not as general as the if and unless statements. They can
also be chained together, so you can write:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="br0">(</span><span class="nu0">42</span><span class="sy0"><</span><span class="nu0">43</span><span class="br0">)</span>ifTrue<span class="br0">(</span><span class="st0">"wowsie!"</span>println<span class="br0">)</span>ifFalse<span class="br0">(</span><span class="st0">"oh noes"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>As should be obvious from these examples, these conditionals can not return
any value. They must only rely on side effects to achieve anything.</p>
<p>Ioke also supports the expected short circuiting boolean evaluators. They
are implemented as regular methods and are available on all objects. All of the
expected combinators are available, including "and", "&&", "or", "||",
"xor", "nor" and "nand".</p>
<a name="cond"></a>
<h3><span class="mw-headline">cond</span></h3>
<p>Ioke doesn't have any else-if expression, which means that when you want to
do several nested checks, you end up with lots of indentation. Cond is a macro
that expands to that code. The code using cond will not have more indentation,
which means it might be easier to read. A cond has one or more conditional
expressions followed by an action part to execute if that condition is true. As
soon as a condition has evaluated to true cond will not evaluate any more
conditions or actions. If no conditions evaluate to true, nil will be returned,
unless there is an action part following the last action-part. In other terms,
if the cond-expression has an odd number of arguments, the last argument is the
default case to execute if nothing else matches.</p>
<p>Some examples of cond:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
cond<span class="br0">(</span> x<span class="sy0">==</span><span class="nu0">1</span>,<span class="st0">"one"</span>println, x<span class="sy0">==</span><span class="re0">-</span><span class="nu0">1</span>,<span class="st0">"minus one"</span>println, x<span class="sy0"><</span><span class="nu0">0</span>,<span class="st0">"negative"</span>println, x<span class="sy0">></span><span class="nu0">0</span>,<span class="st0">"positive"</span>println, <span class="st0">"zero"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>As you can see, it becomes quite clear what happens here. Keep in mind that
cond is an expression, just like anything else in Ioke, and will return the
last value evaluated.</p>
<a name="case"></a>
<h3><span class="mw-headline">case</span></h3>
<p>A thing that you very often want to do is to check one value against several
different conditions. The case expression allows this to be done succinctly.
The core to the case-expression is the === method, that is used for matching.
The expression takes one value, then one or more conditionals followed by
actions, and then an optional default part. Once something matches, no more
conditionals will be executed. The conditional part should not be a complete
conditional statement. Instead it should return something that implements a
fitting ===. So, a small example follows:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
case<span class="br0">(</span>value, <span class="re9"><span class="re11">Text</span></span>,<span class="st0">"it is a text!"</span>println, 1<span class="sy0">..</span>10,<span class="st0">"it is a low number"</span>println, <span class="re12"><span class="re13">:</span>blurg,</span><span class="st0">"it is the symbol blurg"</span>println, <span class="re8">fn</span><span class="br0">(</span>c,<span class="br0">(</span>c<span class="re0">+</span><span class="nu0">2</span><span class="br0">)</span><span class="sy0">==</span><span class="nu0">10</span><span class="br0">)</span>,<span class="st0">"it is 8"</span>println, <span class="st0">"we don't know it!"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>The above example shows several different things you can match against,
including a lexical block. The implementation of === for a lexical block will
call the block with the value and then return true or false depending on the
truth-value of the result of the call to the block.</p>
<p>A thing that can be inconvenient in some languages is to do combinations of
several of these. Say you want to check that something is a Text and matches a
regular expression, or it is either 5..10 or 15..20. In most cases you will end
up having to write several conditional parts for at least one of those two. But
Ioke allows you to use combiners in the conditional part of a case expression.
These combiners will be rewritten before executed, so a combiner called "else"
will actually use the method "case:else", that in turn returns an object that
responds correctly to ===. The end result is that using combiners read really
well, and you can define your own by prefixing the name with "case:". There are
several standard ones. Using a few of them looks like this:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
case<span class="br0">(</span>value, <span class="re5">and</span><span class="br0">(</span><span class="re9"><span class="re11">Text</span></span>,<span class="sy0">#/</span>o<span class="sy0">+/</span><span class="br0">)</span>,<span class="st0">"it's a text with several oos"</span>println, <span class="re5">or</span><span class="br0">(</span>5<span class="sy0">..</span>10, 15<span class="sy0">..</span>20<span class="br0">)</span>,<span class="st0">"numberific"</span>println, else,<span class="st0">"oh no!"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>Combiners can be combined with each other and nested, so you could do
and(foo, or(1, 2, 3), not(x)) if you want.</p>
<p>The available combiners are these:</p>
<dl><dt>and</dt>
<dd>Returns a matcher that returns true if all the arguments return true when
calling ===. This is short circuiting.</dd>
<dt>or</dt>
<dd>Returns a matcher that returns true if any of the arguments return true
when calling ===. This is short circuiting.</dd>
<dt>not</dt>
<dd>Takes one argument and returns the false if calling === on the argument
returns true, and the other way around.</dd>
<dt>nand</dt>
<dd>The nand operation applied to === combiners.</dd>
<dt>nor</dt>
<dd>The nor operation applied to === combiners.</dd>
<dt>xor</dt>
<dd>The xor operation applied to === combiners.</dd>
<dt>else<br /></dt>
</dl><p>otherwise</p>
<dl><dd>Returns a matcher that always returns true. This is useful to make the
default argument read better.</dd>
</dl><a name="Iteration"></a>
<h2><span class="mw-headline">Iteration</span></h2>
<p>Ioke supports most of the expected control flow operations for iteration.
The one thing that is missing is the for-loop. Since the for-loop encourages
low level stepping, and can be replaced by other kinds of operations, I don't
see any reason in having it in Ioke. In fact, the for-statement in Ruby is
generally considered bad form too. And if someone really wants a for-loop it's
really easy to implement. For now I'm reserving the name if I would like to add
comprehensions at some point.</p>
<a name="loop"></a>
<h3><span class="mw-headline">loop</span></h3>
<p>For creating infinte loops, the "loop"-method is the thing. It will just
take a piece of code and execute it over and over again until some non-local
flow control rips the execution up. Using it is as simple as calling it:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
loop<span class="br0">(</span><span class="st0">"hello"</span>println<span class="br0">)</span> x<span class="sy0">=</span><span class="nu0">0</span>loop<span class="br0">(</span> if<span class="br0">(</span>x<span class="sy0">></span><span class="nu0">10</span>,<span class="re7">break</span><span class="br0">)</span> x<span class="sy0">++</span><span class="br0">)</span>
</pre></div>
</div>
<p>The first example will loop forever, printing hello over and over again. The
second example will increment a variable until it's larger then 10, and then it
will break out of the loop.</p>
<a name="while"></a>
<h3><span class="mw-headline">while</span></h3>
<p>The Ioke while loop works exactly like while-loops in other languages. It
takes one argument that is a condition to reevaluate on each iteration, and
another argument that is the code to evaluate each iteration. The result of the
while-loop is the result of the last executed expression in the body.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
x<span class="sy0">=</span><span class="nu0">0</span>while<span class="br0">(</span>x<span class="sy0"><</span><span class="nu0">10</span>, x println x<span class="sy0">++</span><span class="br0">)</span>
</pre></div>
</div>
<a name="until"></a>
<h3><span class="mw-headline">until</span></h3>
<p>The until-loop works the same as the while-loop, except it expects its
condition argument to evaluate to false. It will stop iterating when the
conditional is true for the first time.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
x<span class="sy0">=</span><span class="nu0">0</span>until<span class="br0">(</span>x<span class="sy0">==</span><span class="nu0">10</span>, x println x<span class="sy0">++</span><span class="br0">)</span>
</pre></div>
</div>
<a name="times"></a>
<h3><span class="mw-headline">times</span></h3>
<p>A very common need is to iterate something a certain number of times. The
Number Integer kind defines a method called "times" that does exactly this.
It's got two forms - one with one argument and one with two arguments. With one
argument, it will just run the argument code the specified number of times, and
with two arguments the first argument should be the name of a cell to assign
the current iteration value to and the second is the code to execute.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="nu0">3</span>times<span class="br0">(</span><span class="st0">"hello"</span>println<span class="br0">)</span> <span class="nu0">4</span>times<span class="br0">(</span>n, <span class="st0">"#{n}: wow"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>The first example will print hello three times, while the second example
will count up from 0 to 3, printing the number followed by "wow".</p>
<a name="each"></a>
<h3><span class="mw-headline">each</span></h3>
<p>For most iteration needs, you want to traverse a collection in some way. The
standard way of doing this is with the "each"-method. It's defined on all
central collection classes and is also the basis of the contract for Mixins
Enumerable. The contract for each has three different forms, and all should be
implemented if you decide to implement the each method.</p>
<p>The each method should -- as the name implies -- do something for each entry
in the collection it belongs to. So calling each on a set would do something
with each entry, etc. Exactly what that is depends on how many arguments are
given to "each".</p>
<p>If one argument is given, it should be a message chain. This message chain
will be applied to each element.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="br0">[</span><span class="re12"><span class="re13">:</span>one,</span><span class="re12"><span class="re13">:</span>two,</span><span class="re12"><span class="re13">:</span>three<span class="br0">]</span></span>each<span class="br0">(</span>inspect println<span class="br0">)</span> <span class="co1">;; the above would execute:</span><span class="re12"><span class="re13">:</span>one</span>inspect println<span class="re12"><span class="re13">:</span>two</span>inspect println<span class="re12"><span class="re13">:</span>three</span>inspect println
</pre></div>
</div>
<p>Another way of saying it is that the message chain will be executed using
each element of the collection as receiver, in turn. The return value will be
thrown away in this case, so to achieve anything, the code need to mutate data
somewhere.</p>
<p>The second -- and most common -- form, takes two arguments. The first
argument should be the name of a cell to assign each element to, and the second
argument should be the code to execute. Under the covers, this form will
establish a new lexical context for the code to run in. As with the first
version, each return value will be trown away.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="br0">[</span><span class="nu0">2</span>,<span class="nu0">4</span>,<span class="nu0">6</span><span class="br0">]</span>each<span class="br0">(</span>x,<span class="br0">(</span>x<span class="sy0">*</span>x<span class="br0">)</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>Here, the name "x" will be used as the name of each element of the list in
turn, while executing the code.</p>
<p>The final form of each takes three arguments, where the first is the name of
a cell to assign the current index, and the other two arguments are the same as
the above.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="br0">[</span><span class="nu0">2</span>,<span class="nu0">4</span>,<span class="nu0">6</span><span class="br0">]</span>each<span class="br0">(</span>i, x,<span class="st0">"#{i}: #{(x*x)}"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>The above code would print:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="nu0">0</span><span class="re13">:</span><span class="nu0">4</span><span class="nu0">1</span><span class="re13">:</span><span class="nu0">16</span><span class="nu0">2</span><span class="re13">:</span><span class="nu0">36</span>
</pre></div>
</div>
<a name="break.2C_continue"></a>
<h3><span class="mw-headline">break, continue</span></h3>
<p>When executing loops it is sometimes important to be able to interrupt
execution prematurely. In this cases the break and continue methods allow this
for "loop", "while" and "until". Both break and continue work lexically, so if
you send code to another method that uses these methods, they will generally
jump out of a lexically visible loop, just like expected.</p>
<p>The break method takes an optional value to return. If no value is provided
it will default to nil. When breaking out of a loop, that loop will return the
value given to break. The continue method will not break out of the execution,
but will instead jump to the beginning and reevaluate the condition once
again.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
while<span class="br0">(</span><span class="re6"><span class="re7">true</span></span>, <span class="re7">break</span><span class="br0">(</span><span class="nu0">42</span><span class="br0">)</span><span class="br0">)</span>
</pre></div>
</div>
<p>This code will immediately return 42 from the while-loop, even though it
should have iterated forever.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
i<span class="sy0">=</span><span class="nu0">0</span>while<span class="br0">(</span>i<span class="sy0"><</span><span class="nu0">10</span>, i println if<span class="br0">(</span>i<span class="sy0">==</span><span class="nu0">5</span>, i<span class="sy0">=</span><span class="nu0">7</span> <span class="re7">continue</span><span class="br0">)</span> i<span class="sy0">++</span><span class="br0">)</span>
</pre></div>
</div>
<p>This code uses continue to jump over a specific number, so it will only
print 0 to 5, and 7 to 9.</p>
<a name="Comprehensions"></a>
<h2><span class="mw-headline">Comprehensions</span></h2>
<p>Ioke's Enumerable mimic makes it really easy to use higher order operations
to transform and work with collections of data. But in some cases the code for
doing that might not be as clear as it could be. Comprehensions allow a list,
set or dict to be created based on a more abstract definition of what should be
done. The specific parts of a comprehension are generators, filters and the
mapping. The generators are what data to work on, the filters chooses more
specifically among the generated data, and the mapping decides what the output
should look like.</p>
<p>The following example does three nested iterations and returns all
combinations where the product of the number is larger than 100:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
for<span class="br0">(</span> x<span class="sy0"><-</span>1<span class="sy0">..</span>20, y<span class="sy0"><-</span>1<span class="sy0">..</span>20, z<span class="sy0"><-</span>1<span class="sy0">..</span>20, val<span class="sy0">=</span>x<span class="sy0">*</span>y<span class="sy0">*</span>z, val<span class="sy0">></span><span class="nu0">100</span>, <span class="br0">[</span>x, y, z, val<span class="br0">]</span><span class="br0">)</span>
</pre></div>
</div>
<p>This code neatly shows all things you can do in a comprehension. The final
argument will always be the output mapping, which in this case is a list of the
three variables, and their product. The generator parts is first a name, the
<- operator followed by an expression that is Enumerable. You can also see
that one of the expressions is an assignment, that can be used later. Finally,
there is a conditional that limits what the output will be. The more or less
equivalent expression using Enumerable methods would be 1..20 flatMap(x, 1..20
flatMap(y, 1..20 filter(z, x*y*z > 100) map([x,y,z,x*y*z]))). In my eyes,
the for-comprehension is much more readable.</p>
<p>There are two variations on this. The first one is when you want the output
to be a Set of things instead of a List. The code is exactly the same, except
instead of using for, you use for:set. There is also a for:dict version, for
more esoteric usages.</p>
<a name="Code"></a>
<h1><span class="mw-headline">Code</span></h1>
<p>Many of the things you do in Ioke will directly manipulate code. Since the
messages that make up code is really easy to get hold of, this manipulation
comes easy too. Ioke takes the Lisp philosophy of "code is data" to heart. The
basic unit of a piece of code is a Message. A Message has a name, a next and
prev pointer, and any number of arguments. When you manipulate a message, the
argument list will contain messages too - and if the next or prev pointers are
not nil, they will point to other messages. It serves well to remember that
except for the message itself, all code will be evaluated in the context of a
receiver and a ground. The ground is necessary because arguments to be
evaluated need to be run in some specific context, even though the current
receiver is not the same as the ground.</p>
<p>The current types of code can be divided into three different categories.
These are methods, macros and blocks. Native methods are all of the kind
JavaMethod, but can have any kind of semantics - including semantics that look
like macros. Most native methods do have the same semantics as regular methods,
however.</p>
<a name="Methods"></a>
<h2><span class="mw-headline">Methods</span></h2>
<p>A method in Ioke is executable code that is activatable. A method can take
arguments of several different types. The arguments to a method will always be
evaluated before the code in the method starts to execute. An Ioke method is
defined using the "method" method. All Ioke methods have the kind
DefaultMethod. This leaves the room open to define other kinds of methods, if
need be. DefaultMethod's could be implemented using macros, but at this point
they aren't. A DefaultMethod can have a name - and will get a name the first
time it is assigned to a cell.</p>
<p>It is really easy to define and use a simple method. The easiest case is to
define a method that is empty. This method will just return nil:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span><span class="br0">)</span>m<span class="co1">;; call the method</span>
</pre></div>
</div>
<p>Since methods are activatable, when you name a cell that contains a method,
that method will be invoked. To stop that behavior, use the "cell" method.</p>
<p>The definition of a method can take several different pieces. These are a
documentation string, definitions of positional required arguments, definitions
of positional optional arguments, definitions of keyword arguments, definition
of a rest argument, definition of a keyword rest argument and the actual code
of the method.</p>
<p>Let's take these one by one. First, if the the first element of a call to
"method" is a literal text, and there is at least one more argument in the
definition, then that text will be the documentation text for the method:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="co1">;; a method that returns "foo"</span>m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span><span class="st0">"foo"</span><span class="br0">)</span> <span class="co1">;; a method that returns nil, but</span><span class="co1">;; has the documentation text "foo"</span>m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span><span class="st0">"foo"</span>,<span class="re6"><span class="re7">nil</span></span><span class="br0">)</span>
</pre></div>
</div>
<p>A method can take any number of required positional arguments. These will be
checked when a method is called, and if not enough -- or too many -- arguments
are provided, an error will be signalled.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>x, x println<span class="br0">)</span>m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>x, y, z, x<span class="sy0">*</span>y<span class="sy0">+</span>z<span class="br0">)</span>
</pre></div>
</div>
<p>The first method takes one argument and prints that argument. The second
method takes three arguments and return the product of the two first added to
the third.</p>
<p>A method can also have optional positional arguments. In that case the
optional arguments must follow the required arguments. Optional arguments need
to have a default value -- in fact, that is how you distinguish them from
required arguments. The arity of method calls will still be checked, but using
minimum and maximum values instead. The default value for an argument should be
code that can be executed in the context of the running method, so a default
value can refer to earlier positional arguments. A default value can also do
quite complex things, if need be, although it's not really recommended.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="co1">;; takes zero or one arguments</span>m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>x<span class="nu0">42</span>, x println<span class="br0">)</span> <span class="co1">;; takes one to three arguments</span>m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>x, y<span class="nu0">42</span>, z<span class="nu0">25</span>, x<span class="sy0">*</span>y<span class="sy0">+</span>z<span class="br0">)</span>
</pre></div>
</div>
<p>The syntax for optional arguments is to just write a space after the name of
the argument, and then write the code to generate the default value after
it.</p>
<p>A method can also have keyword arguments. Keyword arguments are checked,
just like regular arguments, and you can't generally give keyword arguments to
a method not expecting it. Nor can you give unexpected keyword arguments to a
method that takes other keywords. Keyword arguments can never be required. They
can have default values, which will default to nil if not provided. They can be
defined anywhere among the arguments -- the only reason to reorder them is that
default values of other optional arguments can use prior defined keyword
arguments.</p>
<p>A keyword argument is defined just like a regular argument, except that it
ends in a colon.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>foo<span class="re12"><span class="re13">:</span>,</span>bar<span class="re13">:</span><span class="nu0">42</span>, foo println bar println<span class="br0">)</span>
</pre></div>
</div>
<p>Just as with regular optional arguments, you supply the default value of the
keyword argument after a space. The cells for the keyword arguments will be the
same as their names, without the ending colon. The above code would print nil
and 42 if no arguments were specified. It's important to remember that keyword
arguments and positional arguments do not interact -- except for when
calculating default values. When assigning values it's always possible to see
what is positional and what is a keyword argument.</p>
<p>Ioke methods can collect positional arguments into a list. This allow
methods to take variable number of arguments. The rule is that all other
positional arguments are first calculated, and the remaining positional
arguments will be added to the rest argument. If no positional arguments are
available, the rest argument will be empty. A rest argument is defined by
preceding it with a plus sign in the argument definition. For clarity a rest
argument should be defined last in the list, although it doesn't exactly matter
anyway.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span><span class="sy0">+</span>rest, rest println<span class="br0">)</span> m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>x, y<span class="nu0">42</span>,<span class="re5">+</span>rest, rest println<span class="br0">)</span>
</pre></div>
</div>
<p>The above code defines one method that only takes one rest argument. That
means the method can take any number of arguments and all of them will be
collected into a list. The second method takes one required argument, one
optional argument and any number of extra arguments. So if four arguments are
given, the rest argument will contain two.</p>
<p>The final type of argument is keyword rest arguments. Just like positional
rest arguments, a keyword rest argument can collect all keywords given to a
method, no matter what. If a keyword rest argument is used, no conditions will
be signalled if an unknown keyword is given to a method. If other keywords are
defined, these keywords will not show up in the keyword rest argument. The
keyword rest argument is defined by preceding the name with a +: sigil, and the
keyword rest argument will be a Dict instead of a list. The keys will be
symbols but without the ending colon.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span><span class="sy0">+</span><span class="re12"><span class="re13">:</span>krest,</span> krest println<span class="br0">)</span> m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>x, y<span class="re12"><span class="re13">:</span>,</span><span class="re5">+</span>rest,<span class="sy0">+</span><span class="re12"><span class="re13">:</span>krest,</span> <span class="br0">[</span>x, y, rest, krest<span class="br0">]</span><span class="br0">)</span>
</pre></div>
</div>
<p>The above code first creates a method that can take any number of keyword
arguments but nothing else. The second method takes one required positional
argument, one keyword argument, rest arguments and keyword rest arguments, and
returns a new list containing all the arguments given to it.</p>
<p>The final argument to the method method should always be the code to
execute. This code will be executed in the context of a receiver, that is the
object the method is activated on. A method execution also happens in the
context of the method activation context, where local variables are stored.
This activation context contain some predefined variables that can be used.
These are "self", "@", "currentMessage" and "surroundingContext". Both "self"
and "@" refer to the receiver of the method call. "currentMessage" returns the
message that initiated the activation of the method, and "surroundingContext"
returns the object that represents the context where this method was called
from. Both "self" and "@" can be used to specify that something should be
assigned to the receiver, for example.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
createNewCell<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span> @foo<span class="sy0">=</span><span class="nu0">42</span><span class="br0">)</span>
</pre></div>
</div>
<p>The method create above will create assign the value 42 to the cell "foo" on
the object the method was called on.</p>
<p>When calling a method, you specify positional arguments separated with
commas. You can provide keyword arguments in any order, in any place inside the
braces:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="co1">;; the method foo takes any kind of argument</span>foo foo<span class="br0">(</span><span class="br0">)</span>foo<span class="br0">(</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">)</span>foo<span class="br0">(</span>blarg<span class="re13">:</span><span class="nu0">42</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span><span class="br0">)</span>foo<span class="br0">(</span>quux<span class="re13">:</span><span class="nu0">42</span><span class="sy0">*</span><span class="nu0">2</span><span class="br0">)</span>
</pre></div>
</div>
<p>To give a keyword argument, you just write it exactly like you define
keyword arugments - a name followed by a colon.</p>
<p>Sometimes it can be useful to be able to take a list of values and give them
as positional arguments. The same can be useful to do with a dict of names. You
can do that using splatting. This is done by preceding a list or a dict with an
asterisk. This will result in the method getting the values inside of it as if
the arguments were given directly. You can splat several things to the same
invocation.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
dc<span class="sy0">=</span><span class="br0">{</span>foo<span class="re13">:</span><span class="nu0">42</span>, bar<span class="re13">:</span><span class="nu0">13</span><span class="br0">}</span>ls<span class="sy0">=</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span><span class="br0">]</span>ls2<span class="sy0">=</span><span class="br0">[</span><span class="nu0">42</span>,<span class="nu0">43</span>,<span class="nu0">44</span><span class="br0">]</span> foo<span class="br0">(</span><span class="sy0">*</span>dc<span class="br0">)</span><span class="co1">;; the same as:</span>foo<span class="br0">(</span>foo<span class="re13">:</span><span class="nu0">42</span>, bar<span class="re13">:</span><span class="nu0">13</span><span class="br0">)</span> foo<span class="br0">(</span><span class="sy0">*</span>ls<span class="br0">)</span><span class="co1">;; the same as:</span>foo<span class="br0">(</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span><span class="br0">)</span> foo<span class="br0">(</span><span class="sy0">*</span>ls2,<span class="nu0">111</span>,<span class="sy0">*</span>dc,<span class="sy0">*</span>ls<span class="br0">)</span><span class="co1">;; the same as:</span>foo<span class="br0">(</span><span class="nu0">42</span>,<span class="nu0">43</span>,<span class="nu0">44</span>,<span class="nu0">111</span>, foo<span class="re13">:</span><span class="nu0">42</span>, bar<span class="re13">:</span><span class="nu0">13</span>,<span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span><span class="br0">)</span>
</pre></div>
</div>
<p>If you try to splat something that can't be splatted, a condition will be
signalled.</p>
<a name="Macros"></a>
<h2><span class="mw-headline">Macros</span></h2>
<p>The main difference between a macro and a method in Ioke is that the
arguments to a macro are not evaluated before they are sent to the macro. That
means you have to use macros to send raw message chains in an invocation. In
most languages, this kind of feature is generally called call-by-name. When a
macro gets called, it will get access to a cell called "call" which is a mimic
of the kind Call. This gives access to information about the call and makes it
possible to evaluate the code sent as arguments, check how many arguments are
supplied, and so on.</p>
<p>A macro is created using the "macro" cell on DefaultBehavior. This will
return a mimic of DefaultMacro. Since macros can't define arguments, it's a bit
easier to describe than methods, but the things that can be done with macros
are also a bit more interesting than what can be achieved with methods. One
important thing to keep in mind is that most macros can not receive splatted
arguments. In most cases keyword arguments aren't available either - but they
could be faked if needed. Macros should generally be used to implement control
structures and things that need to manipulate code in different ways.</p>
<p>Just like a method, a macro gets evaluated on a specific receiver. It also
gets the same kind of method activation context, but the contents of it is a
bit different. Specifically, the context for a macro contains cells named
"self", "@", "currentMessage", "surroundingContext" and "call". It's the "call"
cell that is most important. It is a mimic of Call, and Call defines several
important methods for manipulating the call environment. These are:</p>
<dl><dt>arguments</dt>
<dd>This method returns a list containing the unevaluated arguments given to
this message. Any kind of manipulation can be done with these arguments.</dd>
<dt>ground</dt>
<dd>Returns the ground in which the call was initiated. This is necessary to
evaluate arguments in their own environment.</dd>
<dt>message</dt>
<dd>The currently executing message. This is the same as the "currentMessage"
cell in the macro activation context.</dd>
<dt>evaluatedArguments</dt>
<dd>Returns a list containing all arguments, evaluated according to the regular
rules (but not handling splatting or keywords).</dd>
<dt>resendToMethod</dt>
<dd>Allows a specific message to be resent to another method, without manually
copying lots of information.</dd>
</dl><p>These methods are a bit hard to understand, so I'll take some examples from
the implementation of Ioke, and show how macros are used here.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="re9"><span class="re11">Mixins</span></span><span class="re11">Enumerable</span>map<span class="sy0">=</span><span class="re8">macro</span><span class="br0">(</span> <span class="st0">"takes one or two arguments. if one argument is given, it will be evaluated as a message chain on each element in the enumerable, and then the result will be collected in a new List. if two arguments are given, the first one should be an unevaluated argument name, which will be bound inside the scope of executing the second piece of code. it's important to notice that the one argument form will establish no context, while the two argument form establishes a new lexical closure."</span>, len<span class="sy0">=</span>call arguments length result<span class="sy0">=</span>list<span class="br0">(</span><span class="br0">)</span> if<span class="br0">(</span>len<span class="sy0">==</span><span class="nu0">1</span>, code<span class="sy0">=</span>call arguments first <span class="re6">self</span>each<span class="br0">(</span>n, result<span class="sy0"><<</span>code evaluateOn<span class="br0">(</span>call ground, cell<span class="br0">(</span><span class="re12"><span class="re13">:</span>n<span class="br0">)</span><span class="br0">)</span><span class="br0">)</span>,</span> code<span class="sy0">=</span><span class="re9"><span class="re11">Lexical</span>Block</span>createFrom<span class="br0">(</span>call arguments, call ground<span class="br0">)</span> <span class="re6">self</span>each<span class="br0">(</span>n, result<span class="sy0"><<</span>code call<span class="br0">(</span>cell<span class="br0">(</span><span class="re12"><span class="re13">:</span>n<span class="br0">)</span><span class="br0">)</span><span class="br0">)</span><span class="br0">)</span></span> result<span class="br0">)</span>
</pre></div>
</div>
<p>The code above implements map, one of the methods from Enumerable. The map
method allows one collection to be mapped in a predefined way into something
else. It can take either one or two arguments. If one argument is given, that
is a message chain to apply, and then collect the results. If two arguments are
given, the first is the argument name to use, and the second is the code to
execute for each entry.</p>
<p>The first step is to figure out how many arguments have been given. This is
done by checking the length of the "call arguments" cell. If we have a length
of one, we know that the first argument is a piece of code to apply, so we
assign that argument to a cell called "code". Now, "code" will be a mimic of
Message, and Message has a method called "evaluateOn", that can be used to
fully evaluate a message chain. And that's exactly what we do for each element
in the collection we are in. The result of evaluateOn is added to the result
list. We use "call ground" to get the correct ground for the code to be
evaluated in.</p>
<p>If we get two arguments, it's possible to take a shortcut and generate a
lexical block from those arguments, and then use that. So we call "LexicalBlock
createFrom" and send in the arguments and the ground, and then call that piece
of code once for each element in the collection.</p>
<p>It is a bit tricky to figure out how macros work. I recommend looking at the
implementations of some of the core Ioke methods/macros, since these use much
of the functionality.</p>
<a name="Blocks"></a>
<h2><span class="mw-headline">Blocks</span></h2>
<p>A lexical block allows the execution of a piece of code in the lexical
context of some other code, instead of in a dynamic object scope. A lexical
block does not have a receiver. Instead, it just establishes a new lexical
context, and executes the code in that. The exact effect that has on
assignments has been<a title="Guide:Assignment" href="/wiki/index.php/Guide:Assignment">described</a>earlier.</p>
<p>A lexical block can be created using either the "fn" or the "fnx" methods of
DefaultBehavior. The main difference between the two is that a block created
with "fnx" will be activatable, while something created with "fn" will not.
Lexical blocks handle arguments exactly the same way as methods, so a lexical
block can take optional arguments, keyword arguments, rest arguments and so on.
Both "fn" and "fnx" also take optional documentation text.</p>
<p>A block created with the "fn" method can be invoked using the "call" method
of the kind<a title="http://ioke.org/dok/kinds/LexicalBlock.html" class="external text" href="http://ioke.org/dok/kinds/LexicalBlock.html"><code>LexicalBlock</code></a>.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
x<span class="sy0">=</span><span class="re8">fn</span><span class="br0">(</span>z, z println<span class="br0">)</span>x call<span class="br0">(</span><span class="nu0">42</span><span class="br0">)</span>
</pre></div>
</div>
<p>If a block created with the "fn" method takes one or more explicit
parameters it can also be activated like a regular method. The reason for this
is shown in the code snippet below. Here the result of invoking the block
referred to by "x" is passed to "y" (which may be a regular method or even
another block). If "x" would be fully non-activatable, "x" would be passed to
"y" as is with the argument thrown away. In other words, that would be dead
code. However, you can still refer to the block as "x" without an invocation to
happen.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
x<span class="sy0">=</span><span class="re8">fn</span><span class="br0">(</span>z, z<span class="sy0">+</span><span class="nu0">42</span><span class="br0">)</span>y<span class="br0">(</span>x<span class="br0">(</span><span class="nu0">100</span><span class="br0">)</span><span class="br0">)</span><span class="co1">;; activates the block with argument 100 and passes the result to y</span>x<span class="co1">;; refers to the block without activating it</span>
</pre></div>
</div>
<p>A block created with the "fnx" method is activatable per se and thus can be
activated like a regular method. The default is to use "fn" to create inactive
blocks though, since blocks are generally used to pass pieces of code
around.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
y<span class="sy0">=</span><span class="re8">fnx</span><span class="br0">(</span>z, z println<span class="br0">)</span>y<span class="br0">(</span><span class="nu0">42</span><span class="br0">)</span>
</pre></div>
</div>
<p>A lexical block is a regular kind of object that can be assigned to any
cell, just like other objects. Lexical blocks mimic LexicalBlock, and blocks
don't have names. In contrast to methods and macros, no extra cells will be
added to the activation context for a lexical block.</p>
<a name="Lecros"></a>
<h2><span class="mw-headline">Lecros</span></h2>
<p>A macro works exactly like a method, in that it always has a receiver, and
that receiver is available inside the macro as 'self' and '@'. In some
circumstances it can be really useful to have a macro that behaves like a
lexical block instead - being lexical so it can use cells defined outside of
the definition of the macro. These macros won't have access to 'self' or '@',
since they don't have a receiver in that way. Where such a macro is called is
only based on namespacing.</p>
<p>Ioke supports these kind of macros. They are all mimics of the kind
LexicalMacro, and they are created using the method 'lecro'. A LexicalMacro is
activatable by default, but a non-activatable lecro can be created using
lecrox. The 'lecro' method takes the same arguments as 'macro', and the only
real difference is the way it handles outside cells and the receiver value. A
lecro also has a cell called outerScope that can be used if you need to
explicitly access something in the outer name space - such as call.</p>
<a name="Syntax_2"></a>
<h2><span class="mw-headline">Syntax</span></h2>
<p>Ioke supports loads of stuff with the standard<code>macro</code>, but
sometimes these are a bit too low level for commonly used operations. Syntax is
one of those cases: you can achieve the same goals with macros, but you don't
really want to. Many features in Ioke S are implemented using syntax.</p>
<p>You can define syntax using the<code>syntax</code>method. This returns a
mimic of<code>DefaultSyntax</code>. You can use the same kind of cells in a
syntax as you can in a macro. What is different with syntax is that syntax can
only return one of two things. The first is<code>nil</code>, and the second is
a message chain. A syntax will only be executed once at every point in the
message chains, because after a syntax executes the first time, it will replace
itself with the result of that evaluation. If that evaluation
returns<code>nil</code>, syntax will just remove itself from the message
chain.</p>
<p>You can use this for many things, but one of the more useful things you can
do is translate a high level declarative definition of something into a low
level executable version. That is exactly how for comprehensions are
implemented.</p>
<p>Syntactic macros are fairly advanced, and take some time to grok. They are
incredibly useful though, and they are used all over the standard library to
achieve all manner of interesting things. Take a look there and things should
hopefully become clearer. It's also a must to read the section on message chain
manipulation and quoting in this guide to make syntax macros readable.</p>
<a name="Destructuring"></a>
<h2><span class="mw-headline">Destructuring</span></h2>
<p>A common problem with macros is that you want to take several different
combinations of arguments, and do different things depending on how many you
get. Say you might want to take one code argument, but also two optional
arguments that should be evaluated. All of that code turns out to be highly
repetetive, so Ioke contains a collection of syntax macros that make it easier
to write these things. These are collectively called destructuring syntax.</p>
<p>Let us say we have a macro that can be called with any of three types of
argument list: [code], [evaluatedArgument, code], or [evaluatedArgument, code,
evaluatedArgument]. The stuff that should happen is totally different for each
of these cases. With a regular macro the code would look something like
this:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
foo<span class="sy0">=</span><span class="re8">macro</span><span class="br0">(</span> len<span class="sy0">=</span>call arguments length case<span class="br0">(</span>len, <span class="nu0">1</span>, code<span class="sy0">=</span>call arguments<span class="br0">[</span><span class="nu0">0</span><span class="br0">]</span> <span class="co1">; do something with the code</span> , <span class="nu0">2</span>, arg1<span class="sy0">=</span>call argAt<span class="br0">(</span><span class="nu0">0</span><span class="br0">)</span> code<span class="sy0">=</span>call arguments<span class="br0">[</span><span class="nu0">1</span><span class="br0">]</span> <span class="co1">; do something with the code and arg</span> , <span class="nu0">3</span>, arg1<span class="sy0">=</span>call argAt<span class="br0">(</span><span class="nu0">0</span><span class="br0">)</span> code<span class="sy0">=</span>call arguments<span class="br0">[</span><span class="nu0">1</span><span class="br0">]</span> arg2<span class="sy0">=</span>call argAt<span class="br0">(</span><span class="nu0">2</span><span class="br0">)</span> <span class="co1">; do something with the code and args</span> <span class="br0">)</span><span class="br0">)</span>
</pre></div>
</div>
<p>As you can see it's really a lot of code to see what happens here, and it is
very imperative in style. But, if I instead use dmacro - which is the
destructuring version of macro - it looks like this:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
foo<span class="sy0">=</span><span class="re8">dmacro</span><span class="br0">(</span> <span class="br0">[</span>code<span class="br0">]</span> <span class="co1">; do something with the code</span> , <span class="br0">[</span><span class="sy0">></span>arg1, code<span class="br0">]</span> <span class="co1">; do something with the code and arg</span> , <span class="br0">[</span><span class="sy0">></span>arg1, code,<span class="sy0">></span>arg2<span class="br0">]</span> <span class="co1">; do something with the code and args</span><span class="br0">)</span>
</pre></div>
</div>
<p>dmacro will automatically check the length and extract the different
arguments. The right arrow before the names of arg1 and arg2 marks that these
should be evaluated. And what is more, dmacro will generate code that also
generates a good condition if no argument matching works out. If you give zero
arguments to the first version, it will fail silently. The dmacro will complain
immediately. The dmacro destructuring syntax actually supports several more
ways of ripping arguments apart. You can find this information in the doks for
dmacro. Also, there are equivalent versions of dmacro for lecro, lecrox and
syntax, called dlecro, dlecrox and dsyntax. They do the same thing, except they
act like lecros or syntax instead.</p>
<a name="Message_chains"></a>
<h2><span class="mw-headline">Message chains</span></h2>
<p>In many cases a macro will take code that is not wrapped up inside of a
method, macro or block. These pieces of code are called message chains, since
their representation will be a raw Message mimic. The chains are quite
flexible, since they can be taken apart, modified and put together again. They
can also be unevaluated and used as data definitions of some kind. That's how
the argument handling to methods are implemented, for example. Since the call
to "method" can be seen as a regular call to a macro, the argument descriptions
are actually just unevaluated message chains that are picked apart to tease out
the argument names. The same technique is applicable in any macro usage.</p>
<p>The term message chain fragment is also used to specifically mean a message
chain that is meant to be put together with something and evaluated. Picture a
daisy chain that gets added at the end of another chain and then executed.
That's what happens if you execute something like<code>[1, 2, 3]
map(*2)</code>. In this case the call to<code>*</code>with the argument 2 will
be a message chain fragment that will be put together with a new receiver
before execution.</p>
<p>To handle syntax correctly - but also to generally handle manipulation of
message chains - it is important to know about the available methods to do
this. I have added quite a lot of nice stuff that makes it easy to work with
message chains.</p>
<p>First, messages are actually<code>Enumerable</code>, so you can use
any<code>Enumerable</code>methods on them. The enumeration always starts at the
receiver. It will not proceed into arguments, just following the next-pointer.
To create a new message or message chain, there are several helpful methods and
operators. The first method is called<code>message</code>and takes an evaluated
name and returns a new message with that name.<code>Message from</code>takes
one argument that will not be evaluated and returns a message chain
corresponding to that argument.<code>Message fromText</code>parses text and
returns the message chain for it.<code>Message wrap</code>takes an evaluated
argument and returns a message that will always return that value. As will be
mentioned later, Message has<code>next=</code>and<code>prev=</code>methods that
you can use to set the next and previous pointers. Message also
has<code>appendArgument</code>and<code>prependArgument</code>that allow you to
add new arguments to the message arguments.</p>
<p>The most used versions for creating message chains are short cuts for the
above. Let us begin with creation. Instead of<code>Message from</code>you can
use '. That is a single quote mark. The message after that will be unevaluated
and returned as a message chain. If you use a `, a backtick, that is equivalent
to<code>Message wrap</code>. And then we have '', that is two single quotes
after each other. This message is generally called metaquote or quasiquote. It
works the same as ', except that it will find any place where ` is used and
insert the value of evaluating the message after the ` and insert that into the
current message chain. Finally, '' will replace a `` with a literal `
message.</p>
<p>You can add new arguments to a message by using the << operator. This
operator returns the receiver.</p>
<p>If you want to chain together a message chain,
using<code>next=</code>and<code>prev=</code>is pretty tedious. You can instead
use the -> operator. This will chain together the left hand side and the
right hand side messages, and return the right hand side message.</p>
<p>I think it is time for some examples:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="co1">; create a new message with name foo</span>x<span class="sy0">=</span>'foo <span class="co1">; add two arguments to the foo message</span>arg<span class="sy0">=</span>'<span class="br0">(</span>bar quux<span class="br0">)</span><span class="br0">(</span>x<span class="sy0"><<</span>arg<span class="br0">)</span><span class="sy0"><<</span>'baz <span class="co1">; what we have done so far could be done with:</span>x<span class="sy0">=</span>'<span class="br0">(</span>foo<span class="br0">(</span>bar quux, baz<span class="br0">)</span><span class="br0">)</span> y<span class="sy0">=</span>'blurg<span class="co1">; chain together x and y</span>x<span class="sy0">-></span>y <span class="co1">; the above is equivalent to</span>if<span class="br0">(</span>y prev, y prev next<span class="sy0">=</span><span class="re6"><span class="re7">nil</span></span><span class="br0">)</span>x next<span class="sy0">=</span>y y prev<span class="sy0">=</span>x val<span class="sy0">=</span><span class="nu0">42</span> <span class="co1">; insert the message chain in x</span>''<span class="br0">(</span>foo bar<span class="br0">(</span>`val<span class="br0">)</span>`x<span class="br0">)</span> <span class="co1">; the above will return the same as</span>'<span class="br0">(</span>foo bar<span class="br0">(</span><span class="nu0">42</span><span class="br0">)</span>foo<span class="br0">(</span>bar quux, baz<span class="br0">)</span><span class="br0">)</span>
</pre></div>
</div>
<p>To understand these operators, you need to have a clear understanding of how
the internals of message chains work. Once that clicks, these should be fairly
straight forward to understand.</p>
<a name="Introspection_and_reflection"></a>
<h1><span class="mw-headline">Introspection and reflection</span></h1>
<p>Ioke supports quite fancy introspection and reflection capabilities. In
Ioke, reflection includes the ability to change data dynamically, as well as
introspect on it. Since the message based structure of a program is available
at runtime, most things can be changed dynamically. The internal structure of a
program is also very easy to inspect.</p>
<p>All objects in Ioke have some core methods that are used to look at them.
Some come from Base, and some come from DefaultBehavior. The rest of the
reflection and metaprogramming capabilities belong to the Message kind.</p>
<dl><dt>kind</dt>
<dd>Should be a text that gives the full name of the kind this object is
closest mimic to. Except for nil, true and false, this will return a text that
starts with a capital letter.</dd>
</dl><div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="re11">Foo</span><span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span><span class="re11">Foo</span><span class="re6">mimic</span>kind println <span class="re11">Foo</span><span class="re11">Bar</span><span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span><span class="re11">Foo</span><span class="re11">Bar</span><span class="re6">mimic</span>kind println
</pre></div>
</div>
<p>This code will first print "Foo", and then print "Foo Bar", since an object
assigned to a cell with a capital initial letter will get a new kind value.</p>
<dl><dt>kind?</dt>
<dd>Takes one text argument and returns true if the object has that kind
anywhere in its mimic chain.</dd>
</dl><div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="re11">Foo</span><span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span>foo<span class="sy0">=</span><span class="re11">Foo</span><span class="re6">mimic</span>foo kind?<span class="br0">(</span><span class="st0">"foo"</span><span class="br0">)</span><span class="co1">;; false</span>foo kind?<span class="br0">(</span><span class="st0">"Foo"</span><span class="br0">)</span><span class="co1">;; true</span>foo kind?<span class="br0">(</span><span class="st0">"Text"</span><span class="br0">)</span><span class="co1">;; false</span>foo kind?<span class="br0">(</span><span class="st0">"Origin"</span><span class="br0">)</span><span class="co1">;; true</span>foo kind?<span class="br0">(</span><span class="st0">"Ground"</span><span class="br0">)</span><span class="co1">;; true</span>foo kind?<span class="br0">(</span><span class="st0">"DefaultBehavior"</span><span class="br0">)</span><span class="co1">;; true</span>foo kind?<span class="br0">(</span><span class="st0">"Base"</span><span class="br0">)</span><span class="co1">;; true</span>
</pre></div>
</div>
<p>As you can see in this example, "kind?" can return true for several
different texts.</p>
<dl><dt>notice</dt>
<dd>When looking at objects, there are two ways to get information about them,
notice and inspect. If you want a brief description of an object where it's
important that the description doesn't take up much space, notice should be
used. If an exhaustive description is needed, inspect should be used instead.
For some objects these both return the same thing, but for Origin mimics, the
difference is large.</dd>
</dl><div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="re11">Foo</span><span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span><span class="re11">Foo</span>x<span class="sy0">=</span><span class="st0">"blarg"</span><span class="re11">Foo</span>y<span class="sy0">=</span><span class="nu0">42</span><span class="re11">Foo</span>notice<span class="co1">;; Foo_0x7CBDE6</span>
</pre></div>
</div>
<p>The default notice for Origin mimics will combine the kind and the unique
hex id for the object, and create a text of that. The "notice" method should be
overridden to provide better information in most cases.</p>
<dl><dt>inspect</dt>
<dd>In contrast to notice, inspect is used to get exhaustive information. If a
composite object is asked for its inspect, a quite large dump of information
will often be shown. For a new object the output will be smaller, but usually
still larger than the notice for it.</dd>
</dl><div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="re11">Foo</span><span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span><span class="re11">Foo</span>x<span class="sy0">=</span><span class="st0">"blarg"</span><span class="re11">Foo</span>y<span class="sy0">=</span><span class="nu0">42</span><span class="re11">Foo</span>inspect println
</pre></div>
</div>
<p>This will print:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="re11">Foo</span>_<span class="re1">0x7CBDE6</span><span class="re13">:</span> kind <span class="sy0">=</span><span class="st0">"Foo"</span> x <span class="sy0">=</span><span class="st0">"blarg"</span> y <span class="sy0">=</span><span class="nu0">42</span>
</pre></div>
</div>
<p>If another representation makes more sense for inspection, "inspect" should
definitely be overridden by custom objects.</p>
<dl><dt>uniqueHexId</dt>
<dd>This method is used to return a text that contains a unique hex identity
for an object. This text is guaranteed to be unique within a virtual machine
for any object, and is the mechanism that "inspect" and "notice" uses.</dd>
</dl><dl><dt>cellSummary</dt>
<dd>Calling "inspect" on any Origin mimic will dispatch to "cellSummary", which
displays all the cell information about a specific object.</dd>
</dl><dl><dt>cell</dt>
<dd>The "cell" method can be used for two different things. The first one is to
get access to a value without activating it, and the second is to get access to
a cell based on a name that you don't know at the time you're writing the
program. The "cell" method takes one argument that is the name of the cell to
fetch. The fetching works the same as regular cell lookup, except that
activation doesn't happen. This means that a condition will still be signalled
if you try to get something that doesn't exist.</dd>
</dl><div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
x<span class="sy0">=</span><span class="nu0">42</span>cell<span class="br0">(</span><span class="re12"><span class="re13">:</span>x<span class="br0">)</span></span><span class="co1">;; 42</span> x<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span><span class="br0">)</span>cell<span class="br0">(</span><span class="re12"><span class="re13">:</span>x<span class="br0">)</span></span><span class="co1">;; the method object</span> name<span class="sy0">=</span><span class="re12"><span class="re13">:</span>foo</span>cell<span class="br0">(</span>name<span class="br0">)</span><span class="co1">;; the value of foo</span>
</pre></div>
</div>
<dl><dt>cell=</dt>
<dd>Just as with "cell", "cell=" can be used to set cells that you don't know
the name of at the time of writing the program. As discussed in the chapter on
assignment, cell= can also be used to set cells that can't be set in the
regular way due to naming strangeness.</dd>
</dl><dl><dt>cell?</dt>
<dd>If you're not sure if a cell exists, using "cell?" is the way to find out.
Give it a name and it returns true or false depending on if that cell
exists.</dd>
</dl><dl><dt>cellNames</dt>
<dd>If you want to get the names of all the cells an object contains, you can
get that with cellNames. By default, cellNames will only return the names of
cells that belong to the receiver, but if an argument of true is sent to the
call, the resulting list will contain the names of all cells of all mimics
too.</dd>
</dl><div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
x<span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span>x f<span class="sy0">=</span><span class="nu0">42</span>x cellNames<span class="co1">;; return [:f]</span> x cellNames<span class="br0">(</span><span class="re6"><span class="re7">true</span></span><span class="br0">)</span><span class="co1">;; return a long list, including :f</span>
</pre></div>
</div>
<dl><dt>cells</dt>
<dd>Just like cellNames return the names of all the cells, the "cells" method
will return a Dict of all the cells with their values. And just like cellNames,
cells take an optional boolean argument on whether to include the cells of
mimics too.</dd>
</dl><div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
x<span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span>x f<span class="sy0">=</span><span class="nu0">42</span>x cells<span class="co1">;; return {f: 42}</span> x cells<span class="br0">(</span><span class="re6"><span class="re7">true</span></span><span class="br0">)</span><span class="co1">;; return a large dict, including f: 42</span>
</pre></div>
</div>
<dl><dt>mimics</dt>
<dd>Returns a list of all direct mimics of the receiver.</dd>
</dl><dl><dt>mimics?</dt>
<dd>Takes one object as argument and returns true or false depending on if the
argument is anywhere in the receiving objects mimic chain.</dd>
</dl><dl><dt>message</dt>
<dd>Takes one symbol argument and creates a new Message mimic with that
argument as its name.</dd>
</dl><dl><dt>Message code</dt>
<dd>Returns a text that describes the code this message chain represents. It
will hide some of the internal shuffling, but operators will be displayed using
canonical form.</dd>
</dl><dl><dt>Message formattedCode</dt>
<dd>Returns a text that is formatted and indented in a canonical way. This
method is used to generate the documentation code for DokGen, among other
things.</dd>
</dl><dl><dt>Message evalArgAt</dt>
<dd>Takes the index of the argument to evaluate, and the ground to evaluate it
on - returns the result of evaluating the argument.</dd>
</dl><dl><dt>Message fromText</dt>
<dd>Takes one text argument that should contain Ioke code, and returns the
parsed message chain from that code, without evaluating it.</dd>
</dl><dl><dt>Message doText</dt>
<dd>Takes one text argument that should contain Ioke code, and returns the
result of evaluating that code in the current context.</dd>
</dl><dl><dt>Message filename</dt>
<dd>Returns the filename where the receiving message was defined.</dd>
</dl><dl><dt>Message line</dt>
<dd>Returns the line number where the receiving message was defined.</dd>
</dl><dl><dt>Message position</dt>
<dd>Returns the position in the line where the receiving message was
defined.</dd>
</dl><dl><dt>Message name</dt>
<dd>Returns the name of the message. The name of the message is what you
generally talk about when saying you send a message. It can also be called the
selector in other languages.</dd>
</dl><dl><dt>Message name=</dt>
<dd>Update the message with a new name. From this point on the message will
only have that name, so doing this on a message that is part of an existing
message chain will change the behavior of that code:</dd>
</dl><div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
msg<span class="sy0">=</span><span class="re9"><span class="re11">Message</span></span>fromText<span class="br0">(</span><span class="st0">"2 + 1"</span><span class="br0">)</span>msg next name<span class="sy0">=</span><span class="st0">"-"</span>msg code<span class="co1">;; "2 -(1)"</span>
</pre></div>
</div>
<dl><dt>Message prev</dt>
<dd>Returns the prev pointer of this message, or nil if no prev pointer
exists.</dd>
</dl><dl><dt>Message prev=</dt>
<dd>Sets the prev pointer of a message. The new value should be either nil or
another message.</dd>
</dl><dl><dt>Message next</dt>
<dd>Returns the next pointer of this message, or nil if no next pointer
exists.</dd>
</dl><dl><dt>Message next=</dt>
<dd>Sets the next pointer of a message. The new value should be either nil or
another message.</dd>
</dl><dl><dt>Message sendTo</dt>
<dd>Sends a message to an object. It's important to realize that sendTo will
not evaluate the whole message chain -- it will only send one message with
arguments to an object.</dd>
</dl><dl><dt>Message keyword?</dt>
<dd>Returns true if this message is a keyword message, and false
otherwise.</dd>
</dl><p>There are many more methods that can be used to do interesting introspection
and reflection in Ioke. The reference documentation includes them all. Most of
the interesting stuff can be found on the Message kind.</p>
<dl><dt>send</dt>
<dd>In many cases you want to activate something activatable in a cell, with a
specific receiver. You can do this using send. You can send messages to most
objects. Send takes one argument that should evaluate to the name of the
message to send, and then sends along all other arguments given to send to the
new message. These arguments will remain unevaluated, and will be evaluated at
the leisure of the final method activated.</dd>
</dl><a name="Aspects"></a>
<h1><span class="mw-headline">Aspects</span></h1>
<p>In many circumstances you might want to do several different things in a
specific method. That generally goes against good software engineering, that
says every piece of code should only have one responsibility. Aspect oriented
programming tackles this by allowing you to slice code along a different
dimension compared to the regular object oriented paradigm. Ioke has a small
version of this, that allow you to add advice to cells. This advice can be
before, after or around. All of them will get access to the arguments given in
the original message, but after-advice also gets access to the value returned
from the main cell. Finally, around-advice also gets the responsibility to
invoke the original cell, so an around-advice could choose to not invoke it at
all, or it could invoke it with different arguments, or maybe invoke it several
times.</p>
<p>Ioke currently only allows you to add or remove advice. To be able to remove
advice, you need to name it when adding it. Unnamed advice can not be removed.
Advice can be wrapped. It will be applied in an outside-in approach, where the
most recently added advice will execute first.</p>
<p>The return value of before and after advice doesn't matter, but the return
value of around-advice will be interpreted as the new return value of the
message send.</p>
<p>To manipulate advice in Ioke, you need to describe what to manipulate. This
description will return a Pointcut, that can then be used to inject advice at
that point. Pointcuts can be defined in several ways. The easiest is to define
it in terms of a cell name. Using this approach is the only way to define
advice for non-existent cells.</p>
<p>To create a Pointcut, call before, after or around on the receiver where the
Pointcut should belong. The arguments specify what should be matched by the
pointcut. You can see some examples of pointcuts here:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="co1">; matches cells foo and bar</span><span class="re9"><span class="re11">Text</span></span>before<span class="br0">(</span><span class="re12"><span class="re13">:</span>foo,</span><span class="re12"><span class="re13">:</span>bar<span class="br0">)</span></span> X<span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span><span class="co1">; will not match anything</span>X around<span class="br0">(</span>matching<span class="re13">:</span><span class="re12"><span class="re13">:</span>anyFromSelf<span class="br0">)</span></span> X foo<span class="sy0">=</span><span class="nu0">123</span><span class="co1">; will now match foo</span>X around<span class="br0">(</span>matching<span class="re13">:</span><span class="re12"><span class="re13">:</span>anyFromSelf<span class="br0">)</span></span> <span class="co1">; any cell name matching the regexp</span>X after<span class="br0">(</span>matching<span class="re13">:</span><span class="sy0">#/</span>foo<span class="sy0">/</span><span class="br0">)</span> <span class="co1">; matches any at all, except foo</span>X before<span class="br0">(</span>matching<span class="re13">:</span><span class="re12"><span class="re13">:</span>any,</span>except<span class="re13">:</span><span class="re12"><span class="re13">:</span>foo<span class="br0">)</span></span><span class="co1">; matches any at all, except anything that matches foo</span>X before<span class="br0">(</span>matching<span class="re13">:</span><span class="re12"><span class="re13">:</span>any,</span>except<span class="re13">:</span><span class="sy0">#/</span>foo<span class="sy0">/</span><span class="br0">)</span> <span class="co1">; use a block for matching</span>X around<span class="br0">(</span>matching<span class="re13">:</span><span class="re8">fn</span><span class="br0">(</span>x, x<span class="sy0">==</span><span class="re12"><span class="re13">:</span>blurg<span class="br0">)</span><span class="br0">)</span></span> <span class="co1">; use a list to provide alternatives</span>X before<span class="br0">(</span>matching<span class="re13">:</span><span class="br0">[</span><span class="sy0">#/</span>foo<span class="sy0">/</span>,<span class="sy0">#/</span>bar<span class="sy0">/</span><span class="br0">]</span><span class="br0">)</span>
</pre></div>
</div>
<p>As you can see from these examples, the pointcuts can be fairly advanced and
specific in what they match. The option to send in a block makes it possible to
check any property while matching.</p>
<p>OK, once you have a Pointcut, there are three different methods you can
call. These are <<, add, and remove!. The first one adds an unnamed
advice, the second adds a named advice and the third one removes a named
advice. Advice is any object that can be activated or called, so a method, a
block, a macro or a syntax is fine.</p>
<p>It's time to see what it looks like to add advice. Before-advice is the
easiest kind. The important thing to remember is that the code will get the
same arguments as the original call, which means it will also signal an error
if the arguments doesn't match.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
X before<span class="br0">(</span><span class="re12"><span class="re13">:</span>foo<span class="br0">)</span></span><span class="sy0"><<</span><span class="re8">method</span><span class="br0">(</span>x,<span class="st0">"got #{x}"</span>println<span class="br0">)</span>X before<span class="br0">(</span>matching<span class="re13">:</span><span class="re12"><span class="re13">:</span>anyFromSelf<span class="br0">)</span></span><span class="sy0"><<</span><span class="re8">macro</span><span class="br0">(</span> <span class="st0">"called #{call message name}"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>This code doesn't do anything strange at all.</p>
<p>Next up we have after-advice. The only difference here is that after-advice
automatically gets a cell that is set to adviceResult, that can be used inside
the method.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
X after<span class="br0">(</span><span class="re12"><span class="re13">:</span>foo<span class="br0">)</span></span><span class="sy0"><<</span><span class="re8">method</span><span class="br0">(</span><span class="sy0">+</span>args, <span class="st0">"foo resulted in: #{aspectResult}"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>Remember that the result value of before and after advice doesn't count. It
is thrown away. But these methods can still affect things by side effects. They
can also be used for validation. A condition signalled inside of an advice
would have the same effect as if done in the method itself - namely
interrupting the flow of control.</p>
<p>The final advice is around advice. These are different in two ways. First,
they get access to a cell called aspectCall, which can be used to invoke the
real cell (and the next chain of advice, of course). The second difference is
that the result of the around advice will be the return value from the cell.
So, you can imagine the around-advice executing instead of the original code.
If you forget to invoke it, the original cell won't be invoked at all.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
X around<span class="br0">(</span><span class="re12"><span class="re13">:</span>non_existant<span class="br0">)</span></span><span class="sy0"><<</span><span class="re8">method</span><span class="br0">(</span> <span class="nu0">42</span><span class="br0">)</span> X around<span class="br0">(</span><span class="re12"><span class="re13">:</span>foo<span class="br0">)</span></span><span class="sy0"><<</span><span class="re8">macro</span><span class="br0">(</span>arg1, arg2, <span class="st0">"before"</span>println res<span class="sy0">=</span>aspectResult<span class="br0">(</span>arg2, arg1<span class="br0">)</span> <span class="st0">"got: #{res}"</span>println <span class="nu0">42</span><span class="br0">)</span>
</pre></div>
</div>
<p>The first piece of code show that you can actually use an around advice
around something that doesn't exist. But if you do call aspectCall inside of
it, that will generate a NoSuchCell condition, of course. In the second example
we first log some information, then invoke the original code with switched
argument order, saves away the result, prints the result, and finally returns
42. There you can see most of the things that can be done inside of an around
macro.</p>
<p>The aspect system in Ioke is implemented in Ioke itself, and is fairly small
at the moment. The guiding principle behind it is that it shouldn't have an
impact on code that doesn't use it. It is a highly useful feature that makes it
possible to decompose code substantially. As an example of a common place for
aspect usage is initialization. This is defined as an around-advice that looks
like this:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="re9"><span class="re11">Origin</span></span>around<span class="br0">(</span><span class="re12"><span class="re13">:</span><span class="re6">mimic</span><span class="br0">)</span></span><span class="sy0"><<</span><span class="re8">method</span><span class="br0">(</span><span class="sy0">+</span>rest,<span class="sy0">+</span><span class="re12"><span class="re13">:</span>krest,</span> newMimic<span class="sy0">=</span>aspectCall if<span class="br0">(</span>newMimic cell?<span class="br0">(</span><span class="re12"><span class="re13">:</span>initialize<span class="br0">)</span>,</span> newMimic initialize<span class="br0">(</span><span class="sy0">*</span>rest,<span class="sy0">*</span>krest<span class="br0">)</span><span class="br0">)</span> newMimic<span class="br0">)</span>
</pre></div>
</div>
<p>Note first that the around advice takes any kind of arguments, but doesn't
send them along to mimic. Instead it checks if there is an initialize-cell, and
in that case invokes it with the arguments given to the mimic call. It finally
returns the original result.</p>
<a name="Importing"></a>
<h1><span class="mw-headline">Importing</span></h1>
<p>To import new code into Ioke, the method<code>use</code>should be used. The
terminology is that you give "use" a name of a module to include, and if that
module has already been included it will not be evaluated again. If it has not
been included,<code>use</code>will try to find the module using several
different heuristics. It will add a<tt>.ik</tt>to the name and try to look up a
file of that name - but it will also try to look it up without a<tt>.ik</tt>,
if a full file name has been given. Several different places will be searched,
and the exact order and what will be searched can be found by calling
the<code>System loadPath</code>method. This will return a list of all the
places that Ioke uses to search for modules. This list can be modified to add
more directories to the load path at runtime.</p>
<p>If a module of the specified name can't be found, a condition will be
signalled.</p>
<a name="Core_kinds"></a>
<h1><span class="mw-headline">Core kinds</span></h1>
<p>Ioke obviously contains lots of different data types, but there are some
that are much more important than others. In this chapter I'll take a look at
these and talk about how to work with them correctly.</p>
<a name="Conditions"></a>
<h2><span class="mw-headline">Conditions</span></h2>
<p>One of the major parts of Ioke is the condition system. Unlike most other
programming languages, Ioke doesn't have exceptions. Instead it has conditions,
where errors are a specific kind of condition. The condition system comprises
several different things. Specifically, the condition system uses the kinds
Condition, Restart, Handler and Rescue. Restarts are mostly orthogonal to the
rest of the system.</p>
<p>The way the condition system works is this. When something happens, a
program can elect to signal a condition. This can be done using "signal!",
"warn!" or "error!". Both "warn!" and "error!" use "signal!" under the covers,
but do some other things as well. A condition will always mimic Condition. Each
of these three methods can be called in three different ways. First, you can
call them with a text argument. In that case the signalled condition will be
the default for that type. (The default for "signal!" is Condition Default. The
default for "warn!" is Condition Warning Default and the default for "error!"
is Condition Error Default.) A new mimic of the default condition will be
created, and a cell called text will be set to the text argument. The second
variation is to give an instance of an existing condition to one of the
methods. In that case that condition will be signalled unmodified. Finally, the
third version gives a condition mimic and one or more keyword arguments with
data to set on that condition. In that case a mimic of the condition will be
created, and then cells with data set based on the arguments.</p>
<p>If a signal is not handled, nothing happens.</p>
<p>If a warning is not handled, a message will be printed with the text of that
warning.</p>
<p>If an error is not handled, the debugger will be invoked - if a debugger is
available. Otherwise the program will be terminated.</p>
<p>A Rescue allows conditions to unwind the stack to the place where the rescue
is established. Combining rescues and conditions looks a lot like regular
exception handling in other programming languages.</p>
<p>A Handler on the other hand will run code in the dynamic context of the
place where the condition was signalled. A handler can invoke restarts to
handle an error state at the place it happened, and as such doesn't have to
actually unwind the stack anywhere. Any number of handlers can run - the last
handler to run will be either the last handler, the handler that activates a
restart, or the last handler before a valid rescue for that condition.</p>
<p>A restart is a way to allow ways of getting back to a valid state. Take the
example of referring to a cell that doesn't exist. Before signalling a
condition, Ioke will set up restarts so you can provide a value to use in the
case a cell doesn't exist. This restart will use that new value and continue
execution at the point where it would otherwise have failed.</p>
<p>A restart can have a name. If it doesn't have a name it can only be used
interactively. You can use findRestart to get hold of the closest restart with
a given name. You can invoke a given restart with invokeRestart, which takes
either the name of a restart or a restart mimic. Finally, you can get all
available restarts using availableRestarts.</p>
<p>Both handlers, rescues and restarts are established inside a call to the
bind macro. All arguments to this macro need to be either handlers, rescues or
restarts, except for the last argument which should be the code to execute.</p>
<p>You create a new handler by calling the method "handle". You create a new
rescue by calling the method "rescue". You create a new restart by calling the
method "restart". These all take funky arguments, so refer to the reference to
better understand how they work.</p>
<p>This small example doesn't necessarily show the power of conditions, but it
can give an idea about how it works.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="co1">;; to handle any problem</span>bind<span class="br0">(</span> rescue<span class="br0">(</span><span class="re8">fn</span><span class="br0">(</span>c,<span class="re6"><span class="re7">nil</span></span><span class="br0">)</span><span class="br0">)</span>,<span class="co1">;; do nothing in the rescue</span> error!<span class="br0">(</span><span class="st0">"This is bad!!"</span><span class="br0">)</span><span class="br0">)</span> <span class="co1">;; to print all conditions happening, but not do anything</span>bind<span class="br0">(</span> handle<span class="br0">(</span><span class="re8">fn</span><span class="br0">(</span>c, c println<span class="br0">)</span><span class="br0">)</span>, signal!<span class="br0">(</span><span class="st0">"something"</span><span class="br0">)</span> signal!<span class="br0">(</span><span class="st0">"something more"</span><span class="br0">)</span> warn!<span class="br0">(</span><span class="st0">"A warning!!"</span><span class="br0">)</span><span class="br0">)</span> <span class="co1">;; rescue either of two conditions</span>C1<span class="sy0">=</span><span class="re9"><span class="re11">Condition</span></span><span class="re11">Error</span><span class="re6">mimic</span>C2<span class="sy0">=</span><span class="re9"><span class="re11">Condition</span></span><span class="re11">Error</span><span class="re6">mimic</span> bind<span class="br0">(</span> rescue<span class="br0">(</span>C1, C2,<span class="re8">fn</span><span class="br0">(</span>c,<span class="st0">"got an error: #{c}"</span>println<span class="br0">)</span><span class="br0">)</span>, error!<span class="br0">(</span>C1<span class="br0">)</span><span class="br0">)</span> <span class="co1">;; invoke a restart when no such cell is signaled</span>bind<span class="br0">(</span> handle<span class="br0">(</span><span class="re9"><span class="re11">Condition</span></span><span class="re11">Error</span><span class="re11">No</span>SuchCell,<span class="re8">fn</span><span class="br0">(</span>c, invokeRestart<span class="br0">(</span><span class="re12"><span class="re13">:</span>useValue,</span><span class="nu0">42</span><span class="br0">)</span><span class="br0">)</span><span class="br0">)</span>, blarg println<span class="br0">)</span><span class="co1">;; will print 42</span> <span class="co1">;; establish a restart</span>bind<span class="br0">(</span> restart<span class="br0">(</span>something,<span class="re8">fn</span><span class="br0">(</span><span class="sy0">+</span>args, args println<span class="br0">)</span><span class="br0">)</span>, invokeRestart<span class="br0">(</span><span class="re12"><span class="re13">:</span>something,</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">)</span><span class="br0">)</span>
</pre></div>
</div>
<p>The code above shows several different things you can do with the condition
system. It is a very powerful system, so I recommend trying to understand it.
It lies at the core of many things in Ioke, and some parts will not make sense
without a deep understanding of conditions. For more information on what such a
system is capable of, look for documentation about the Common Lisp condition
system, which has been a heavy influence on Ioke. Also, the debugger in IIk
uses the condition system to implement its functionality.</p>
<p>There are many conditions defined in the core of Ioke, and they are used by
the implementation to signal error conditions of different kinds. Refer to the
reference to see which conditions are available.</p>
<p>Finally, one thing that you might miss if you're used to exceptions in other
languages, is a construct that makes it possible to ensure that code gets
executed, even if a non-local flow control happens. Don't despair, Ioke has
one. It is called ensure, and works mostly like ensure in Ruby, and finally in
Java. It takes one main code argument, followed by zero or more arguments that
contain the code to always make sure executes. It looks like this:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
ensure<span class="br0">(</span> conn<span class="sy0">=</span><span class="re11">Database</span>open conn SELECT<span class="sy0">*</span>FROM a_table, conn close!, conn reallyClose!, conn reallyReallyReallyClose!<span class="br0">)</span>
</pre></div>
</div>
<p>This code uses a hypothetical database library, opens up a connection, does
something, and then in three different ensure blocks tries to ensure that it
really is closed afterwards. The return value of the ensure block will still be
the return value of the last expression in the main code. Non local flow
control can happen inside of the ensure block, but exactly what will happen is
undefined -- so avoid it, please.</p>
<a name="Text_2"></a>
<h2><span class="mw-headline">Text</span></h2>
<p>In Ioke, the equivalent of Strings in other languages are called Text. This
better describes the purpose of the type. Ioke Text is immutable. All
operations that would change the text returns a new object instead. If you are
used to Java strings or Ruby strings, then most operations available on Ioke
Texts will not come as a surprise.</p>
<p>To create a new Text, you use the literal syntax as described in the syntax
chapter. You can use interpolation to include dynamic data.</p>
<p>You can do several things with Ioke text. These examples show some of the
methods:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="co1">;; repeat a text several times</span><span class="st0">"foo"</span><span class="sy0">*</span><span class="nu0">3</span><span class="co1">;; => "foofoofoo"</span> <span class="co1">;; concatenate two texts</span><span class="st0">"foo"</span><span class="sy0">+</span><span class="st0">"bar"</span><span class="co1">;; => "foobar"</span> <span class="co1">;; get the character at a specific index</span><span class="st0">"foo"</span><span class="br0">[</span><span class="nu0">1</span><span class="br0">]</span><span class="co1">;; => 111</span> <span class="co1">;; get a subset of text</span><span class="st0">"foo"</span><span class="br0">[</span>1<span class="sy0">..</span>1<span class="br0">]</span><span class="co1">;; => "o"</span><span class="st0">"foo"</span><span class="br0">[</span>0<span class="sy0">..</span>1<span class="br0">]</span><span class="co1">;; => "fo"</span><span class="st0">"foo"</span><span class="br0">[</span>0<span class="sy0">...</span>1<span class="br0">]</span><span class="co1">;; => "f"</span> <span class="st0">"foxtrot"</span><span class="br0">[</span>1<span class="sy0">..</span><span class="re0">-</span><span class="nu0">1</span><span class="br0">]</span><span class="co1">;; => "oxtrot"</span><span class="st0">"foxtrot"</span><span class="br0">[</span>1<span class="sy0">...</span><span class="re0">-</span><span class="nu0">1</span><span class="br0">]</span><span class="co1">;; => "oxtro"</span> <span class="co1">;; is a text empty?</span><span class="st0">"foo"</span>empty? <span class="co1">;; => false</span><span class="st0">""</span>empty? <span class="co1">;; => true</span> <span class="co1">;; the length of the text</span><span class="st0">"foo"</span>length <span class="co1">;; => 3</span><span class="st0">""</span>length <span class="co1">;; => 0</span> <span class="co1">;; replace the first occurrence of something with something else</span><span class="st0">"hello fox fob folk"</span>replace<span class="br0">(</span><span class="st0">"fo"</span>,<span class="st0">"ba"</span><span class="br0">)</span> <span class="co1">;; => "hello bax fob folk"</span> <span class="co1">;; replace all occurrences of something with something else</span><span class="st0">"hello fox fob folk"</span>replaceAll<span class="br0">(</span><span class="st0">"fo"</span>,<span class="st0">"ba"</span><span class="br0">)</span> <span class="co1">;; => "hello bax bab balk"</span> <span class="co1">;; split around a text</span><span class="st0">"foo bar bax"</span>split<span class="br0">(</span><span class="st0">" "</span><span class="br0">)</span> <span class="co1">;; => ["foo", "bar", "bax"]</span>
</pre></div>
</div>
<p>The Text kind contains lots of useful functionality like this. The purpose
is to make it really easy to massage text of any kind.</p>
<p>One important tool for doing that is the "format" method. This is a mix
between C printf and Common Lisp format. At the moment, it only contains a
small amount of functionality, but it can still be very convenient.
Specifically you can print each element in a list directly by using format,
instead of concatenating text yourself.</p>
<p>The "format" method takes format specifiers that begin with %, and then
inserts one of its arguments in different ways depending on what kind of format
specifier is used.</p>
<p>Some examples of format follow:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="co1">;; insert simple value as text</span><span class="st0">"%s"</span>format<span class="br0">(</span><span class="nu0">123</span><span class="br0">)</span><span class="co1">;; => "123"</span> <span class="co1">;; insert value right justified by 6</span><span class="st0">"%6s"</span>format<span class="br0">(</span><span class="nu0">123</span><span class="br0">)</span><span class="co1">;; => " 123"</span> <span class="co1">;; insert value left justified by 6</span><span class="st0">"%-6s"</span>format<span class="br0">(</span><span class="nu0">123</span><span class="br0">)</span><span class="co1">;; => "123 "</span> <span class="co1">;; insert two values</span><span class="st0">"%s: %s"</span>format<span class="br0">(</span><span class="nu0">123</span>,<span class="nu0">321</span><span class="br0">)</span><span class="co1">;; => "123: 321"</span> <span class="co1">;; insert a list of values formatted the same</span><span class="st0">"%[%s, %]<span class="es0">\n</span>"</span>format<span class="br0">(</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">]</span><span class="br0">)</span> <span class="co1">;; => "1, 2, 3, \n"</span> <span class="co1">;; insert a dict of values formatted the same</span><span class="st0">"%:[%s => %s, %]<span class="es0">\n</span>"</span>format<span class="br0">(</span><span class="br0">{</span>sam<span class="re13">:</span><span class="nu0">3</span>, toddy<span class="re13">:</span><span class="nu0">10</span><span class="br0">}</span><span class="br0">)</span> <span class="co1">;; => "sam => 3, toddy => 10, \n"</span> <span class="co1">;; insert splatted values from a list</span><span class="st0">"wow: %*[%s: %s %]"</span>format<span class="br0">(</span><span class="br0">[</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span><span class="br0">]</span>,<span class="br0">[</span><span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">]</span>,<span class="br0">[</span><span class="nu0">3</span>,<span class="nu0">4</span><span class="br0">]</span><span class="br0">]</span><span class="br0">)</span> <span class="co1">;; => "wow: 1: 2 2: 3 3: 4 "</span>
</pre></div>
</div>
<a name="Numbers"></a>
<h2><span class="mw-headline">Numbers</span></h2>
<p>As mentioned in the section on syntax, Ioke supports decimal numbers,
integers and ratios. A Ratio will be created when two integers can't be divided
evenly. A Ratio will always use the GCD. In most cases Ratios, Decimals and
Integers can interact with each other as would be expected. The one thing that
might surprise people is that Ioke doesn't have any inexact floating point data
type. Instead, decimals are exact and can have any size. This means they are
well suited to represent such things as money, since operations will always
have well defined results.</p>
<p>All expected math works fine on Ioke numbers. The reference for numbers more
closely specify what is possible. One thing to notice is that the % operator
implements modulus, not remainder. This might be unintuitive for some
developers. What that means is that it is not an error to ask for the modulus
of 0: "13 % 0", since there is no division necessary in this operation.</p>
<p>In addition to the above, Integers have the "times" method described
earlier. It can also return the successor and predecessor of itself with the
"pred" and "succ" methods.</p>
<a name="Lists"></a>
<h2><span class="mw-headline">Lists</span></h2>
<p>Ioke has lists that expand to the size needed. These lists can be created
using a simple literal syntax. They can contain any kind of element, including
itself (although don't try to print such a list). Ioke List mixes in the
Enumerable mixin, which gives it quite powerful capabilities.</p>
<p>A list can be created using the "list" or "[]" methods:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="co1">;; an empty list</span><span class="br0">[</span><span class="br0">]</span> <span class="co1">;; the same list created in two different ways</span>list<span class="br0">(</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">)</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">]</span> <span class="co1">;; a list with different elements</span><span class="br0">[</span><span class="nu0">1</span>,<span class="st0">"one"</span>,<span class="re12"><span class="re13">:</span>one<span class="br0">]</span></span>
</pre></div>
</div>
<p>Except for the Enumerable methods, List also defines many other methods that
can be highly useful. Some examples are shown below:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
l<span class="sy0">=</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">]</span> <span class="co1">;; add two lists together</span>l<span class="sy0">+</span>l<span class="co1">;; => [1, 2, 3, 1, 2, 3]</span> <span class="co1">;; return the difference of two lists</span>l<span class="sy0">-</span><span class="br0">[</span><span class="nu0">2</span><span class="br0">]</span><span class="co1">;; => [1, 3]</span> <span class="co1">;; add a new value to a list</span>l<span class="sy0"><<</span><span class="nu0">42</span>l<span class="sy0">==</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">42</span><span class="br0">]</span><span class="co1">;; => true</span> <span class="co1">;; get a specific element from the list</span>l<span class="br0">[</span><span class="nu0">0</span><span class="br0">]</span><span class="co1">;; => 1</span> <span class="co1">;; -1 returns the last, -2 the next to last</span>l<span class="br0">[</span><span class="re0">-</span><span class="nu0">1</span><span class="br0">]</span><span class="co1">;; => 42</span> <span class="co1">;; an index outside the boundaries return nil</span>l<span class="br0">[</span><span class="nu0">10</span><span class="br0">]</span><span class="co1">;; => nil</span> <span class="co1">;; assign a new value</span>l<span class="br0">[</span><span class="nu0">3</span><span class="br0">]</span><span class="sy0">=</span><span class="nu0">40</span>l<span class="sy0">==</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">40</span><span class="br0">]</span><span class="co1">;; => true</span> l<span class="br0">[</span><span class="re0">-</span><span class="nu0">1</span><span class="br0">]</span><span class="sy0">=</span><span class="nu0">39</span>l<span class="sy0">==</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">39</span><span class="br0">]</span><span class="co1">;; => true</span> <span class="co1">;; assign an out of bounds value</span>l<span class="br0">[</span><span class="nu0">10</span><span class="br0">]</span><span class="sy0">=</span><span class="nu0">13</span>l<span class="sy0">==</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">39</span>,<span class="re6"><span class="re7">nil</span></span>,<span class="re6"><span class="re7">nil</span></span>,<span class="re6"><span class="re7">nil</span></span>,<span class="re6"><span class="re7">nil</span></span>,<span class="re6"><span class="re7">nil</span></span>,<span class="re6"><span class="re7">nil</span></span>,<span class="nu0">13</span><span class="br0">]</span> <span class="co1">;; => true</span> <span class="co1">;; at and at= is the same as [] and []=</span>l at<span class="br0">(</span><span class="nu0">0</span><span class="br0">)</span><span class="co1">;; => 1</span> <span class="co1">;; empty the list</span>l clear! l<span class="sy0">==</span><span class="br0">[</span><span class="br0">]</span><span class="co1">;; => true</span> <span class="co1">;; follows the each protocol</span>l each<span class="br0">(</span>println<span class="br0">)</span> <span class="co1">;; is empty?</span>l empty?<span class="co1">;; => true</span> <span class="co1">;; does it include an element?</span>l include?<span class="br0">(</span><span class="re12"><span class="re13">:</span>foo<span class="br0">)</span></span><span class="co1">;; => false</span> <span class="co1">;; the last element</span>l last<span class="co1">;; => nil</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span><span class="br0">]</span>last<span class="co1">;; => 2</span> <span class="co1">;; the length</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span><span class="br0">]</span>length<span class="co1">;; => 2</span> <span class="co1">;; first value</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span><span class="br0">]</span>first<span class="co1">;; => 1</span> <span class="co1">;; rest except for first</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">]</span>rest<span class="co1">;; => [2, 3]</span> <span class="co1">;; returns a new sorted list</span><span class="br0">[</span><span class="nu0">3</span>,<span class="nu0">2</span>,<span class="nu0">1</span><span class="br0">]</span>sort<span class="co1">;; => [1, 2, 3]</span> <span class="co1">;; sorts in place</span>l<span class="sy0">=</span><span class="br0">[</span><span class="nu0">3</span>,<span class="nu0">2</span>,<span class="nu0">1</span><span class="br0">]</span>l sort! l<span class="sy0">==</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">]</span><span class="co1">;; => true</span>
</pre></div>
</div>
<a name="Dicts"></a>
<h2><span class="mw-headline">Dicts</span></h2>
<p>A Dict is a dictionary of key-value mappings. The mappings are unordered,
and there can only ever be one key with the same value. Any kind of Ioke object
can be used as a key. There is no problem with having the same value for
different keys. The default implementation of Dict uses a hash-based
implementation. That's not necessarily always true for all dicts. The iteration
order is not necessarily stable either, so don't write code that depends on
it.</p>
<p>Creating a dict is done using either the "dict" or the "{}" methods. Both of
these expect either keyword arguments or mimics of Pair. If keyword arguments,
these keywords will be used as symbol keys. That's the most common thing, so it
makes sense to have that happen automatically. Dicts also try to print
themselves that way.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
dict<span class="br0">(</span><span class="nu0">1</span><span class="sy0">=></span><span class="nu0">2</span>,<span class="nu0">3</span><span class="sy0">=></span><span class="nu0">4</span><span class="br0">)</span> <span class="co1">;; these two are the same</span>dict<span class="br0">(</span>foo<span class="re13">:</span><span class="st0">"bar"</span>, baaz<span class="re13">:</span><span class="st0">"quux"</span><span class="br0">)</span>dict<span class="br0">(</span><span class="re12"><span class="re13">:</span>foo</span><span class="sy0">=></span><span class="st0">"bar"</span>,<span class="re12"><span class="re13">:</span>baaz</span><span class="sy0">=></span><span class="st0">"quux"</span><span class="br0">)</span> <span class="br0">{</span><span class="nu0">1</span><span class="sy0">=></span><span class="nu0">2</span>,<span class="nu0">3</span><span class="sy0">=></span><span class="nu0">4</span><span class="br0">}</span> <span class="co1">;; these two are the same</span><span class="br0">{</span>foo<span class="re13">:</span><span class="st0">"bar"</span>, baaz<span class="re13">:</span><span class="st0">"quux"</span><span class="br0">}</span><span class="br0">{</span><span class="re12"><span class="re13">:</span>foo</span><span class="sy0">=></span><span class="st0">"bar"</span>,<span class="re12"><span class="re13">:</span>baaz</span><span class="sy0">=></span><span class="st0">"quux"</span><span class="br0">}</span> <span class="co1">;; the formats can be combined:</span><span class="br0">{</span><span class="nu0">1</span><span class="sy0">=></span><span class="nu0">2</span>, foo<span class="re13">:</span><span class="nu0">42</span>,<span class="st0">"bar"</span><span class="sy0">=></span><span class="st0">"qux"</span><span class="br0">}</span>
</pre></div>
</div>
<p>The literal Pair syntax (using =>) will not necessarily instantiate real
pairs for this.</p>
<p>Dicts mix in Enumerable. When using each, what will be yielded are mimics of
Pair, where the first value will be the key and the second will be value. Just
like Lists, Dicts have several useful methods in themselves:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
d<span class="sy0">=</span><span class="br0">{</span>one<span class="re13">:</span><span class="st0">"two"</span>,<span class="nu0">3</span><span class="sy0">=></span><span class="nu0">4</span><span class="br0">}</span> <span class="co1">;; lookup with [], "at" works the same</span>d<span class="br0">[</span><span class="re12"><span class="re13">:</span>one<span class="br0">]</span></span><span class="co1">;; => "two"</span>d<span class="br0">[</span><span class="re12"><span class="re13">:</span>two<span class="br0">]</span></span><span class="co1">;; => nil</span>d<span class="br0">[</span><span class="nu0">3</span><span class="br0">]</span> <span class="co1">;; => 4</span>d<span class="br0">[</span><span class="nu0">4</span><span class="br0">]</span> <span class="co1">;; => nil</span> <span class="co1">;; assign values with []=</span>d<span class="br0">[</span><span class="re12"><span class="re13">:</span>one<span class="br0">]</span></span><span class="sy0">=</span><span class="st0">"three"</span>d<span class="br0">[</span><span class="re12"><span class="re13">:</span>new<span class="br0">]</span></span><span class="sy0">=</span><span class="st0">"wow!"</span> d<span class="sy0">==</span><span class="br0">{</span>one<span class="re13">:</span><span class="st0">"three"</span>,<span class="nu0">3</span><span class="sy0">=></span><span class="nu0">4</span>, new<span class="re13">:</span><span class="st0">"wow!"</span><span class="br0">}</span> <span class="co1">;; iterate over it</span>d each<span class="br0">(</span>value println<span class="br0">)</span> <span class="co1">;; get all keys</span>d keys<span class="sy0">==</span>set<span class="br0">(</span><span class="re12"><span class="re13">:</span>one,</span><span class="re12"><span class="re13">:</span>new,</span><span class="nu0">3</span><span class="br0">)</span>
</pre></div>
</div>
<a name="Sets"></a>
<h4><span class="mw-headline">Sets</span></h4>
<p>If you want an object that work like a mathematical set, Ioke provides such
a kind for you. There is no support for literal syntax for sets, but you can
create new with the set method. A set can be iterated over and it is
Enumerable. You can add and remove elements, and check for membership.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
x<span class="sy0">=</span>set<span class="br0">(</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">3</span>,<span class="nu0">2</span>,<span class="nu0">1</span><span class="br0">)</span> x map<span class="br0">(</span><span class="sy0">*</span><span class="nu0">2</span><span class="br0">)</span>sort<span class="co1">; => [2, 4, 6]</span> x<span class="sy0">===</span><span class="nu0">1</span><span class="co1">; => true</span>x<span class="sy0">===</span><span class="nu0">0</span><span class="co1">; => false</span> x remove!<span class="br0">(</span><span class="nu0">2</span><span class="br0">)</span>x<span class="sy0">===</span><span class="nu0">2</span><span class="co1">; => false</span> x<span class="sy0"><<</span><span class="nu0">4</span>x<span class="sy0">===</span><span class="nu0">4</span><span class="co1">; => true</span>
</pre></div>
</div>
<a name="Ranges_and_Pairs"></a>
<h4><span class="mw-headline">Ranges and Pairs</span></h4>
<p>Both ranges and pairs tie two values together. They also have literal syntax
to create them, since they are very useful in many circumstances.</p>
<p>A Range defines two endpoints. A Range is Enumerable and you can also check
for membership. It's also convenient to send Ranges to the "List []" method. A
Range can be exclusive or inclusive. If it's inclusive it includes the end
value, and if it is exclusive it doesn't.</p>
<p>An addition to Ioke S is the possibility of inverted ranges. If the first
value is larger than the second value, then the range is inverted. This puts
slightly different demands on the objects inside of it. Specifically, if you
want to iterate over the elements, the kind you're using need to have a method
called 'pred' for predecessor, instead of 'succ' for successor. Membership can
still be tested, as long as <=> is defined. So you can do something like
this: ("foo".."aoo") === "boo". It's mostly useful for iterating in the
opposite direction, like with 10..1, for example.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="co1">;; literal syntax for inclusive range</span>1<span class="sy0">..</span>10 <span class="co1">;; literal syntax for exclusive range</span>1<span class="sy0">...</span>10 <span class="co1">;; check for membership</span><span class="br0">(</span>1<span class="sy0">..</span>10<span class="br0">)</span><span class="sy0">===</span><span class="nu0">5</span><span class="co1">;; => true</span><span class="br0">(</span>1<span class="sy0">..</span>10<span class="br0">)</span><span class="sy0">===</span><span class="nu0">10</span><span class="co1">;; => true</span><span class="br0">(</span>1<span class="sy0">..</span>10<span class="br0">)</span><span class="sy0">===</span><span class="nu0">11</span><span class="co1">;; => false</span> <span class="br0">(</span>1<span class="sy0">...</span>10<span class="br0">)</span><span class="sy0">===</span><span class="nu0">5</span><span class="co1">;; => true</span><span class="br0">(</span>1<span class="sy0">...</span>10<span class="br0">)</span><span class="sy0">===</span><span class="nu0">10</span><span class="co1">;; => false</span><span class="br0">(</span>1<span class="sy0">...</span>10<span class="br0">)</span><span class="sy0">===</span><span class="nu0">11</span><span class="co1">;; => false</span> <span class="co1">;; get the from value</span><span class="br0">(</span>1<span class="sy0">..</span>10<span class="br0">)</span>from<span class="sy0">==</span><span class="nu0">1</span><span class="co1">;; => true</span><span class="br0">(</span>1<span class="sy0">...</span>10<span class="br0">)</span>from<span class="sy0">==</span><span class="nu0">1</span><span class="co1">;; => true</span> <span class="co1">;; get the to value</span><span class="br0">(</span>1<span class="sy0">..</span>10<span class="br0">)</span>to<span class="sy0">==</span><span class="nu0">10</span><span class="co1">;; => true</span><span class="br0">(</span>1<span class="sy0">...</span>10<span class="br0">)</span>to<span class="sy0">==</span><span class="nu0">10</span><span class="co1">;; => true</span> <span class="co1">;; is this range exclusive?</span><span class="br0">(</span>1<span class="sy0">..</span>10<span class="br0">)</span>exclusive?<span class="co1">;; => false</span><span class="br0">(</span>1<span class="sy0">...</span>10<span class="br0">)</span>exclusive?<span class="co1">;; => true</span> <span class="co1">;; is this range inclusive?</span><span class="br0">(</span>1<span class="sy0">..</span>10<span class="br0">)</span>inclusive?<span class="co1">;; => true</span><span class="br0">(</span>1<span class="sy0">...</span>10<span class="br0">)</span>inclusive?<span class="co1">;; => false</span>
</pre></div>
</div>
<p>A Pair represents a combination of two values. They don't have to be of the
same kind. They can have any kind of relationship. Since Pairs are often used
to represent the elements of Dicts, it is very useful to refer to the first
value as the "key", and the second value as the "value".</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="co1">;; literal syntax for a pair</span><span class="st0">"foo"</span><span class="sy0">=></span><span class="st0">"bar"</span> <span class="co1">;; getting the first value</span><span class="br0">(</span><span class="st0">"foo"</span><span class="sy0">=></span><span class="st0">"bar"</span><span class="br0">)</span>first<span class="co1">;; => "foo"</span><span class="br0">(</span><span class="st0">"foo"</span><span class="sy0">=></span><span class="st0">"bar"</span><span class="br0">)</span>key<span class="co1">;; => "foo"</span> <span class="co1">;; getting the second value</span><span class="br0">(</span><span class="st0">"foo"</span><span class="sy0">=></span><span class="st0">"bar"</span><span class="br0">)</span>second<span class="co1">;; => "bar"</span><span class="br0">(</span><span class="st0">"foo"</span><span class="sy0">=></span><span class="st0">"bar"</span><span class="br0">)</span>value<span class="co1">;; => "bar"</span>
</pre></div>
</div>
<a name="Enumerable"></a>
<h2><span class="mw-headline">Enumerable</span></h2>
<p>One of the most important mixins in Ioke is Mixins Enumerable - the place
where most of the collection functionality is available. The contract for any
kind that wants to be Enumerable is that it should implement each in the manner
described earlier. If it does that it can mixin Enumerable and get access to
all the methods defined in it. I'm not going to show all the available methods,
but just a few useful examples here. Note that any method name that ends with
Fn takes a block instead of a raw message chain.</p>
<p>Almost all methods in Enumerable take variable amounts of arguments and do
different things depending on how many arguments are provided. The general rule
is that if there is only one argument, it should be a message chain, and if
there are two or more arguments the last one should be code, and the rest
should be names of arguments to use in that code.</p>
<p>Mapping a collection into a another collection can be done using map or
mapFn. These are aliased as collect and collectFn too.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
l<span class="sy0">=</span><span class="br0">[</span><span class="nu0">10</span>,<span class="nu0">20</span>,<span class="nu0">30</span>,<span class="nu0">40</span><span class="br0">]</span> <span class="co1">;; mapping into text</span>l map<span class="br0">(</span>asText<span class="br0">)</span><span class="co1">;; => ["10", "20", "30", "40"]</span>l map<span class="br0">(</span>n, n asText<span class="br0">)</span><span class="co1">;; => ["10", "20", "30", "40"]</span> <span class="co1">;; exponentiation</span>l map<span class="br0">(</span><span class="sy0">**</span><span class="nu0">2</span><span class="br0">)</span><span class="co1">;; => [100, 400, 900, 1600]</span>l map<span class="br0">(</span>n, n<span class="sy0">*</span>n<span class="br0">)</span><span class="co1">;; => [100, 400, 900, 1600]</span>
</pre></div>
</div>
<p>Filtering the contents of a collection can be done using select, which is
aliased as filter and findAll.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="co1">;; with no arguments, return all true things</span><span class="br0">[</span><span class="re6"><span class="re7">nil</span></span>,<span class="re6"><span class="re7">false</span></span>,<span class="nu0">13</span>,<span class="nu0">42</span><span class="br0">]</span>select<span class="co1">;; => [13, 42]</span> l<span class="sy0">=</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span>,<span class="nu0">5</span>,<span class="nu0">6</span><span class="br0">]</span> <span class="co1">;; all elements over 3</span>l select<span class="br0">(</span><span class="sy0">></span><span class="nu0">3</span><span class="br0">)</span><span class="co1">;; => [4, 5, 6]</span>l select<span class="br0">(</span>n, n<span class="sy0">></span><span class="nu0">3</span><span class="br0">)</span><span class="co1">;; => [4, 5, 6]</span>
</pre></div>
</div>
<p>A very common operation is to create one object based on the contents of a
collection. This operation has different names in different languages. In Ioke
it is called inject, but it is aliased as reduce and fold.</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
l<span class="sy0">=</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span>,<span class="nu0">5</span><span class="br0">]</span> <span class="co1">;; inject around a message chain</span>l inject<span class="br0">(</span><span class="sy0">+</span><span class="br0">)</span><span class="co1">;; => 15</span>l inject<span class="br0">(</span><span class="sy0">*</span><span class="br0">)</span><span class="co1">;; => 120</span> <span class="co1">;; with one arg</span>l inject<span class="br0">(</span>n,<span class="sy0">*</span>n<span class="br0">)</span><span class="co1">;; => 120</span>l inject<span class="br0">(</span>n,<span class="re5">+</span>n<span class="sy0">*</span><span class="nu0">2</span><span class="br0">)</span><span class="co1">;; => 29</span> <span class="co1">;; with two args</span>l inject<span class="br0">(</span>sum, n, sum<span class="sy0">*</span>n<span class="br0">)</span><span class="co1">;; => 120</span>l inject<span class="br0">(</span>sum, n, sum<span class="sy0">*</span><span class="nu0">2</span><span class="sy0">+</span>n<span class="sy0">*</span><span class="nu0">3</span><span class="br0">)</span><span class="co1">;; => 139</span> <span class="co1">;; with three args</span>l inject<span class="br0">(</span><span class="nu0">1</span>, sum, n, sum<span class="sy0">*</span>n<span class="br0">)</span><span class="co1">;; => 120</span>l inject<span class="br0">(</span><span class="nu0">10</span>, sum, n, sum<span class="sy0">*</span>n<span class="br0">)</span><span class="co1">;; => 1200</span>
</pre></div>
</div>
<a name="Regexps"></a>
<h2><span class="mw-headline">Regexps</span></h2>
<p>Regular expressions allow the matching of text against an abstract pattern.
Ioke uses the JRegex engine to implement regular expressions. This means Ioke
supports quite advanced expressions. Exactly what kind of regular expression
syntax is supported can be found at<a title="http://jregex.sf.net" class="external free" href="http://jregex.sf.net">http://jregex.sf.net</a>. This
section will describe how you interact with regular expressions from Ioke.</p>
<p>There are two kinds that are used when working with regular expression.
First, Regexp, which represents an actual pattern. The second is Regexp Match,
which contains information about a regular expression match. It is this match
that can be used to extract most information about where and how a complicated
expression matched.</p>
<p>The standard way of matching something is with the match method. This method
is aliased as =~, which is the idiomatic usage. It takes anything that can be
converted to a text and returns nil if it fails to match anything, or a Regexp
Match if it matches.</p>
<p>You can create a new Regexp from a text by using the Regexp from method. You
can quote all meta characters in a text by using the Regexp quote method.
Finally, if you just want to get all the text pieces that match for a regular
expression, you can use Regexp allMatches. It takes a text and returns a list
of all the text pieces where the Regexp matched.</p>
<p>You can also investigate a Regexp, by asking for its pattern (the pattern
method), its flags (the flag method), and the named groups it defines. The
names of the named groups can be inspected with the names method.</p>
<p>A Regexp Match is specific to one specific match. You will always get a new
one every time you try to match against something. A match has a target, which
is the original text the regular expression was matched against. So if I do #/
.. / =~ "abc fo bar", then the whole "abc fo bar" is the target. You get the
target from a match by using the target method. A match can also be asked for
the named groups the regular expression it was matched against support. This is
also done with the names method. Match also has two methods beforeMatch and
afterMatch, that returns the text before and after the match. The match method
returns the text comprising the actual match. The captures method will return a
list of all the captured groups in this match. The asList method returns the
same things as captures, except it also includes the full match text.</p>
<p>To figure out the indices where groups start or end, you can use the start
or end methods. These take an optional index that defaults to zero, where group
zero is the full match. They can also take a text or symbol that should be the
name of a named group. The offset method returns a pair of the beginning and
end offset of the group asked for. It works the same as start and end, with
regards to what argument it takes.</p>
<p>You can use the [] method on Match to extract the one or several pieces of
matches. If m is a match, then all of these are valid expressions: m[0].
m[1..3]. m[:foo]. m[-2], where the ranges return several groups, and the
negative index returns indexed from the end of the list of captures.</p>
<p>Finally, a Regexp Match implements pass. It does this in such a way that if
you use named groups, you can extract the value for that group by calling a
method named the same as that group name. An example of this:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
number<span class="sy0">=</span><span class="st0">"555-12345"</span>m<span class="sy0">=</span><span class="sy0">#/</span><span class="br0">(</span><span class="br0">{</span>areaCode<span class="br0">}</span>\d<span class="br0">{</span><span class="nu0">3</span><span class="br0">}</span><span class="br0">)</span><span class="sy0">-</span><span class="br0">(</span><span class="br0">{</span>localNumber<span class="br0">}</span>\d<span class="br0">{</span><span class="nu0">5</span><span class="br0">}</span><span class="br0">)</span><span class="sy0">/</span><span class="sy0">=~</span>number m areaCode println m localNumber println
</pre></div>
</div>
<a name="FileSystem"></a>
<h2><span class="mw-headline">FileSystem</span></h2>
<p>The FileSystem kind allows access to functionality in the file system. It is
the entry point to any manipulation of files and directories, and it can also
be used to get listings of existing files. The reference includes good
information about the existing methods in the FileSystem kind.</p>
<a name="Other_things"></a>
<h2><span class="mw-headline">Other things</span></h2>
<p>Ioke supports transforming an object into another object through the use of
the method become!. After an object becomes another object, those two objects
are indistinguishable from Ioke. This makes it really easy to do transparent
proxies, futures and other things like that. To use it, do something like
this:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
x<span class="sy0">=</span><span class="st0">"foo"</span>y<span class="sy0">=</span><span class="st0">"bar"</span> x become!<span class="br0">(</span>y<span class="br0">)</span>x same?<span class="br0">(</span>y<span class="br0">)</span><span class="co1">; => true</span>
</pre></div>
</div>
<p>In Ioke, objects can also be frozen. When an object is frozen it cannot be
modified in any way. Any try at modifying a frozen object will result in a
condition. This can be really helpful to track down problems in code, and make
assertions about what should be possible. You freeze an Ioke object by calling
freeze! on it. You can unfreeze it by calling thaw! on it. You can also check
if something is frozen by calling frozen? on it.</p>
<a name="Java_integration"></a>
<h1><span class="mw-headline">Java integration</span></h1>
<p>Java classes can be accessed by their full name, separated with colon
instead of dots:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
h<span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map</span>new
</pre></div>
</div>
<p>You can invoke methods as expected, although the rules for this are a bit
intricate. Specifically, the rules are that when calling methods that take any
kind of primitive arguments (most of the types in java.lang), these values will
be unwrapped. That means for a method taking an int, you can send in a wrapped
Java Integer, but you can also send in an Ioke Number Rational, and it will be
unwrapped correctly. You can send Text and Symbol to methods taking
Strings.</p>
<p>If you send in data to a method taking Object, you will not get the expected
result in all cases. Specifically, in these cases Ioke will unwrap wrapped Java
objects, but will not coerce the primitive types. So doing<code>h put("foo",
"bar")</code>will not coerce Text into java.util.String. However, if you have a
java.lang.String that has been modified from the Ioke side - adding cells for
example - then that String will be unwrapped before sent to the method
call.</p>
<p>The return value from a Java invocation will never be modified, except that
null will always be changed into nil, and Java booleans will be transformed
into Ioke booleans. This means that if you wrap a Java object, do some
modifications to it, and then let it go through a Java call, what you will get
back is probably not the wrapped version of that object. Of course, later on if
you try to call a method on the object, you will still use the wrapped
data.</p>
<p>The general rule for overloading is that overloaded methods will be sorted
from the most specific to the most general.</p>
<a name="Casts"></a>
<h2><span class="mw-headline">Casts</span></h2>
<p>Ioke Java integration supports casts in the same way as Java does. The main
difference is that the cast will be evaluated at runtime, not compile time. The
name to cast to will be unevaluated. Valid names are either Object, String, any
Java class name where dots are separated with colons, and a few special ones to
handle primitive values. These names are byte, int, integer, long, short, char,
character, float, double and boolean. Casting looks like this:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
x<span class="sy0">=</span><span class="re11">Foo</span>new x bar<span class="br0">(</span><span class="br0">(</span>short<span class="br0">)</span><span class="nu0">123</span>,<span class="br0">(</span>org<span class="re12"><span class="re13">:</span>something</span><span class="re12"><span class="re13">:</span><span class="re11">Interface</span><span class="br0">)</span>anObj<span class="br0">)</span></span>
</pre></div>
</div>
<a name="Class_methods"></a>
<h2><span class="mw-headline">Class methods</span></h2>
<p>Methods that belong to the Java class java.lang.Class are treated a bit
differently from the way other Java methods work. The reason for this is a bit
intricate to explain, but basically comes down to the dichotomy between the way
mimicking works in Ioke, and the way inheritance works in Java.</p>
<p>The easiest way to explain this might be to take a look at
java.util.ArrayList. In Java the hierarchy looks like this (somewhat
simplified)</p>
<pre>
instance >> ArrayList -> AbstractList -> AbstractCollection -> Object -> Serializable -> Cloneable -> Iterable -> Collection -> List -> RandomAccess
</pre>
<p>Note here that all capitalized words are names of classes. The Class itself
is not part of the inheritance structure, because Java has two namespaces. In
Ioke, the above hierarchy basically ends up looking like this:</p>
<pre>
instance -> ArrayList -> Class -> AbstractList -> Class -> AbstractCollection -> Class -> Object -> Class -> Serializable -> Class -> Cloneable -> Class -> Iterable -> Class -> Collection -> Class -> List -> Class -> RandomAccess -> Class
</pre>
<p>This is slightly simplified too, but the basic idea is that Class has to be
part of the same inheritance chain, because there only exists one namespace in
Ioke.</p>
<p>And that is why there is a need to have these methods named differently. So,
for example, say that you want to invoke the<code>toString</code>method
on<code>java:util:HashMap</code>. To do that, you do it like
this:<code>java:util:HashMap class:toString</code>. Note that you can actually
use the<code>class:</code>methods on instances of a class too. The result will
be the same as if the receiver had been that class instead of the instance.</p>
<a name="Fields"></a>
<h2><span class="mw-headline">Fields</span></h2>
<p>Accessing Java fields can be done by prepending the field name
with<code>field:</code>. The exact mechanics of this is that a Java field will
result in one or two Ioke methods. That means that the fields are not
represented as cells directly on the object. If the field is not final, a
setter will be also be generated for it. The setter follows the same rules as
invocations of regular methods, with regards to casting and choice of unpacking
of arguments.</p>
<p>There is a slight gotcha with this scheme. If you try to set a field that is
final, you will end up overwriting the accessor for that field - so it's
important to be really careful to not set final fields. In the long run, it
might be an idea to implement a setter that signals a condition when this
happens, but doing that gives the impression that you can set the value - since
the setter is there.</p>
<p>Ioke doesn't care if a field is private or protected. All fields are
accessible.</p>
<p>A small example - say that you have a java object in<code>foo</code>. This
Java object has two fields
called<code>oneThing</code>and<code>anotherThing</code>. Then you can work with
it like this:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
foo field<span class="re12"><span class="re13">:</span>oneThing</span>println foo field<span class="re12"><span class="re13">:</span>anotherThing</span><span class="sy0">=</span><span class="st0">"Bar"</span><span class="re9"><span class="re11">System</span></span>out println<span class="br0">(</span>foo field<span class="re12"><span class="re13">:</span>anotherThing<span class="br0">)</span></span>
</pre></div>
</div>
<p>Note that static fields work the same way - so you can access the Java
streams directly like this, for example:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
java<span class="re12"><span class="re13">:</span>lang</span><span class="re12"><span class="re13">:</span><span class="re9"><span class="re11">System</span></span></span>field<span class="re12"><span class="re13">:</span>out</span>println<span class="br0">(</span><span class="st0">"some text"</span><span class="br0">)</span>
</pre></div>
</div>
<a name="Importing_2"></a>
<h2><span class="mw-headline">Importing</span></h2>
<p>Ioke can import classes just as Java can. The way to do it looks a bit
different, though. Also, in Ioke an import only means that a local name will be
assigned to a class. It will not necessarily be globally visible, unless you
import in a global scope. It's also important to keep in mind that imports will
not happen if they might shadow or overwrite a name. If you want that, you will
have to do a manual assignment instead.</p>
<p>There are three ways of using the method<code>import</code>. The first one
is simply to import one class with the same name as it already has:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="co1">;; these are all equivalent</span><span class="re11">Hash</span>Map<span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map</span>import<span class="br0">(</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map<span class="br0">)</span></span>import java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map</span> <span class="co1">;; you can also import directly into a scope</span>foo<span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span>foo import<span class="br0">(</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Linked</span>HashMap<span class="br0">)</span></span>foo<span class="re11">Linked</span>HashMap new
</pre></div>
</div>
<p>Note that you can only give one class to import when using the above
way.</p>
<p>The second way to import is when you want to rename the imports. This allow
you to import several classes from different packages and also rename them at
the same time. This is done using keyword arguments to import:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="co1">;; these are all equivalent</span><span class="re11">Foo</span><span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map</span><span class="re11">Bar</span><span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>lang</span><span class="re12"><span class="re13">:</span><span class="re11">String</span></span>import<span class="br0">(</span><span class="re11">Foo</span><span class="re13">:</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map,</span><span class="re11">Bar</span><span class="re13">:</span>java<span class="re12"><span class="re13">:</span>lang</span><span class="re12"><span class="re13">:</span><span class="re11">String</span><span class="br0">)</span></span> <span class="co1">;; you can do the same in a new scope:</span>foo<span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span>foo import<span class="br0">(</span><span class="re11">Foo</span><span class="re13">:</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map,</span><span class="re11">Bar</span><span class="re13">:</span>java<span class="re12"><span class="re13">:</span>lang</span><span class="re12"><span class="re13">:</span><span class="re11">String</span><span class="br0">)</span></span>foo<span class="re11">Foo</span>new
</pre></div>
</div>
<p>The third way allow you to import several classes from the same package.
Note that to use this way, you need to provide at least one class name, in
addition to the package name:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="co1">;; these are the same as the following import</span><span class="re11">Hash</span>Map<span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map</span><span class="re11">Linked</span>List<span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Linked</span>List</span><span class="re11">Array</span>List<span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Array</span>List</span>import<span class="br0">(</span><span class="re12"><span class="re13">:</span>java</span><span class="re12"><span class="re13">:</span>util,</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map,</span><span class="re12"><span class="re13">:</span><span class="re11">Linked</span>List,</span><span class="re12"><span class="re13">:</span><span class="re11">Array</span>List<span class="br0">)</span></span> <span class="co1">;; and just as above, you can do it in a scope too</span>foo<span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span>foo import<span class="br0">(</span><span class="re12"><span class="re13">:</span>java</span><span class="re12"><span class="re13">:</span>util,</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map,</span><span class="re12"><span class="re13">:</span><span class="re11">Linked</span>List,</span><span class="re12"><span class="re13">:</span><span class="re11">Array</span>List<span class="br0">)</span></span>foo<span class="re11">Linked</span>List new
</pre></div>
</div>
<a name="Java_native_arrays"></a>
<h2><span class="mw-headline">Java native arrays</span></h2>
<p>In general, working with Java native arrays work exactly like you would
expect. The main difference is how you create them. For working with native
arrays of primitive types, you can use the primitive type names, which
are:<em>java:byte</em>,<em>java:short</em>,<em>java:char</em>,<em>java:int</em>,<em>java:long</em>,<em>java:float</em>and<em>java:double</em>.
When setting or getting values from these arrays, they will work exactly like
the coercions for regular Java methods.</p>
<p>You can either create a new empty array, or you can initialize it based on
an existing Ioke list:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
x<span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>short<span class="br0">[</span><span class="nu0">5</span><span class="br0">]</span></span>new x<span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>short<span class="br0">[</span><span class="br0">]</span></span>from<span class="br0">(</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span>,<span class="nu0">5</span><span class="br0">]</span><span class="br0">)</span>
</pre></div>
</div>
<p>The first version creates a JavaArrayProxyCreator with dimension one, and
length 5. The call to<em>new</em>will generate the actual array from this. You
can create multidimensional arrays by adding new pairs of square brackets.</p>
<p>In the second example, the call to square-brackets without an argument, will
return the type of that array class. We then call<em>from</em>on that type,
which will take an Ioke list, and generate an equivalent Java native array.</p>
<p>You can set and get values in Java arrays, just as you would with Ioke
lists:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
x<span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>char<span class="br0">[</span><span class="nu0">10</span><span class="br0">]</span></span>new x<span class="br0">[</span><span class="nu0">5</span><span class="br0">]</span><span class="sy0">=</span><span class="nu0">10</span>x<span class="br0">[</span><span class="nu0">6</span><span class="br0">]</span><span class="sy0">=</span><span class="nu0">13</span>x<span class="br0">[</span><span class="nu0">5</span><span class="br0">]</span>println
</pre></div>
</div>
<p>Finally, Java native arrays implement<em>each</em>, and mimic<em>Mixins
Enumerable</em>, which means that most things you expect to be able to do with
them will work correctly.</p>
<a name="Adding_jar-files_to_the_CLASSPATH"></a>
<h2><span class="mw-headline">Adding jar-files to the CLASSPATH</span></h2>
<p>If you dynamically want to add new jar-files to the CLASSPATH, you can do
that using<em>use</em>. There are two ways of doing it - you can either be
implicit or explicit, depending on if the module name is unique to a jar-file
or not:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="re6">use</span><span class="br0">(</span><span class="st0">"the_jar_file"</span><span class="br0">)</span><span class="re6">use</span><span class="br0">(</span><span class="st0">"the_jar_file.jar"</span><span class="br0">)</span><span class="re6">use</span>jar<span class="br0">(</span><span class="st0">"the_jar_file"</span><span class="br0">)</span>
</pre></div>
</div>
<a name="Implementing_and_extending_Java_types"></a>
<h2><span class="mw-headline">Implementing and extending Java types</span></h2>
<p><a title="Ioke E" href="/wiki/index.php/Ioke_E">Ioke E</a>supports
implementing Java interfaces from Ioke, and extending Java classes. This
machinery is all done with the method<code>integrate</code>.</p>
<p>The<code>integrate</code>method takes one or more Java types (it doesn't
matter if it's classes or interfaces, but it can only take at most one class),
and then returns a new class that is magic in that it will proxy back all calls
to the Ioke object, if it defines a method with the corresponding name. This
scheme works for most things, but there are some things to keep in mind too.
The most important one is that if you override a method that is overloaded in
Java-land, it is the responsibility of the Ioke method to handle all the
overloads.</p>
<p>Using it is very simple:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
<span class="re11">Ioke</span>Runnable<span class="sy0">=</span>integrate<span class="br0">(</span>java<span class="re12"><span class="re13">:</span>lang</span><span class="re12"><span class="re13">:</span><span class="re11">Runnable</span><span class="br0">)</span></span><span class="re11">Ioke</span>Runnable run<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span><span class="st0">"running!"</span>println<span class="br0">)</span>java<span class="re12"><span class="re13">:</span>lang</span><span class="re12"><span class="re13">:</span><span class="re11">Thread</span></span>new<span class="br0">(</span><span class="re11">Ioke</span>Runnable new<span class="br0">)</span>
</pre></div>
</div>
<p>Note that you have to use the<code>new</code>method to create new instances
of this object. In this way it behaves exactly like regular objects in Java
integration. And just in the same way, doing mimic will not copy the internal
Java object, just the outwards Ioke object.</p>
<p>Integration takes care of handling coercion of arguments and return values
into what Java expects.</p>
<a name="Coercing_lexical_blocks_to_interfaces"></a>
<h3><span class="mw-headline">Coercing lexical blocks to interfaces</span></h3>
<p>Ioke contains a mechanism that will automatically try to coerce anything
code-like into an interface or abstract class if no other matching overload can
be found for a method. So, that means you can do something like this, and it
will work as expected:</p>
<div style="text-align:left;" dir="ltr">
<div style="font-family:monospace;" class="ioke source-ioke">
<pre class="de1">
javax<span class="re12"><span class="re13">:</span>swing</span><span class="re12"><span class="re13">:</span>JButton</span>new addActionListener<span class="br0">(</span><span class="re8">fn</span><span class="br0">(</span>e,<span class="st0">"button pressed"</span>println<span class="br0">)</span><span class="br0">)</span>
</pre></div>
</div>
<a name="Libraries"></a>
<h1><span class="mw-headline">Libraries</span></h1>
<p>Ioke ships with several small libraries that are useful for different tasks.
The main ones are IIk, ISpec and DokGen, and these will be documented a bit
more in this chapter. All of them are considered a core part of Ioke since the
functionality they provide is tied to the distribution.</p>
<a name="IIk"></a>
<h2><span class="mw-headline">IIk</span></h2>
<dl><dd>
<div class="noprint"><em>Main article:<a title="Iik" href="/wiki/index.php/Iik">Iik</a></em></div>
</dd>
</dl><p>IIk is the interactive Ioke prompt, which will run if you give no arguments
to the ioke script. At the IIk prompt you can execute mostly all the same kind
of code that could execute inside of an Ioke script file. The main difference
is that this code will not be assigned to Ground, but instead will run in
another context that is specific for the purposes of IIk.</p>
<a name="ISpec"></a>
<h2><span class="mw-headline">ISpec</span></h2>
<dl><dd>
<div class="noprint"><em>Main article:<a title="ISpec" href="/wiki/index.php/ISpec">ISpec</a></em></div>
</dd>
</dl><p>ISpec is a minimal port of the Ruby RSpec framework for behavior-driven
development. It supports the bare minimum to allow testing of Ioke itself. The
current Ioke test suite is completely written in ISpec, and it seems to be a
capable environment.</p>
<a name="DokGen"></a>
<h2><span class="mw-headline">DokGen</span></h2>
<dl><dd>
<div class="noprint"><em>Main article:<a title="DokGen" href="/wiki/index.php/DokGen">DokGen</a></em></div>
</dd>
</dl><p>DokGen is the tool that is used to generate the reference documentation for
Ioke, and it generates output similar to<a title="http://rdoc.sourceforge.net/" class="external text" href="http://rdoc.sourceforge.net/">RDoc</a>. Its goal is
to be a general purpose tool for any Ioke application.</p>
<a name="What_is_missing"></a>
<h1><span class="mw-headline">What is missing</span></h1>
<p>Ioke E is not a finished Ioke version. I seriously doubt Ioke will ever be
complete. The core mechanics of the language I'm feeling fairly confident in,
but the core libraries are generally only partially implemented. They are much
more complete than for the Ioke S release, but there still exist large holes in
it.</p>
<p>Concurrency support is missing, and so is any kind of advanced IO. Package
management and other libraries like that is now starting to become necessary.
Finally, alternative implementations for other platforms is also in the
pipeline to happen sooner or later.</p>
<p>There is a<a title="Todo" href="/wiki/index.php/Todo">Todo</a>list where we
gather those things that should be done, sooner or later.</p>
<a name="Future_plans"></a>
<h1><span class="mw-headline">Future plans</span></h1>
<p>I have many plans for the future of Ioke. The next major version of Ioke
will be called<a title="Ioke P (not yet written)" class="new" href="/wiki/index.php?title=Ioke_P&action=edit&redlink=1">Ioke P</a>.
Exactly what it will contain we'll have to see, but feel free to add your
requests and ideas to<a title="Todo" href="/wiki/index.php/Todo">our TODO
list</a>.</p>
<div class="printfooter">Retrieved from "<a href="http://ioke.org/wiki/index.php/Guide">http://ioke.org/wiki/index.php/Guide</a>"</div>
<div class="visualClear"> </div>
</div>
</div>
</div>
<div id="column-one">
<div class="portlet" id="p-cactions">
<h5>Views</h5>
<div class="pBody">
<ul><li class="selected" id="ca-nstab-main"><a title="View the content page [c]" href="/wiki/index.php/Guide">Page</a></li>
<li class="new" id="ca-talk"><a title="Discussion about the content page [t]" href="/wiki/index.php?title=Talk:Guide&action=edit">Discussion</a></li>
<li id="ca-viewsource"><a title="This page is protected. You can view its source. [e]" href="/wiki/index.php?title=Guide&action=edit">View source</a></li>
<li id="ca-history"><a title="Past versions of this page. [h]" href="/wiki/index.php?title=Guide&action=history">History</a></li>
</ul></div>
</div>
<div id="p-personal" class="portlet">
<h5>Personal tools</h5>
<div class="pBody">
<ul><li id="pt-login"><a title="You are encouraged to log in, it is not mandatory however. [o]" href="/wiki/index.php?title=Special:UserLogin&returnto=Guide">Log in / create
account</a></li>
</ul></div>
</div>
<div id="p-logo" class="portlet"> </div>
<div id="p-" class="generated-sidebar portlet">
<div class="pBody">
<ul><li id="n-News"><a href="/wiki/index.php/News">News</a></li>
<li id="n-About-Ioke"><a href="http://ioke.org/index.html">About Ioke</a></li>
<li id="n-Guide"><a href="/wiki/index.php/Guide">Guide</a></li>
<li id="n-Download-x"><a href="http://ioke.org/download.html">Download</a></li>
<li id="n-Project-page"><a href="http://ioke.kenai.com">Project page</a></li>
<li id="n-Reference"><a href="http://ioke.org/dok/index.html">Reference</a></li>
<li id="n-Resources"><a href="/wiki/index.php/Resources">Resources</a></li>
<li id="n-Wiki"><a href="http://ioke.org/wiki">Wiki</a></li>
</ul></div>
</div>
<div id="p-Wiki" class="generated-sidebar portlet">
<h5>Wiki</h5>
<div class="pBody">
<ul><li id="n-mainpage-description"><a href="/wiki/index.php/Main_Page">Main
Page</a></li>
<li id="n-recentchanges"><a title="The list of recent changes in the wiki. [r]" href="/wiki/index.php/Special:RecentChanges">Recent changes</a></li>
</ul></div>
</div>
<div class="portlet" id="p-search">
<h5>Search</h5>
<div class="pBody" id="searchBody">
<div> </div>
</div>
</div>
<div id="p-tb" class="portlet">
<h5>Toolbox</h5>
<div class="pBody">
<ul><li id="t-whatlinkshere"><a title="List of all wiki pages that link here [j]" href="/wiki/index.php/Special:WhatLinksHere/Guide">What links here</a></li>
<li id="t-recentchangeslinked"><a title="Recent changes in pages linked from this page [k]" href="/wiki/index.php/Special:RecentChangesLinked/Guide">Related changes</a></li>
<li id="t-specialpages"><a title="List of all special pages [q]" href="/wiki/index.php/Special:SpecialPages">Special pages</a></li>
<li id="t-print"><a title="Printable version of this page [p]" href="/wiki/index.php?title=Guide&printable=yes">Printable version</a></li>
<li id="t-permalink"><a title="Permanent link to this version of the page" href="/wiki/index.php?title=Guide&oldid=230">Permanent link</a></li>
</ul></div>
</div>
</div>
<div class="visualClear"> </div>
<div id="footer">
<div id="f-poweredbyico"><a href="http://www.mediawiki.org/"><img alt="Powered by MediaWiki" src="/wiki/skins/common/images/poweredby_mediawiki_88x31.png" /></a></div>
<div id="f-copyrightico"><a href="http://www.gnu.org/copyleft/fdl.html"><img alt="GNU Free Documentation License 1.2" src="/wiki/skins/common/images/gnu-fdl.png" /></a></div>
<ul id="f-list"><li id="lastmod">This page was last modified on 5 April 2009, at 14:32.</li>
<li id="viewcount">This page has been accessed 6,503 times.</li>
<li id="copyright">Content is available under<a title="http://www.gnu.org/copyleft/fdl.html" class="external" href="http://www.gnu.org/copyleft/fdl.html">GNU Free Documentation License
1.2</a>.</li>
<li id="privacy"><a title="IokeWiki:Privacy policy" href="/wiki/index.php/IokeWiki:Privacy_policy">Privacy policy</a></li>
<li id="about"><a title="IokeWiki:About" href="/wiki/index.php/IokeWiki:About">About IokeWiki</a></li>
<li id="disclaimer"><a title="IokeWiki:General disclaimer" href="/wiki/index.php/IokeWiki:General_disclaimer">Disclaimers</a></li>
</ul></div>
</div>
<div>
<blockquote>このページは<a href="http://ioke.org/wiki/index.php/Guide">http://ioke.org/wiki/index.php/Guide</a>からの引用です</blockquote>
</div>
<div id="globalWrapper">
<div id="column-content">
<div id="content"><a name="top"></a>
<h1 class="firstHeading">Guide</h1>
<div id="bodyContent"><a name="Introduction"></a>
<h1><span class="mw-headline">Introduction</span></h1>
<h1><span class="mw-headline">はじめに</span></h1>
<p>Ioke is a general purpose language. It is a strongly typed, extremely
dynamic, prototype object oriented language. It is<a href="http://en.wikipedia.org/wiki/Homoiconicity" class="external text" title="http://en.wikipedia.org/wiki/Homoiconicity">homoiconic</a>and its closest
ancestors are<a href="http://iolanguage.com" class="external text" title="http://iolanguage.com">Io</a>,<a href="http://www.smalltalk.org" class="external text" title="http://www.smalltalk.org">Smalltalk</a>,<a href="http://www.ruby-lang.org" class="external text" title="http://www.ruby-lang.org">Ruby</a>and<a href="http://en.wikipedia.org/wiki/Lisp_programming_language" class="external text" title="http://en.wikipedia.org/wiki/Lisp_programming_language">Lisp</a>- but
it's quite a distance from all of them. It looks a lot like Io, to a limit.</p>
<p>
Iokeは汎用言語です。極動的な強い型付け、プロトタイプベースのオブジェクト指向言語です。homoiconic(http://en.wikipedia.org/wiki/Homoiconicity)であり、Io、Smalltalk、Ruby、Lispに近い系統の言語です。が、それらとは大きな違いもあります。見た目はほとんどIoです。<font size="1">to
a limit?</font></p>
<p>Ioke is a<em>folding</em>language. This means it folds in on itself. You can
create new abstractions covering any of the existing abstractions in the
language. You can abstract over these, over and over again, until you have a
language that lets you express what you want to express in a succinct and
readable way. Ioke allows you to fold your code.</p>
<p>Iokeは織り込み<font size="1">(いい言葉はない?)</font>言語です。自分自身に織り込むということです。言語が用意する既存の抽象階層を拡張する新たな抽象階層を、自由に作成できます。その抽象階層をさらに拡張することも可能で、必要に応じた簡潔で読みやすい言語を作ることもできます。Iokeにあなたのコードを織り込むことができます。</p>
<p>Ioke is targeted at the Java Virtual Machine and is tightly integrated with
the platform. Why the JVM? It's available everywhere, it gives several
important features such as world class garbage collectors, capable thread
schedulers and an amazing JIT compiler. All of these are things that serve Ioke
well, without requiring direct development resources from the Ioke team. Access
to the Java platform also means access to all existing libraries and
functionality, with all that entails. The JVM is just a very pragmatic
choice.</p>
<p>IokeはJVM(Java Virtual
Machine)をターゲットとして、JVMプラットホーム上で開発されています。なぜJVMか?どこでも実行可能で、ガベージコレクタや優秀なスレッドスケジューラ、素晴らしいJITコンパイラなどの重要な機能をサポートしているからです。それらの機能はすべてIokeにも必要な機能を、Ioke開発チームが直接作る必要がありません。Javaプラットホームへのアクセスできるということは、必然的に、既存のライブラリや機能性へアクセスできるということになります。JVMは実に実用的な選択です。</p>
<p>You're probably reading this guide at<a href="http://ioke.org/guide.html" class="external text" title="http://ioke.org/guide.html">ioke.org</a>. That is
the official home of the project, although some of the project functionality is
hosted at<a href="http://ioke.kenai.com" class="external text" title="http://ioke.kenai.com">Kenai</a>, where such things as mailing lists and a bug
tracker is available. The canonical source repository for Ioke is on<a href="http://github.org/olabini/ioke/tree/master" class="external text" title="http://github.org/olabini/ioke/tree/master">GitHub</a>.</p>
<p>
今あなたは、ioke.orgにあるガイドを読んでいると思います。ioke.orgはこのプロジェクトの公式サイトです。また、メーリングリストやバグ管理などのプロジェクト機能の一部はKenaiにあります。Iokeの正式なソースレポジトリはGitHubにあります。</p>
<p>The current version of Ioke is called<a href="/wiki/index.php/Ioke_E" title="Ioke E">Ioke E</a>. The naming of Ioke will change regularly with major
revisions. There are two different versions in play here.<a href="/wiki/index.php/Ioke_E" title="Ioke E">Ioke E</a>is the name and version of
the language and core libraries. The initial implementation for<a href="/wiki/index.php/Ioke_E" title="Ioke E">Ioke E</a>is called<tt>ikj 0.3.0</tt>,
and the version numbers are not interdependent. The next major version of Ioke
will be called<a href="/wiki/index.php?title=Ioke_P&action=edit&redlink=1" class="new" title="Ioke P (not yet written)">Ioke P</a>, and you can find information about it in
the chapter on<a href="#Future_plans" title="">future plans</a>.</p>
<p>Iokeの現行バージョンはIoke Eです。Iokeの名前はメジャーバージョンで変わるよう付けています。2つのバージョンがあり、Ioke
Eは言語仕様とコアライブラリのバージョンを指しています。Ioke Eの最初の実装はikj
0.3.0で、バージョン番号は相互依存ではありません。次のメジャーバージョンはIoke Pで、情報はfuture plansの章にあります。</p>
<p>This programming guide -- together with the reference for your current
version -- should be the complete document needed to understand<a href="/wiki/index.php/Ioke_E" title="Ioke E">Ioke E</a>, how to program in it, how
to understand the names and concepts used, and also give an initial inkling on
what I think is good taste.</p>
<p>このプログラミングガイドは(あなたのカレントバージョンのリファレンスもそうですが)、Ioke
Eを理解するためのドキュメントであり、どのようにプログラムを作成するかとか、どのように用語やコンセプトを理解するかとか、私がいいと思うような初期のほのめかしも書かれています。</p>
<p>Note that I will use many names that aren't necessarily the same as the ones
traditional programming languages use. These names will be made clear sooner or
later in this document, but it might help some to jump forward to<a href="#Objects" title="">Objects</a>, skim that bit, and then start over once words
lik e<em>Origin</em>,<em>cell</em>and<em>mimic</em>make sense.</p>
<p>
ここで使う用語は、既存のプログラム言語で使われる用語と意味が同じとは限りません。用語についてはドキュメント内で時機に明確になりますが、Objects章、とくにOrigin、cell、mimicについて、さらっと読んでおいてもいいかも知れません。</p>
<a name="Vision"></a>
<h2><span class="mw-headline">Vision</span></h2>
<h2><span class="mw-headline">構想</span></h2>
<p>The evolution of programming languages is a steady progression of finding
new ways to express abstractions naturally - in a way that doesn't stray too
far away from the smaller details. A programming language has to make it
possible to abstract away common things, while making it easy to customize
these abstractions in very detailed ways. A programming language should be able
to do this well without sacrificing readability and understandability. This
tension lies at the core of programming.</p>
<p>
プログラミング言語の進化は、抽象階層を自然に記述する新しい方法を見つけるための着実な前進です。より詳細な点からそんなに遠く外れることはなく?。プログラミング言語は共通事項の抽象化を可能にし、細部に渡る抽象階層を簡単にカスタマイズ可能にしました。プログラミング言語に読みやすさや理解しやすさも必要です。この葛藤こそが、プログラミングの本質です。</p>
<p>How do you create a language that makes it easy to express powerful concepts
in a succinct way, while still making it easy to maintain and work with after
the fact, without turning it into a new compression mode? How do you make it
easy for a programmer to express high level abstractions that are abstractions
of abstractions of abstractions?</p>
<p>
では、言語をどのように作れば、簡潔な方法でパワフルかつ簡単に概念を記述できるようになるのでしょうか?同時に、事後の保守を簡単に出来るようにするには?新しい圧縮モード(?)を不要とするには?言語をどのように作れば、プログラマが抽象階層の抽象階層の抽象階層といった、高レベルの抽象階層を簡単に書くことができるのでしょうか?</p>
<p>There are many open problems in programming language design. Concurrency is
one of them, performance another. These are two areas Ioke does not address.
Instead, Ioke is a remodeling of the core concepts and ideas embodied in other
programming languages.</p>
<p>
プログラミング言語設計には、多くの未解決問題があります。一つは並列処理で、もう一つはパフォーマンスです。これら2つの問題領域には、Iokeは踏み込んでいません。その代わりに、Iokeはコア構造の再構築を可能にし、他のプログラミング言語のアイデアを盛り込めるようにしています。</p>
<p>Are Lisp and Smalltalk still the most powerful languages around, or are
there ways of providing more expressiveness without sacrificing
understandability? Is there a way to combine all the lessons learned from
languages like Ruby and Python, and patch them back into a Lisp and Smalltalk
core? Is it possible to do this while taking some of the benefits of Io? Can a
language be both small, regular, homoiconic, reflective and easy to understand?
I hope that Ioke is just that.</p>
<p>Simplicity doesn't mean lack of power. Small, simple, orthogonal
functionality can be more powerful than larger, complicated abstractions that
don't fit together.</p>
<p>Io explicitly states that the goal of the language is to refocus attention
on expressiveness, and with Ioke I want to take that philosophy one step
further.</p>
<p>It's important to realize that an experiment like this doesn't necessarily
have to mean the language can't be used for real projects. By wedding Ioke to
the Java Virtual Machine, I make it easy to get access to good libraries and
existing implementations on most platforms. In that way, Ioke can be used to
create real systems, even though the ecosystem will initially be very small.
And I think that this is necessary. How can you know if a language really is
worthwhile or not, if you can't use it as a general purpose programming
language? The Java platform makes this possible.</p>
<a name="Getting_started"></a>
<h2><span class="mw-headline">Getting started</span></h2>
<h2><span class="mw-headline">はじめよう</span></h2>
<p>Ioke is very easy to get started with. The first step is to download a
package. Which one you choose depends on what platform you're on, and whether
you want to build Ioke yourself, or just start using it. This guide will only
cover using a prebuilt version. Go to the<a href="http://ioke.org/download.html" class="external text" title="http://ioke.org/download.html">download page</a>, and grab one of the
distributions. At the time of writing the full version of Ioke is Ioke E ikj
0.3.0. Choose the latest download in the 0.3-series for this document to
apply.</p>
<p>Once you have downloaded the distribution, you need to unpack it somewhere,
and finally add the<tt>bin</tt>directory to your<tt>PATH</tt>environment
variable. There is also a<tt>jar</tt>download that can be run directly. If you
choose this option you don't get the benefits of having a home for Ioke, which
in some cases might be inconvenient. Ioke can be run directly from the jar
file, though.</p>
<a name="Building_Ioke"></a>
<h3><span class="mw-headline">Building Ioke</span></h3>
<h3><span class="mw-headline">Iokeのビルド</span></h3>
<p>If you'd like to build Ioke from source, make sure you have a recent version
of the<a href="http://java.sun.com/javase/downloads/index.jsp" class="external text" title="http://java.sun.com/javase/downloads/index.jsp">Java
Development Kit</a>installed (1.5.0 or higher, preferrably 1.6.0) and<a href="http://ant.apache.org" class="external text" title="http://ant.apache.org">Apache Ant</a>. You must have the<tt>ant</tt>script
reachable from your<tt>PATH</tt>variable. Then, simply check out the source
code from the<a href="http://github.org/olabini/ioke/tree/master" class="external text" title="http://github.org/olabini/ioke/tree/master">main
repository</a>, and build it using<tt>ant</tt>. That should run all the
compilation steps and tests, and allow the<tt>bin/ioke</tt>script to run. Just
proceed as if you had unpacked the distribution, adding
the<tt>bin</tt>directory to the<tt>PATH</tt>.</p>
<a name="Running_scripts"></a>
<h3><span class="mw-headline">Running scripts</span></h3>
<h3><span class="mw-headline">スクリプトを実行</span></h3>
<p>To run an Ioke script, you can generally just use
the<tt>ioke</tt>command:</p>
<pre>
$ ioke helloWorld.ik Hello world
</pre>
<p>You can also execute snippets of code on the command line using
the<tt>-e</tt>argument to the<tt>ioke</tt>command. You can have several of
these in the same line too:</p>
<pre>
$ ioke -e'"Hello world" println' -e'"Goodbye world" println' Hello world Goodbye world
</pre>
<p>When using<tt>-e</tt>, be careful about what quoting style you use, since
the shell sometimes can munge up your commands if you don't surround them
correctly.</p>
<p>The<tt>ioke</tt>command has several helpful command line options, which can
change what happens during execution. These are:</p>
<dl><dt>-Cdirectory</dt>
<dd>Switch to directory before executing any files and command line scripts.
This will make the directory the initial current working directory for Ioke
during the execution of the JVM.</dd>
<dt>-d</dt>
<dd>Enable debug output.</dd>
<dt>-e script</dt>
<dd>Execute script, as describe above. May occur more than once on a command
line.</dd>
<dt>-h<br /></dt>
</dl><p>--help</p>
<dl><dd>Display help information, including descriptions of these command line
options.</dd>
<dt>-Idirectory</dt>
<dd>Add directory to the load path of Ioke. May occur more than once on a
command line.</dd>
<dt>-JjvmOptions</dt>
<dd>Pass on options to the JVM. This can be used to change any runtime
parameters that your JVM takes. May occur more than once. The options are
provided directly after the -J, so if you want to change the maximum amount of
memory used, you can do that writing -J-Xmx128M.</dd>
<dt>--copyright</dt>
<dd>Print copyright information and exit.</dd>
<dt>--version</dt>
<dd>Print version information and exit</dd>
<dt>--server</dt>
<dd>Run the JVM in server Hotspot mode</dd>
<dt>--client</dt>
<dd>Run the JVM in client Hotspot mode (the default)</dd>
<dt>--</dt>
<dd>Mark the end of options to the<tt>ioke</tt>script, anything after this are
options to be sent to the code running.</dd>
</dl><p>If you provide the name of a script file on the command line, it should come
after all the arguments to the<tt>ioke</tt>script. Everything after the script
will be added as data to the<code>System programArguments</code>cell. You can
use both one-line scripts with<tt>-e</tt>and specify a script file. If so, the
script file will be run after the one-line scripts.</p>
<a name="Interactive_mode"></a>
<h3><span class="mw-headline">Interactive mode</span></h3>
<h3><span class="mw-headline">インタラクティブモード</span></h3>
<p>If no code to execute has been specified to the<tt>ioke</tt>script,<a href="/wiki/index.php/IIk" class="mw-redirect" title="IIk">IIk - Interactive
Ioke</a>- will start. This is a REPL that allows the execution of arbitrary
code in a shell that immediately displays the result. The main difference
between running Ioke from a file and interactively is that the interactive
prompt will show a notice of the result of the last operation after each
execution. IIk will also invoke a debugger when a<a href="/wiki/index.php?title=Conditions&action=edit&redlink=1" class="new" title="Conditions (not yet written)">condition</a>is encountered. This debugger
gives you the possibility to inspect what happened more closely. The final
difference with IIk is that it does not execute code directly in Ground - which
the top level inside an Ioke script will do. This difference is crucial, when
considering namespacing issues.</p>
<p>IIk will try to use Readline through JLine if your platform supports it.</p>
<p>IIk will be more closely described later, but just to give you a glimpse,
this is how a small session could look like:</p>
<pre>
iik> "hello world" println hello world +> nil iik> 10 * 20 +> 200 iik> 3/2 +> 3/2 iik> 3/2 + 3/2 +> 3 iik> 3/2 * 3 +> 9/2 iik> foo = "hello" +> "hello" iik> foo +> "hello" iik> exit Bye.
</pre>
<p>When you see the prompt "iik>", you know that IIk is waiting for input.
The result of a computation is shown after the "+>" sigil. You can exit from
IIk by calling either "exit" or "quit". There is also a restart named "quit"
that can be invoked to quit IIk.</p>
<a name="Syntax"></a>
<h1><span class="mw-headline">Syntax</span></h1>
<h1><span class="mw-headline">構文</span></h1>
<p>Ioke has no keywords or statements. Everything is an expression composed of
a chain of messages. A piece of code is represented as a chain of messages that
links to the next message. The result of one message will be the receiver of
the next message, until a "." message is received. The "." message is a
terminator that throws away the current receiver. A newline will serve as a "."
message in the circumstances where it feels natural.</p>
<p>An informal BNF description of Ioke looks like this:</p>
<pre>
program ::= messageChain? messageChain ::= expression+ expression ::= message | brackets | literal | terminator literal ::= Text | Regexp | Number | Decimal | Unit message ::= Identifier ( "(" commated? ")" )? commated ::= messageChain ( "," messageChain )* brackets ::= ( "[" commated? "]" ) | ( "{" commated? "}" ) terminator ::= "." | "\n" comment ::= ";" .* "\n"
</pre>
<p>What isn't visible here is that all whitespace -- except for newlines --
will work only as separators of messages, and is otherwise ignored. That means
that message sending does not use the dot, as in most other languages. A phrase
such as<code>foo().bar(quux(42)).baaz()</code>would be expressed as<code>foo()
bar(quux(42)) baaz()</code>, or more succinctly<code>foo bar(quux(42))
baaz</code>in Ioke.</p>
<p>All the types of literals are actually turned into a message to create that
literal, so the canonical form of the message chain contains no literals, just
a message to create that literal. Any message can have zero or more arguments
given to it. Arguments are separated with comma. If there are no arguments to a
message, the parenthesis can be left off, but they need to be there if there
are arguments. Mostly any combination of characters can be used as an
Identifier, with some exceptions.</p>
<p>There used to be a parsing element called operators, but these have now been
included into identifiers. They are not parsed differently at all, but the
operator shuffling step will handle them differently. Specifically, operators
can be used in infix, including having different precedence rules. Assignment
is a specific form of operator which gets its own kind of shuffling. These are
both described below.</p>
<p>An identifier in Ioke can be one of several things. Ioke takes the rules for
Java identifiers, and adds some more to them. All Unicode letters and digits
can be part of an identifier, except for the first entry. Underscores are
allowed, just like in Java. Ioke also allows colons as an identifier.
Exclamation mark and question mark is allowed anywhere in the identifier except
for in the beginning. Identifiers can be broadly classified into identifiers
and operators, where operators can be any combination of several sigils. There
are also some special operators that have restrictions. These are: Opening and
close brackets are not allowed, except together with its counterpart, so [ is
not a valid identifier, while [] is. So is {}. () is not valid either. Two or
more dots is a valid identifier. A hash sign can be followed by any operator
char, but isn't parsed as an identifier by itself. Slash is not an operator
char, but can be used as it except in combinations that look like regular
expressions. The operator chars are: +, -, *, %, <, >, !, ?, ~, &, |,
^, $, =, @, ', ` and :. These can be combined together in any order, and any
number, except for the caveats noted before. That means the available operator
space is infinite, and very wide. Combinations of letters and operator
characters are generally not allowed, except for the exceptions with :, !
and ?. This is to make it possible to have infix operations without spaces in
some situations.</p>
<p>The two forms of brackets will get turned into a canonical form. Surrounding
comma-separated message chains with square brackets is the same as calling the
method [], giving it those message chains as argument. So [foo, bar, quux] is
exactly the same as [](foo, bar, quux). The same is true for curly
brackets.</p>
<p>Comments start with semicolon and end at the first newline. They can be used
mostly anywhere, except inside of literal texts. The hash sign followed by an
exclamation mark is also a comment, to allow the shebang line in Unix
scripts.</p>
<p>How and when the actual evaluation of messages happen depend on what kind
the message type is. If it's inactive, the value reflecting that cell will be
returned. If it's active, the cell will be activated and the result of that
activation returned. How the activation depends on what kind of code the cell
contains. The various kinds of code is described more closely in the chapter
about<a href="/wiki/index.php/Guide:Code" title="Guide:Code">code</a>.</p>
<a name="Literal_values"></a>
<h2><span class="mw-headline">Literal values</span></h2>
<h2><span class="mw-headline">リテラル値</span></h2>
<p>Ioke currently contains four different kinds of literals. There is a fifth
quasi literal, that isn't exactly parsed as a literal, but will be evaluated
differently based on its name. These literals are texts, regular expressions,
integers and decimal numbers. Symbols are actually parsed as regular
identifiers, but they are handled a bit differently during evaluation.</p>
<a name="Text"></a>
<h3><span class="mw-headline">Text</span></h3>
<h3><span class="mw-headline">テキスト</span></h3>
<p>A literal text in Ioke is what is generally called strings in most
languages. As in most languages, text is written inside of double quotes. Any
characters are valid inside of those double quotes. That includes newlines - so
you can write a literal text that extends to several lines. There is an
alternate syntax for text when the value contains a lot of double quotes. As in
most other languages, several escapes are valid inside of a text. Escapes are
preceded by the backslash, and insert the character corresponding to the escape
values. These escapes are:</p>
<dl><dt>\b</dt>
<dd>Inserts the backspace character, that is represented in ASCII by the
decimal value 8.</dd>
<dt>\e</dt>
<dd>Inserts the character that is represented in ASCII by the decimal value 27.
This value is used for sending escape values to the TTYs in some operating
systems.</dd>
<dt>\t</dt>
<dd>Inserts the TAB character - ASCII decimal 9.</dd>
<dt>\n</dt>
<dd>Inserts the newline character - ASCII decimal 10.</dd>
<dt>\f</dt>
<dd>Inserts the form feed character - ASCII decimal 12.</dd>
<dt>\r</dt>
<dd>Inserts the carriage return character - ASCII decimal 13.</dd>
<dt>\"</dt>
<dd>Inserts the double quote character - ASCII decimal 34.</dd>
<dt>\\</dt>
<dd>Inserts the backslash character - ASCII decimal 92.</dd>
<dt>\[newline]</dt>
<dd>Inserts nothing at all. Used to escape necessary newlines, without having
them show up in the output text.</dd>
<dt>\#</dt>
<dd>Inserts a literal hash character - ASCII decimal 35.</dd>
<dt>\uABCD</dt>
<dd>Inserts the Unicode codepoint corresponding to the hexadecimal value of the
four characters following the "u". All four hexadecimal characters need to be
specified.</dd>
<dt>\7, \12, \316</dt>
<dd>Inserts the Unicode codepoint corresponding to the octal value of the one,
two or three octal characters. The maximum value allowed is \377, and the
minimum is obviously \0.</dd>
</dl><p>Ioke also supports an alternative text syntax that can be used when the text
in question contains many scare quotes. The alternative syntax starts with #[
and ends with ]. A right bracket will have to be escaped, but scare quotes
doesn't have to be.</p>
<p>The parsing of text will generate a message with name "internal:createText".
This message will get one argument that is the raw Java String corresponding to
the text.</p>
<p>Ioke allows automatic interpolation of arbitrary values in the same manner
as Ruby. It uses the same syntax for this, which is the #{} syntax inside a
text. These can be nested in any way. The elements will be parsed and sent as
arguments to the message with name "internal:concatenateText". So an Ioke text
such as "foo bar#{flux} will #{1+2}" will generate the message
internal:concatenateText("foo bar", flux, " will ", 1+(2), ""). As you can see,
there is a small amount of waste in the way this is generated -- but the simple
model makes it easy to understand. It's not guaranteed that this will remain
the same, although the message will definitely remain.</p>
<p>Some examples:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="st0">"foo"</span><span class="st0">"flax<span class="es0">\</span>mux"</span><span class="st0">"one two #{three}<span class="es0">\b</span>four"</span><span class="sy0">#</span><span class="br0">[</span>you don't really<span class="st0">"#{1+2+3}"</span>believe that?<span class="br0">]</span>
</pre></div>
</div>
<a name="Regular_expressions"></a>
<h3><span class="mw-headline">Regular expressions</span></h3>
<h3><span class="mw-headline">正規表現</span></h3>
<p>Ioke has very capable regular expressions. Exactly what you can do with them
can be found further down in this guide. The literal syntax allows regular
expressions to be embedded in code directly. The syntax for this starts with a
#/ and ends with another /. The last slash can optionally be followed by some
flags that change the behavior of the expression. Regular expressions can also
use an alternative syntax that starts with #r[ and ends with ]. Just as with
Text, regular expressions can contain interpolation. This interpolation will be
transformed into regular expressions and then combined with the outer regular
expression. A few examples might be in order here:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="sy0">#//</span><span class="sy0">#</span>r<span class="br0">[</span><span class="br0">]</span><span class="sy0">#/</span>foo<span class="sy0">/</span><span class="sy0">#</span>r<span class="br0">[</span>foo<span class="br0">]</span><span class="sy0">#/</span>fo<span class="sy0">+/</span>x<span class="sy0">#</span>r<span class="br0">[</span>fo<span class="sy0">+</span><span class="br0">]</span>x<span class="sy0">#/</span>bla<span class="sy0">#</span><span class="br0">{</span><span class="st0">"foo"</span><span class="br0">}</span>bar<span class="sy0">/</span><span class="sy0">#</span>r<span class="br0">[</span>bla<span class="sy0">#</span><span class="br0">{</span><span class="st0">"foo"</span><span class="br0">}</span>bar<span class="br0">]</span>
</pre></div>
</div>
<p>The first example is an empty regular expression. The second is an
expression matching the word "foo". The third expression matches an "f"
followed with one or more "o". It also allows extended regular expression
syntax, due to the x flag. The flags supported in Ioke are x, i, u, m and s.
The meaning of these match the meaning of corresponding Ruby flags. Regular
expressions allow most of the same escapes as Ioke text. Specifically, these
escapes are supported: b, t, n, f, r, /, \ and newline. Unicode and octal
escapes also work. The fourth example shows the insertion of a literal text
inside of a regular expression.</p>
<p>Ioke regular expressions will be transformed into a call to
internal:createRegexp. This message expects two Java strings, one with the
actual pattern, and one with the flags.</p>
<a name="Integers"></a>
<h3><span class="mw-headline">Integers</span></h3>
<h3><span class="mw-headline">整数値</span></h3>
<p>Ioke supports arbitrarily sized numbers. It also contains a numerical tower
that can be more closely explored in the reference documentation. The numerical
tower is based in Number. Number Real mimics Number. Number Rational mimics
Number Real, and so does Number Decimal. Finally, Number Integer and Number
Ratio both mimics Number Rational. The interesting parts of this tower is
Number Integer, which corresponds to integers, Number Ratio, which is any ratio
between two integers, and Number Decimal, which corresponds to decimal numbers.
These are arbitrarily sized and exact. There are no floats or doubles in Ioke.
There is also a potential place for Number Complex at the same layer as Number
Real, although complex numbers are not currently implemented. There are also
plans for implementing a unit system further down the line.</p>
<p>Literal integers can be written using either decimal or hexadecimal
notation. Hexadecimal notation begins with 0x or 0X and are then followed by
one or more hexadecimal letters. They can be either upper or lower case. A
decimal literal number is written using one or more decimal letters, but
nothing else.</p>
<p>There is no literal to create ratios - these can only be created by division
of integers. Negative numbers have no literal syntax, but preceding a number
with a minus sign will call the message - on the number and generate the
negative value.</p>
<p>A literal integer will be transformed into a call to internal:createNumber,
which takes one native Java String from which to create the number.</p>
<p>Some examples:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="nu0">1234444444444444444444444444444444444444235234534534</span><span class="nu0">0</span><span class="re1">0xFFFFF</span>
</pre></div>
</div>
<a name="Decimals"></a>
<h3><span class="mw-headline">Decimals</span></h3>
<h3><span class="mw-headline">数値</span></h3>
<p>Literal decimal values can be written either using exponential notation, or
using a decimal dot. A decimal dot notation can be combined with exponential
notation. Exponential notation starts with a number or a decimal number,
followed by lower or upper case E, followed by an optional sign, and then
followed by one or more decimal letters.</p>
<p>A literal decimal will be transformed into a call to internal:createDecimal,
which takes one native Java String from which to create the decimal.</p>
<p>Some examples:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="nu0">0.0</span><span class="re2"><span class="re3">1E</span>6</span><span class="re3">1E</span><span class="re0">-</span><span class="nu0">32</span><span class="re2"><span class="nu0">23.444</span><span class="re3">5e</span>10</span>
</pre></div>
</div>
<a name="Symbols"></a>
<h3><span class="mw-headline">Symbols</span></h3>
<h3><span class="mw-headline">シンボル</span></h3>
<p>Symbols aren't exactly syntax, but they aren't exactly messages either. Or
rather, they are messages that will evaluate to the symbol that represent
themselves. Symbol is a kind in Ioke. There are two kinds of symbols - the
first one is simple symbols that can be parsed as is. The second is symbols
that can't be parsed as is. Symbols are preceded by a colon and then directly
followed by the symbol text. If it can't be parsed correctly, the value should
be surrounded by quotes, and this will be turned into a call to the method :,
which takes the text as argument. That means that you can actually get dynamic
symbols by calling the : method.</p>
<p>Some examples:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="re12"><span class="re13">:</span>foo</span><span class="re12"><span class="re13">:</span>flaxBarFoo</span><span class="re13">:</span><span class="st0">""</span><span class="re13">:</span><span class="st0">"mux mex mox<span class="es0">\n</span>::::::::"</span>
</pre></div>
</div>
<a name="Operator_shuffling"></a>
<h2><span class="mw-headline">Operator shuffling</span></h2>
<h2><span class="mw-headline">演算子</span>のようなもの</h2>
<p>One exception to the way message handling works in Ioke is operators. All
the so called operators in this section is possible to call directly in message
passing position too -- but to make it possible to use them in a more natural
way, the parsing step will handle them a bit differently, and then do a
shuffling step that actually takes operator precedence into account. So all the
common operators will generally work as you expect them to -- although I
recommend adding parenthesis when something is possibly unclear.</p>
<p>Ioke has a slightly larger amount of operators than most other languages.
Most of these are currently unused, but they are certainly available for use
for any purpose the programmer wants to use it for. Many adherents of other
languages (Java, I'm looking at you) claim that operator overloading is evil. I
don't believe that is true, seeing as how it works so well in Ruby, so Ioke
instead allow you quite large freedom with regards to operators.</p>
<p>The precedence rules for regular operators can be found in the cell 'Message
OperatorTable operators', which is a regular Dict that can be updated with new
values. The new values will obviously not take effect until the current code
has run, and a new parse is started.</p>
<p>Note that the below is only the operators that have defined precedence
rules. As noted in the section on syntax, you can use any operator you want
really. It is easy to add new precedences to the table, either temporarily or
permanently.</p>
<p>At the time of writing, the available operators - in order of precedence -
are these:</p>
<ul><li> !</li>
<li> ?</li>
<li>$</li>
<li>~</li>
<li>#</li>
<li>**</li>
<li>*</li>
<li>/</li>
<li> %</li>
<li>+</li>
<li>-</li>
<li><<</li>
<li>>></li>
<li><=></li>
<li>></li>
<li><</li>
<li><=</li>
<li>>=</li>
<li><></li>
<li><>></li>
<li>==</li>
<li> !=</li>
<li>===</li>
<li>=~</li>
<li> !~</li>
<li>&</li>
<li>^</li>
<li>|</li>
<li>&&</li>
<li> ?&</li>
<li>||</li>
<li> ?|</li>
<li>..</li>
<li>...</li>
<li>=></li>
<li><-></li>
<li>-></li>
<li>+></li>
<li> !></li>
<li>&></li>
<li> %></li>
<li>#></li>
<li>@></li>
<li>/></li>
<li>*></li>
<li> ?></li>
<li>|></li>
<li>^></li>
<li>~></li>
<li>->></li>
<li>+>></li>
<li> !>></li>
<li>&>></li>
<li> %>></li>
<li>#>></li>
<li>@>></li>
<li>/>></li>
<li>*>></li>
<li> ?>></li>
<li>|>></li>
<li>^>></li>
<li>~>></li>
<li>=>></li>
<li>**></li>
<li>**>></li>
<li>&&></li>
<li>&&>></li>
<li>||></li>
<li>||>></li>
<li>$></li>
<li>$>></li>
<li>+=</li>
<li>-=</li>
<li>**=</li>
<li>*=</li>
<li>/=</li>
<li> %=</li>
<li>and</li>
<li>nand</li>
<li>&=</li>
<li>&&=</li>
<li>^=</li>
<li>or</li>
<li>xor</li>
<li>nor</li>
<li>|=</li>
<li>||=</li>
<li><<=</li>
<li>>>=</li>
<li><-</li>
<li>return</li>
</ul><p>And as mentioned above, all of these can be used for your own purpose,
although some of them already have reserved meanings. This document will cover
most of the used operators, while the rest can be found in the reference.</p>
<p>Since this operator shuffling happens, that also means that an Ioke program
has a canonical inner form that can differ from the source text. When you use
introspection of any kind, you will get back that canonical form which might
not look exactly like you expected. Similarly, if you ask some code to print
itself, it will use the canonical form instead of the operator skin. Macros
that modify message chains should work against the canonical form, and nothing
else.</p>
<p>What an operator does depends on the result of sending the message of that
name to the receiver, just like regular messages. In fact, to Ioke there really
isn't any difference, except that the parsing takes special notice about
operators and assignment operators.</p>
<a name="Assignment_shuffling"></a>
<h2><span class="mw-headline">Assignment shuffling</span></h2>
<h2>代入のようなもの</h2>
<p>Much like with regular operators, trinary - assignment - operators are
subject to a kind of shuffling. This shuffling differs from regular operator
shuffling, in that it will shuffle around two things - the left hand side and
the right hand side. This is true for every assignment operator except for the
unary ones, which will only reshuffle one message.</p>
<p>A few examples might make the translation easier to perceive. The first item
is the readable form, while the second form is the canonical form:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
foo<span class="sy0">=</span><span class="nu0">1</span><span class="sy0">+</span><span class="nu0">2</span><span class="sy0">=</span><span class="br0">(</span>foo,<span class="nu0">1</span><span class="sy0">+</span><span class="br0">(</span><span class="nu0">2</span><span class="br0">)</span><span class="br0">)</span><span class="re9"><span class="re11">Ground</span></span>foo<span class="sy0">*=</span><span class="st0">"text"</span><span class="re9"><span class="re11">Ground</span></span><span class="sy0">*=</span><span class="br0">(</span>foo,<span class="st0">"text"</span><span class="br0">)</span>bar foo<span class="br0">(</span><span class="nu0">123</span><span class="br0">)</span><span class="sy0">=</span><span class="nu0">42</span>bar<span class="sy0">=</span><span class="br0">(</span>foo<span class="br0">(</span><span class="nu0">123</span><span class="br0">)</span>,<span class="nu0">42</span><span class="br0">)</span>flux<span class="sy0">++</span><span class="sy0">++</span><span class="br0">(</span>flux<span class="br0">)</span>
</pre></div>
</div>
<p>These examples show some more advanced details -- specifically the fact that
assignment operators generally work on "places", not on names or cells. This
will be more explored in the chapter on<a href="/wiki/index.php/Guide:Assignment" title="Guide:Assignment">assignment</a>. The
important thing to notice from the above examples is that for most assignments
two things will be rearranged. For the unary operators only one thing will be
moved.</p>
<p>Just as with regular operators, the assignment operators have information in
the 'Message OperatorTable' cell. The specific cell is 'Message OperatorTable
trinaryOperators', and it matches an assignment operator to either the integer
1, or the integer 2. Everything with 1 will be matched as being unary
assignment.</p>
<p>The currently available assignment operators are:</p>
<ul><li>=</li>
<li>++</li>
<li>--</li>
<li>+=</li>
<li>-=</li>
<li>/=</li>
<li>**=</li>
<li>*=</li>
<li> %=</li>
<li>&=</li>
<li>&&=</li>
<li>|=</li>
<li>||=</li>
<li>^=</li>
<li><<=</li>
<li>>>=</li>
</ul><p>Just as with regular operators, what an assignment operator does depend on
what the result is from sending the message of that name to the receiver
object, just like with any type of message.</p>
<a name="Inverted_operators"></a>
<h2><span class="mw-headline">Inverted operators</span></h2>
<h2><span class="mw-headline">否定演算子</span></h2>
<p>In addition to the regular binary operators and the trinary assignment
operators, Ioke also sports inverted operators. These aren't actually used
anywhere in the core distribution, but they might be useful at some time or
another. The basic idea is that sometimes you want to have the right hand side
of an expresssion become the receiver of an operator call, and the left hand
side become the argument to the operator. Inverted operators allow this.</p>
<p>As with both the binary and trinary operators, you can find and update
information about inverted operators in the cell 'Message OperatorTable
invertedOperators'. To make this a little less abstract, let us look at two
simple examples and what they translate into:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="st0">"foo"</span><span class="re13">:</span><span class="re13">:</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span><span class="br0">]</span>map<span class="br0">(</span>asText<span class="br0">)</span><span class="co1">;; will be translated to</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span><span class="br0">]</span>map<span class="br0">(</span>asText<span class="br0">)</span><span class="re13">:</span><span class="re12"><span class="re13">:</span><span class="br0">(</span></span><span class="st0">"foo"</span><span class="br0">)</span><span class="co1">;; provided we have an inverted</span><span class="co1">;; operator called 'doit'</span>abc foo quux doit another time<span class="co1">;; will be translated to</span>another time doit<span class="br0">(</span>abc foo quux<span class="br0">)</span>
</pre></div>
</div>
<a name="Execution_model"></a>
<h1><span class="mw-headline">Execution model</span></h1>
<h1><span class="mw-headline">実行モデル</span></h1>
<p>The way an Ioke program works is very simple. Everything executes based on
two things. The first is the context, or the ground, and the second is the
receiver. The first message sent in each message chain will have the ground as
receiver. The default ground in Ioke source files is an object
called<code>Ground</code>. This object is in the mimic chain for most regular
objects created in Ioke, which means that things defined at the top level will
generally be available in most objects. Inside of methods and blocks, the
ground will be different. Exactly in what way is defined by the type of code
executing.</p>
<p>Every message in a chain will be sent to the receiver of that message. That
receiver is the result of the last message, or the current ground if there was
no previous message, or if that previous message was a terminator. So Ioke code
like<code>foo bar(flux bar) quux</code>involves 5 different messages.</p>
<ol><li>The message<code>foo</code>is sent to<code>Ground</code>, which is the
current ground and also the default receiver.</li>
<li>The message<code>bar</code>is sent to the result of
the<code>foo</code>message. The value returned will be activated.</li>
<li>The cell<code>bar</code>contains a method in this case, and that method
expects one argument, so that forces evaluation of the arguments.</li>
<li>The message<code>flux</code>is sent to<code>Ground</code>, since it's the
ground and there is no prior message inside of an argument list.</li>
<li>The message<code>bar</code>is sent to the result of
the<code>flux</code>message.</li>
<li>The result of the<code>bar</code>message is used as the argument value
given to the outside<code>bar</code>method.</li>
<li>The message<code>quux</code>is sent to the result of the
initial<code>bar</code>message.</li>
<li>The result of the<code>quux</code>message is thrown away, unless this code
is part of a larger piece of code.</li>
</ol><p>This description generally describes what happens in the case of this code.
The more general control flow is this:</p>
<ol><li>A message is encountered</li>
<li>If the message is a symbol message, the corresponding symbol will be
returned.</li>
<li>Otherwise the name of the message will be looked up in the receiver, or in
the receivers mimics.</li>
<li>If the name is found and is not activatable, the value of that name (the
cell) is returned.</li>
<li>If the name is found and is activatable, it will be activated, with the
current ground, receiver and message sent to the activatable object.</li>
<li>If the name is not found, a second search is done for the
name<code>pass</code>. If a pass is found, use that instead of the name of the
original message, and go back to 4.</li>
<li>If a pass is not found, signal a<a href="http://ioke.org/dok/kinds/Condition/Error/NoSuchCell.html" class="external text" title="http://ioke.org/dok/kinds/Condition/Error/NoSuchCell.html"><code>Condition
Error NoSuchCell</code></a>condition.</li>
</ol><p>Exactly what happens when an object is activated depends on what kind of
code gets activated. It's really up to the method, block or macro to handle
evaluation of arguments in any way it likes - including not evaluating them.
For a description of the default models available, see the chapter on<a href="/wiki/index.php/Guide:Code" title="Guide:Code">code</a>.</p>
<a name="Objects"></a>
<h1><span class="mw-headline">Objects</span></h1>
<h1><span class="mw-headline">オブジェクト</span></h1>
<p>The object model of Ioke is quite simple. Everything in Ioke is an object
that follows these same rules. An object is something with an identity. It can
have zero or more mimics, and zero or more cells. An object can also have a
documentation text. Some objects can have a native data component. This acts
more or less like a hidden cell that contains information that can't be
directly represented in Ioke - for example the actual text in a Text. Or the
actual number in a Number. Or the actual regular expression in a Regexp. These
objects are the core types that contain primitive information.</p>
<p>A cell is the main way of representing data in Ioke. A cell has a name and a
value. Every value in Ioke is a cell - every time you send a message, a cell is
looked up for the value of that cell. Cells can contain any kind of data. In
other languages, cells are generally called properties or slots. They are quite
close to instance variables that also can contain methods. Cells can be added
and removed at any time during runtime.</p>
<p>A mimic could also be called the parent of the object. Ioke is a prototype
based language, which means that there is no distinction between classes of
objects, and the objects themselves. In fact, any object can be used as the
"class" of a new object. The word for that is mimicking, since the word "class"
loses it's meaning in this kind of language. It's most common for an object to
mimic one other object, at least initially. It's impossible to create an object
that doesn't mimic anything, but you can remove all mimics for an object after
the fact. You can also add more mimics. This turns out to be useful to
represent shared functionality in the manner of Ruby mixins, for example. The
actual effect of a mimic is that when a cell can't be found in the current
object, all mimics will be searched for that cell (depth-first). So all cells
available in an object's mimic is available to the object too. This is the
inheritance part of Object-Oriented Programming.</p>
<p>In many places you will find the word "kind" being used. A Kind is by
convention an object that is used primarily to use as a mimic for other
objects. The convention is that kinds are named with an initial upper case
letter, while everything else starts with a lower case letter. The assignment
process of Ioke also uses this convention to automatically set a cell called
"kind" on any object that gets assigned to a name matching this convention.</p>
<p>The rest of this chapter will discuss the kinds that are the basis of the
object system.</p>
<a name="Base"></a>
<h2><span class="mw-headline">Base</span></h2>
<p>The kind called Base is the top of the mimic chain. It's not generally
useful in itself as it only defines the bare minimum of cells to make it
possible to add new cells to it, mimic it, and so on. But if you want an object
that is possible to use but not include most of the other stuff, Base is place
to begin. Be careful when defining methods in Base, since it doesn't have
access to most of the namespace. In fact, it doesn't even know about its own
name. Base can act as a kind of blank slate, if needed, but it's probably
easier to just create a regular object and remove all mimics from it after the
fact.</p>
<p>Base defines these cells:</p>
<dl><dt>kind</dt>
<dd>returns the kind of the object, which is "Base".</dd>
<dt>notice</dt>
<dd>returns the short notice of the object, which is "Base". Refer to<a href="http://ioke.org/#introspection" class="external text" title="http://ioke.org/#introspection">Introspection</a>for more information about
notice.</dd>
<dt>=</dt>
<dd>Takes two values, the first a place and the second a value, and assigns the
place named to that value. Refer to<a href="http://ioke.org/#assignment" class="external text" title="http://ioke.org/#assignment">Assignment</a>for more
information about it.</dd>
<dt>==</dt>
<dd>Compares this object against the argument. Returns true if they are the
same, otherwise false.</dd>
<dt>cell</dt>
<dd>Takes one argument that should be the name of a cell that exists, and
returns the value of the cell unactivated.</dd>
<dt>cell=</dt>
<dd>Sets a cell to a specific value. Used to set cells that can't be set using
the regular assignment model. Refer to<a href="http://ioke.org/#assignment" class="external text" title="http://ioke.org/#assignment">Assignment</a>for
more information about it.</dd>
<dt>cell?</dt>
<dd>Takes one argument that should be the name of a cell to check if it exists
in this objects mimic chain.</dd>
<dt>cellNames</dt>
<dd>Returns a List containing the names of all cells this object contains.</dd>
<dt>cells</dt>
<dd>Returns a Dict with all cells this object contains. The key is the name and
the value is the cell value.</dd>
<dt>cellOwner</dt>
<dd>Returns the closest mimic that has a cell with the name given as argument
to the message. A condition will be signalled if you try to find the owner of a
cell that doesn't exist in this mimic tree. This method will only return the
closest cell owner for the named cell. It will not use "pass", so it's the
responsibility of pass-implementers to make it return a correct result for
those names.</dd>
<dt>cellOwner?</dt>
<dd>Takes the name of a cell and returns true if the receiver of the message
defines a cell by that name, otherwise false. Note that there can be more than
one cell owner in a message chain. This just returns true if the current
receiver is the closest one.</dd>
<dt>removeCell!</dt>
<dd>Removes the named cell from the current object. This means that if the
current cell shadowed cells in mimics, those can be called again. It only
removes a cell if the receiver is the owner of that cell. Otherwise it is an
error to call this method.</dd>
<dt>undefineCell!</dt>
<dd>Makes it impossible to find a cell from the receiver. In all ways it looks
like this cell doesn't exist in the mimic chain at all, even if mimics define
several implementations of it. The use of undefining can make an object
conceptually totally clean from cells, although it might be hard to use the
objec after that. An interesting side-effect of the way these methods work is
that removeCell! can be used to remove the undefine. So if you call removeCell!
with a cell name and a receiver that has been called with undefine earlier,
that undefine-status will be removed, and access to mimic versions of the cell
will be possible again. Look at the specs for a better understanding.</dd>
<dt>documentation</dt>
<dd>Returns the documentation text for this object, or nil if no documentation
exists for it.</dd>
<dt>documentation=</dt>
<dd>Sets the documentation text for this object.</dd>
<dt>mimic</dt>
<dd>Returns a newly created object that has the receiver as mimic. This is the
magic way of creation new objects in Ioke. It is also the<em>ONLY</em>way to do
it.</dd>
</dl><p>All of these methods are described further in the reference.</p>
<a name="Ground"></a>
<h2><span class="mw-headline">Ground</span></h2>
<p>As mentioned above, Ground is the default ground/context for evaluation.
Ground IokeGround and JavaGround, and IokeGround mimics Base and
DefaultBehavior. IokeGround is special in that this is the place where all top
level kinds are defined. If you want to create a top level kind, you should put
it in IokeGround. If you take a look in IokeGround, you will see that it
contains cells for Text, Dict, List, Base, Origin, itself and many other. Ioke
doesn't have any global state at all, but IokeGround is as close as it gets.
IokeGround and Ground should in most cases not be mimicked directly.</p>
<p>JavaGround is the place where all Java integration support is integrated
into Ioke.</p>
<a name="Origin"></a>
<h2><span class="mw-headline">Origin</span></h2>
<p>Origin should be the place where most objects in Ioke start from. It is
specifically created to be the origin of objects. As such it doesn't contain
many cells for itself, but it mimics Ground and has access to everything from
Base, DefaultBehavior and Ground in that way. When adding new more or less
global functionality, Origin is probably the best place to put it. Currently,
the only cells Origin contains is for purposes of printing itself.</p>
<p>Origin also happens to be the point where initialization is defined. This is
really done as an aspect on 'mimic'. If you want an object to be able to be
initialized every time a new mimic of it is created, just create a method
called initialize in your kind. It will be called by the mimic-aspect. Any
arguments given to mimic will be ignored and passed along to initialize. An
example:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="re11">Foo</span><span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span><span class="re11">Foo</span>initialize<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span><span class="st0">"New foo created!"</span>println<span class="br0">)</span><span class="re11">Foo</span><span class="re6">mimic</span><span class="re11">Foo</span><span class="re6">mimic</span><span class="re11">Foo</span>initialize<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>arg1, key<span class="re12"><span class="re13">:</span>,</span><span class="re6">self</span>value<span class="sy0">=</span><span class="br0">[</span>arg1, key<span class="br0">]</span><span class="br0">)</span><span class="re11">Foo</span><span class="re6">mimic</span><span class="br0">(</span><span class="nu0">42</span>, key<span class="re13">:</span><span class="nu0">15</span><span class="br0">)</span><span class="re11">Foo</span><span class="re6">mimic</span><span class="br0">(</span>key<span class="re13">:</span><span class="st0">"blarg"</span>,<span class="nu0">42</span><span class="br0">)</span>
</pre></div>
</div>
<p>There is nothing special with the initialize method, so if you want more
initialization to happen in a deep hierarchy, you will have to use super-calls
and so on.</p>
<a name="DefaultBehavior"></a>
<h2><span class="mw-headline">DefaultBehavior</span></h2>
<p>DefaultBehavior is a mixin - meaning it should never be the sole mimic of an
object. Mixins are generally not grounded in Base, and doesn't contain most of
the things you would expect from an object. DefaultBehavior contain almost all
the general methods you use when programming Ioke. It contains the internal
methods to create values from literals, and most other functionality specified
in this document. In short, DefaultBehavior is the work horse, and you should
have a pretty good reason to not have it in the mimic chain of an object. Since
Ground mimics DefaultBehavior, any object you create from Origin, will have
DefaultBehavior in its mimic chain.</p>
<a name="nil.2C_true.2C_false"></a>
<h2><span class="mw-headline">nil, true, false</span></h2>
<p>The three values nil, true and false are the only values that are considered
kinds, even though they start with lower case letters. They are not like the
other kinds in the other important way either - these values can not be
mimicked, and you will get a condition if you try it. The reason is that Ioke's
basic boolean system revolves around these values. It is not entirely certrain
that these values will forever be the only boolean values, but for now they
are. nil should be used to represent the absence of a value, including the
absence of a reasonable return value. false is the quintessential false value,
and true is the quintessential true value. The value true isn't strictly
necessary since any value except for nil and false are true. This notion of
truthness mimics Ruby. The cells nil, true and false are defined in Ground, and
they can actually be overridden or changed - but I don't recommend it. I can
guarantee lots of chaos and non-working programs from doing it. More info on
how these values interact can be found in the section on<a href="http://ioke.org/#comparison" class="external text" title="http://ioke.org/#comparison">Comparison</a>.</p>
<a name="Assignment"></a>
<h1><span class="mw-headline">Assignment</span></h1>
<h1><span class="mw-headline">代入</span></h1>
<p>Superficially, Ioke's assignment model is quite simple. But there exists
some subtleties too. One of the main reasons for this is that assigning a cell
that doesn't exist will create that cell. Where it gets created is different
based on what kind of context the assignment happens in. The main difference
here is between a method activation context, or a lexical block context.</p>
<p>Ioke also supports assignment of places, which makes assigning much more
flexible. A third feature of Ioke assignment is that it will check for the
existence of an assignment method before assigning a specific name. This
chapter will make all these things clear, and show some examples.</p>
<p>Let's start with a small example of simple assignment:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
foo<span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span>foo x<span class="sy0">=</span><span class="nu0">42</span>foo y<span class="sy0">=</span><span class="nu0">13</span>foo x<span class="sy0">+=</span><span class="nu0">2</span>
</pre></div>
</div>
<p>The first line creates a new Origin mimic, and then assigns that to the name
foo. Since this code executes at the top level, "foo" will be a new cell
created in Ground. The second line creates a new cell called "x" inside the
"foo" object. It gets assigned the value 42. The third line creates a "y" cell,
and the fourth line sends the += message, which will first call +, and then
assign using =. So at the end of this program, "foo" will contain two cells:
"x" with value 44, and "y" with value 13. As mentioned above, cells get created
the first time they are assigned to. If you need to create a cell in a specific
object, just namespace it. For example, if you want to make sure that you
create a cell in Ground, just do "Ground foo = 42".</p>
<p>Inside of a method, the situation is exactly the same. If you assign
something, it will be assigned in the current context, which is the local
activation context (meaning it's the place where local variables are
available). There are two situations where this doesn't hold true. The first
one is within the special method "do". This method will take any code as
argument and execute that with the receiver of the "do" message as the
ground/context of the code inside it. That means "do" is a good way to create
new cells inside an object.</p>
<p>This is a bit academic, so lets take a look at an example:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="re11">Foo</span><span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span><span class="re11">Foo</span>x<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span><span class="co1">;; this creates a local variable in the method activation</span>foo<span class="sy0">=</span><span class="nu0">42</span><span class="br0">)</span><span class="re11">Foo</span><span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span><span class="re11">Foo</span>do<span class="br0">(</span><span class="co1">;; this creates the cell foo inside of Foo</span>foo<span class="sy0">=</span><span class="nu0">42</span><span class="br0">)</span>
</pre></div>
</div>
<p>Here you can see a method defined called x. This method will just create a
new local cell, which means calling the method will not make any difference on
its receiver at all. The call to "do" in contrast will immediately execute the
code inside it, and this code will create the cell "foo" inside of "Foo".</p>
<p>The second exception to the general rule is when executing inside of a
lexical context. A lexical context is basically established inside of a block,
but can also be created transparently when sending code to a method. A lexical
block will try to not create new cells. When you assign a cell without a
specific place to assign it, a lexical block will first see if there is any
cell with that name further out, and if so it will make the assignment there
instead. Only when no such cell exists, a new cell will be created in the
lexical context. This code shows this in action:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
x<span class="sy0">=</span><span class="nu0">42</span><span class="re8">fn</span><span class="br0">(</span>x<span class="sy0">=</span>43. y<span class="sy0">=</span><span class="nu0">42</span><span class="br0">)</span>call x<span class="co1">;; => 43</span>y<span class="co1">;; => Condition Error NoSuchCell</span>
</pre></div>
</div>
<p>The "fn" message creates a new lexical block. The chapter on<a href="http://ioke.org/#code" class="external text" title="http://ioke.org/#code">code</a>will talk more about this. But as you can see,
this block assigns 43 to the cell "x", and 42 to the cell "y". But since the
cell "y" doesn't exist, it will only be created inside the lexical context,
while "x" exists outside, and will be assigned a new value instead. The basic
idea is that code like this should behave like you expect it to behave.</p>
<p>The canonical form of assignment is a bit different from the way you usually
write code in Ioke. The section on the syntax of assignments talked a bit about
this. Specifically, something like "foo = 42" will get translated into "=(foo,
42)". That also means that assignment is just a regular method call, and can be
overridden or removed just like any other method. That is exactly how both
lexical context, and local method context make it possible to have different
logic here. This is true for all assignment operators.</p>
<p>All assignment operators take as their first argument the place to assign
to. This place will be unevaluated. Only the second argument to an assignment
will be evaluated. In most cases, a place is the same thing as a cell name, but
it doesn't have to be. Let's look at the case of assigning a cell with a
strange name. Say we want to assign the cell with the no name. We can do it
like this:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
cell<span class="br0">(</span><span class="st0">""</span><span class="br0">)</span><span class="sy0">=</span><span class="nu0">42</span>
</pre></div>
</div>
<p>What happens here is a bit subtle. Since the left hand side of the
assignment takes arguments, the "=" method figures out that the assignment is
not to a simple cell name, but to a place. The parsing step will change
"cell("") = 42" into "=(cell(""), 42)". Notice here that the argument comes
along into the specification of the place. When this happens, the assignment
operator will not try to create or assign a cell - instead it will in this case
call the method cell=. So "cell("") = 42" will ultimately end up being the same
as "cell=("", 42)". This way of transforming the name will work the same for
all cases, so you can have as many arguments as you want to the place on the
left hand side. The equals sign will be added to the method name, and a message
will be sent to that instead.</p>
<p>This makes assignment of places highly flexible, and the only thing you need
to do is implement methods with the right names. This feature is used
extensively in Lists and Dicts to make it easy to assign to specific indexes.
So, say we have a list called x. Then this code: "x[13] = 42" will be
transformed into "x =([](13), 42)" which will in turn be transformed into "x
[]=(13, 42)". Ioke lists also has an at= method, so you can do "x at(13) = 42"
which will call at=, of course.</p>
<p>The second transformation that might happen is that if you try to assign a
cell that has an assigner, you will call that assigner instead of actually
assigning a cell. So, for example, if you do "foo documentation = 42", this
will not actually create or assign the cell "documentation". Instead it will
find that Base has a cell called "documentation=", and instead send that
message. So the prior code would actually be equivalent to "foo
documentation=(42)".</p>
<p>All of these assignment processes together make it really easy to take
control over assignment, while still making it very obvious and natural in most
cases.</p>
<a name="Let"></a>
<h2><span class="mw-headline">Let</span></h2>
<p>Sometimes you really need to change the value of something temporarily, but
then make sure that the value gets set back to the original value afterwards.
Other situations often arise when you want to have a new name bound to
something, but maybe not for a complete method. This might be really useful to
create closures, and also to create localized helper methods. For example, the
Ioke implementations for Enumerable use a helper syntax macro. This macro is
bound temporarily, using a let form. This ensures that the syntax doesn't stay
around and pollute the namespace.</p>
<p>A let in Ioke can do two different things, that on the surface look mostly
the same but are really very different operations. The first one is to
introduce new lexical bindings, and the second is to do a dynamic rebind of a
specific place. The easiest way of thinking about it is that the lexical
binding introduces a local change or addition to the available names you're
currently using, while a dynamic rebinding will change the global state
temporarily, and then set it back.</p>
<p>This sounds really academic, so let us go for some examples. We begin with
lexical bindings.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="co1">;; put everything in a method to show explicit scope</span>foo<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>x, y, x println<span class="co1">; => argument value of x</span>let<span class="br0">(</span>x,<span class="nu0">14</span>, x println<span class="co1">; => 14</span><span class="br0">)</span>x println<span class="co1">; => argument value of x</span>y println<span class="co1">; => argument value of y</span>y<span class="sy0">=</span><span class="nu0">13</span>y println<span class="co1">; => 13</span>let<span class="br0">(</span>y,<span class="nu0">14</span>, y println<span class="co1">; => 14</span><span class="br0">)</span>y println<span class="co1">; => 13</span>z println<span class="co1">; will signal condition</span>let<span class="br0">(</span>z,<span class="nu0">42</span>, z println<span class="co1">; => 42</span><span class="br0">)</span>z println<span class="co1">; will signal condition</span><span class="br0">)</span>
</pre></div>
</div>
<p>Here a new method is created that has two arguments, x and y. The first
let-expression will create a new scope where a binding from x to 14 is
established. This binding is valid until the end of the let-form (but it can be
changed, doing an assignment will set the value to something else, but only
until the end of the let form). The same thing is true with y. We can change
the value of y outside of the let form. That changes the actual argument
variable. But a let form that binds y will only have it active for a limited
time. Finally, a let form can also create totally new variables, as when
creating z.</p>
<p>I didn't show any example of it, but the first part of a let-name can be any
kind of place, not just a simple name. Anything you can use with =, can be used
as a name for let. So you could do something like let(cell(""), 42, nil) if you
wanted to.</p>
<p>OK, so that's lexical binding. What about dynamic rebinding? The main
difference in a dynamic binding is that the scope you work in is something that
is referencable from other scopes. In most cases this will be global places,
but not necessarily. You can also rebind cells inside of other objects with the
dynamic binding feature.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
bar<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>let<span class="br0">(</span><span class="re9"><span class="re11">Origin</span></span>foo,<span class="re8">method</span><span class="br0">(</span><span class="st0">"haha"</span>println<span class="br0">)</span>,<span class="st0">"x"</span>foo<span class="re9"><span class="re11">Origin</span></span>foo<span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">]</span>foo<span class="br0">)</span>let<span class="br0">(</span><span class="re9"><span class="re11">Text</span></span>something,<span class="nu0">42</span>,<span class="st0">"abc"</span>something println<span class="co1">; => 42</span><span class="br0">)</span><span class="st0">"abc"</span>something println<span class="co1">; will signal condition</span>let<span class="br0">(</span><span class="re9"><span class="re11">Text</span></span>inspect,<span class="st0">"HAHA"</span>,<span class="st0">"foo bar qux"</span>inspect println<span class="co1">; => "HAHA"</span><span class="br0">)</span><span class="st0">"foo bar qux"</span>inspect println<span class="co1">; => #["foo bar qux"]</span>let<span class="br0">(</span><span class="re9"><span class="re11">Text</span></span>asRational,<span class="re8">method</span><span class="br0">(</span><span class="nu0">42</span><span class="br0">)</span>,<span class="br0">(</span><span class="nu0">3</span><span class="sy0">+</span><span class="st0">"haha"</span><span class="br0">)</span>println<span class="co1">; => 45</span><span class="br0">)</span><span class="br0">)</span>
</pre></div>
</div>
<p>This example actually changes things quite a lot. The first and second
examples introduce new cells into existing places, uses them and then doesn't
do anything. The third example actually overrides an existing cell in Text -
inspect - and then uses it inside of the let code. Finally, after the let block
is over, we see that the original method is back. The fourth example shows that
our changes with let actually are global. There is no asRational on Text, but
we add it temporarily and can then use it in arithmetic with numbers. This is
once again a temporary change that will disappear afterwards.</p>
<p>Ioke's let-form is incredibly powerful, and it allows very nice temporal and
localized changes. Of course, it's a power that can be abused, but it gives
lots of interesting possibilities for expression.</p>
<a name="Control_flow"></a>
<h1><span class="mw-headline">Control flow</span></h1>
<h1><span class="mw-headline">制御フロー</span></h1>
<p>Ioke has some standard control flow operators, like most other languages. In
Ioke, all of these are regular method calls though, and they can usually be
implemented in terms of Ioke. This chapter will chiefly talk about comparisons,
conditionals and iteration constructs.</p>
<a name="Comparison"></a>
<h2><span class="mw-headline">Comparison</span></h2>
<h2><span class="mw-headline">比較</span></h2>
<p>There are several comparison operators in Ioke, but the most important is
called the spaceship operator. This operator is <=>. It takes one
argument and returns -1, 0 or 1 depending on the ordering of the receiver and
the argument. If the two objects can't be compared, it returns nil. If you
implement this operator and mixin Mixins Comparing, you get the operators
==, !=, <, <=, > and >= implemented in terms of the spaceship
operator. There are two other common operators in Ioke. The first =~, which can
also be called the match operator. It's only implemented for Regexp right now.
The === operator also exists, but isn't implemented for most objects. This
operator doesn't do much right now, but is planned to be the basis of a
Ruby-like case-statement further down the line. The contract of comparison
operators is that they should return a true value (not necessarily the true) if
the comparison is true, and otherwise return either false or nil.</p>
<p>The contract for === should be matching or not matching. It is among other
things used in Ranges to see if something is included in that range or not.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
iik<span class="sy0">></span><span class="nu0">1</span><span class="sy0">+</span><span class="nu0">2</span><span class="sy0"><</span><span class="nu0">4</span><span class="sy0">+></span><span class="re6"><span class="re7">true</span></span>iik<span class="sy0">></span><span class="nu0">3</span><span class="sy0">+</span><span class="nu0">2</span><span class="sy0"><</span><span class="nu0">4</span><span class="sy0">+></span><span class="re6"><span class="re7">false</span></span>iik<span class="sy0">></span><span class="st0">"foo"</span><span class="sy0"><=></span><span class="st0">"fop"</span><span class="sy0">+></span><span class="re0">-</span><span class="nu0">1</span>
</pre></div>
</div>
<a name="Conditionals"></a>
<h2><span class="mw-headline">Conditionals</span></h2>
<h2>条件分岐</h2>
<p>Ioke has two different ways of doing conditionals. The first one is the
default, and is also the traditional conditional from other languages. The
second version looks more like Smalltalk conditionals.</p>
<p>As with everything else, these conditionals are all methods, and can be
overridden and changed if need be. They can also be polymorphic.</p>
<p>The default conditionals are called "if" and "unless". They both take an
initial evaluated argument that is used to check which branch should be taken.
The "if" method will execute it's second argument if the first argument is
true, and the third argument if the first argument is false. The "unless"
method does the inverse -- executing the second argument if the first argument
is false, and the third argument if the first argument is true. One or both of
the branches can be left out from the statement. If no else-part is around and
the conditional part evaluates to a false value, that false value will be
returned.</p>
<p>A few examples are in order:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
if<span class="br0">(</span><span class="nu0">42</span><span class="sy0"><</span><span class="nu0">43</span>,<span class="st0">"wow, math comparison works"</span>println,<span class="st0">"we have some serious trouble"</span>println<span class="br0">)</span>if<span class="br0">(</span><span class="nu0">42</span><span class="sy0"><</span><span class="nu0">43</span>,<span class="st0">"wow, math comparison works"</span>,<span class="st0">"we have some serious trouble"</span><span class="br0">)</span>println<span class="re7">unless</span><span class="br0">(</span><span class="nu0">42</span><span class="sy0"><</span><span class="nu0">43</span>,<span class="st0">"convoluted math"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>It is good style to not use "unless" with an else branch. It generally tends
to not be so readable that way. Remember that "if" and "unless" return their
values, which means they are expressions like everything else. The middle
example show that you can just call println on the result of the if-call,
instead of doing it twice inside. This is also good style. Assigning the result
of an if-call is likewise not a problem.</p>
<p>In some languages you see a pattern such as "if(foo =
someExpensiveMethodCall(), foo println)", where a variable is assigned in the
condition evaluation so the value doesn't have to be evaluated twice. This
works in Ioke too, but there is a more idiomatic way of doing it. Both "if" and
"unless" establish a lexical context, where a variable called "it" is
available. This variable will be bound to the result of the conditional. So the
above idiom could instead be written "if(someExpensiveMethodCall(), it
println)". This is the preferred way of handling regular expression
matching.</p>
<p>The Smalltalk inspired way of doing conditionals rest on the methods called
ifTrue and ifFalse. Both of these methods are only defined on true and false,
which means they are not as general as the if and unless statements. They can
also be chained together, so you can write:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="br0">(</span><span class="nu0">42</span><span class="sy0"><</span><span class="nu0">43</span><span class="br0">)</span>ifTrue<span class="br0">(</span><span class="st0">"wowsie!"</span>println<span class="br0">)</span>ifFalse<span class="br0">(</span><span class="st0">"oh noes"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>As should be obvious from these examples, these conditionals can not return
any value. They must only rely on side effects to achieve anything.</p>
<p>Ioke also supports the expected short circuiting boolean evaluators. They
are implemented as regular methods and are available on all objects. All of the
expected combinators are available, including "and", "&&", "or", "||",
"xor", "nor" and "nand".</p>
<a name="cond"></a>
<h3><span class="mw-headline">cond</span></h3>
<p>Ioke doesn't have any else-if expression, which means that when you want to
do several nested checks, you end up with lots of indentation. Cond is a macro
that expands to that code. The code using cond will not have more indentation,
which means it might be easier to read. A cond has one or more conditional
expressions followed by an action part to execute if that condition is true. As
soon as a condition has evaluated to true cond will not evaluate any more
conditions or actions. If no conditions evaluate to true, nil will be returned,
unless there is an action part following the last action-part. In other terms,
if the cond-expression has an odd number of arguments, the last argument is the
default case to execute if nothing else matches.</p>
<p>Some examples of cond:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
cond<span class="br0">(</span>x<span class="sy0">==</span><span class="nu0">1</span>,<span class="st0">"one"</span>println, x<span class="sy0">==</span><span class="re0">-</span><span class="nu0">1</span>,<span class="st0">"minus one"</span>println, x<span class="sy0"><</span><span class="nu0">0</span>,<span class="st0">"negative"</span>println, x<span class="sy0">></span><span class="nu0">0</span>,<span class="st0">"positive"</span>println,<span class="st0">"zero"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>As you can see, it becomes quite clear what happens here. Keep in mind that
cond is an expression, just like anything else in Ioke, and will return the
last value evaluated.</p>
<a name="case"></a>
<h3><span class="mw-headline">case</span></h3>
<p>A thing that you very often want to do is to check one value against several
different conditions. The case expression allows this to be done succinctly.
The core to the case-expression is the === method, that is used for matching.
The expression takes one value, then one or more conditionals followed by
actions, and then an optional default part. Once something matches, no more
conditionals will be executed. The conditional part should not be a complete
conditional statement. Instead it should return something that implements a
fitting ===. So, a small example follows:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
case<span class="br0">(</span>value,<span class="re9"><span class="re11">Text</span></span>,<span class="st0">"it is a text!"</span>println, 1<span class="sy0">..</span>10,<span class="st0">"it is a low number"</span>println,<span class="re12"><span class="re13">:</span>blurg,</span><span class="st0">"it is the symbol blurg"</span>println,<span class="re8">fn</span><span class="br0">(</span>c,<span class="br0">(</span>c<span class="re0">+</span><span class="nu0">2</span><span class="br0">)</span><span class="sy0">==</span><span class="nu0">10</span><span class="br0">)</span>,<span class="st0">"it is 8"</span>println,<span class="st0">"we don't know it!"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>The above example shows several different things you can match against,
including a lexical block. The implementation of === for a lexical block will
call the block with the value and then return true or false depending on the
truth-value of the result of the call to the block.</p>
<p>A thing that can be inconvenient in some languages is to do combinations of
several of these. Say you want to check that something is a Text and matches a
regular expression, or it is either 5..10 or 15..20. In most cases you will end
up having to write several conditional parts for at least one of those two. But
Ioke allows you to use combiners in the conditional part of a case expression.
These combiners will be rewritten before executed, so a combiner called "else"
will actually use the method "case:else", that in turn returns an object that
responds correctly to ===. The end result is that using combiners read really
well, and you can define your own by prefixing the name with "case:". There are
several standard ones. Using a few of them looks like this:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
case<span class="br0">(</span>value,<span class="re5">and</span><span class="br0">(</span><span class="re9"><span class="re11">Text</span></span>,<span class="sy0">#/</span>o<span class="sy0">+/</span><span class="br0">)</span>,<span class="st0">"it's a text with several oos"</span>println,<span class="re5">or</span><span class="br0">(</span>5<span class="sy0">..</span>10, 15<span class="sy0">..</span>20<span class="br0">)</span>,<span class="st0">"numberific"</span>println, else,<span class="st0">"oh no!"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>Combiners can be combined with each other and nested, so you could do
and(foo, or(1, 2, 3), not(x)) if you want.</p>
<p>The available combiners are these:</p>
<dl><dt>and</dt>
<dd>Returns a matcher that returns true if all the arguments return true when
calling ===. This is short circuiting.</dd>
<dt>or</dt>
<dd>Returns a matcher that returns true if any of the arguments return true
when calling ===. This is short circuiting.</dd>
<dt>not</dt>
<dd>Takes one argument and returns the false if calling === on the argument
returns true, and the other way around.</dd>
<dt>nand</dt>
<dd>The nand operation applied to === combiners.</dd>
<dt>nor</dt>
<dd>The nor operation applied to === combiners.</dd>
<dt>xor</dt>
<dd>The xor operation applied to === combiners.</dd>
<dt>else<br /></dt>
</dl><p>otherwise</p>
<dl><dd>Returns a matcher that always returns true. This is useful to make the
default argument read better.</dd>
</dl><a name="Iteration"></a>
<h2><span class="mw-headline">Iteration</span></h2>
<h2><span class="mw-headline">繰り返し</span></h2>
<p>Ioke supports most of the expected control flow operations for iteration.
The one thing that is missing is the for-loop. Since the for-loop encourages
low level stepping, and can be replaced by other kinds of operations, I don't
see any reason in having it in Ioke. In fact, the for-statement in Ruby is
generally considered bad form too. And if someone really wants a for-loop it's
really easy to implement. For now I'm reserving the name if I would like to add
comprehensions at some point.</p>
<a name="loop"></a>
<h3><span class="mw-headline">loop</span></h3>
<p>For creating infinte loops, the "loop"-method is the thing. It will just
take a piece of code and execute it over and over again until some non-local
flow control rips the execution up. Using it is as simple as calling it:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
loop<span class="br0">(</span><span class="st0">"hello"</span>println<span class="br0">)</span>x<span class="sy0">=</span><span class="nu0">0</span>loop<span class="br0">(</span>if<span class="br0">(</span>x<span class="sy0">></span><span class="nu0">10</span>,<span class="re7">break</span><span class="br0">)</span>x<span class="sy0">++</span><span class="br0">)</span>
</pre></div>
</div>
<p>The first example will loop forever, printing hello over and over again. The
second example will increment a variable until it's larger then 10, and then it
will break out of the loop.</p>
<a name="while"></a>
<h3><span class="mw-headline">while</span></h3>
<p>The Ioke while loop works exactly like while-loops in other languages. It
takes one argument that is a condition to reevaluate on each iteration, and
another argument that is the code to evaluate each iteration. The result of the
while-loop is the result of the last executed expression in the body.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
x<span class="sy0">=</span><span class="nu0">0</span>while<span class="br0">(</span>x<span class="sy0"><</span><span class="nu0">10</span>, x println x<span class="sy0">++</span><span class="br0">)</span>
</pre></div>
</div>
<a name="until"></a>
<h3><span class="mw-headline">until</span></h3>
<p>The until-loop works the same as the while-loop, except it expects its
condition argument to evaluate to false. It will stop iterating when the
conditional is true for the first time.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
x<span class="sy0">=</span><span class="nu0">0</span>until<span class="br0">(</span>x<span class="sy0">==</span><span class="nu0">10</span>, x println x<span class="sy0">++</span><span class="br0">)</span>
</pre></div>
</div>
<a name="times"></a>
<h3><span class="mw-headline">times</span></h3>
<p>A very common need is to iterate something a certain number of times. The
Number Integer kind defines a method called "times" that does exactly this.
It's got two forms - one with one argument and one with two arguments. With one
argument, it will just run the argument code the specified number of times, and
with two arguments the first argument should be the name of a cell to assign
the current iteration value to and the second is the code to execute.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="nu0">3</span>times<span class="br0">(</span><span class="st0">"hello"</span>println<span class="br0">)</span><span class="nu0">4</span>times<span class="br0">(</span>n,<span class="st0">"#{n}: wow"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>The first example will print hello three times, while the second example
will count up from 0 to 3, printing the number followed by "wow".</p>
<a name="each"></a>
<h3><span class="mw-headline">each</span></h3>
<p>For most iteration needs, you want to traverse a collection in some way. The
standard way of doing this is with the "each"-method. It's defined on all
central collection classes and is also the basis of the contract for Mixins
Enumerable. The contract for each has three different forms, and all should be
implemented if you decide to implement the each method.</p>
<p>The each method should -- as the name implies -- do something for each entry
in the collection it belongs to. So calling each on a set would do something
with each entry, etc. Exactly what that is depends on how many arguments are
given to "each".</p>
<p>If one argument is given, it should be a message chain. This message chain
will be applied to each element.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="br0">[</span><span class="re12"><span class="re13">:</span>one,</span><span class="re12"><span class="re13">:</span>two,</span><span class="re12"><span class="re13">:</span>three<span class="br0">]</span></span>each<span class="br0">(</span>inspect println<span class="br0">)</span><span class="co1">;; the above would execute:</span><span class="re12"><span class="re13">:</span>one</span>inspect println<span class="re12"><span class="re13">:</span>two</span>inspect println<span class="re12"><span class="re13">:</span>three</span>inspect println
</pre></div>
</div>
<p>Another way of saying it is that the message chain will be executed using
each element of the collection as receiver, in turn. The return value will be
thrown away in this case, so to achieve anything, the code need to mutate data
somewhere.</p>
<p>The second -- and most common -- form, takes two arguments. The first
argument should be the name of a cell to assign each element to, and the second
argument should be the code to execute. Under the covers, this form will
establish a new lexical context for the code to run in. As with the first
version, each return value will be trown away.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="br0">[</span><span class="nu0">2</span>,<span class="nu0">4</span>,<span class="nu0">6</span><span class="br0">]</span>each<span class="br0">(</span>x,<span class="br0">(</span>x<span class="sy0">*</span>x<span class="br0">)</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>Here, the name "x" will be used as the name of each element of the list in
turn, while executing the code.</p>
<p>The final form of each takes three arguments, where the first is the name of
a cell to assign the current index, and the other two arguments are the same as
the above.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="br0">[</span><span class="nu0">2</span>,<span class="nu0">4</span>,<span class="nu0">6</span><span class="br0">]</span>each<span class="br0">(</span>i, x,<span class="st0">"#{i}: #{(x*x)}"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>The above code would print:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="nu0">0</span><span class="re13">:</span><span class="nu0">4</span><span class="nu0">1</span><span class="re13">:</span><span class="nu0">16</span><span class="nu0">2</span><span class="re13">:</span><span class="nu0">36</span>
</pre></div>
</div>
<a name="break.2C_continue"></a>
<h3><span class="mw-headline">break, continue</span></h3>
<p>When executing loops it is sometimes important to be able to interrupt
execution prematurely. In this cases the break and continue methods allow this
for "loop", "while" and "until". Both break and continue work lexically, so if
you send code to another method that uses these methods, they will generally
jump out of a lexically visible loop, just like expected.</p>
<p>The break method takes an optional value to return. If no value is provided
it will default to nil. When breaking out of a loop, that loop will return the
value given to break. The continue method will not break out of the execution,
but will instead jump to the beginning and reevaluate the condition once
again.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
while<span class="br0">(</span><span class="re6"><span class="re7">true</span></span>,<span class="re7">break</span><span class="br0">(</span><span class="nu0">42</span><span class="br0">)</span><span class="br0">)</span>
</pre></div>
</div>
<p>This code will immediately return 42 from the while-loop, even though it
should have iterated forever.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
i<span class="sy0">=</span><span class="nu0">0</span>while<span class="br0">(</span>i<span class="sy0"><</span><span class="nu0">10</span>, i println if<span class="br0">(</span>i<span class="sy0">==</span><span class="nu0">5</span>, i<span class="sy0">=</span><span class="nu0">7</span><span class="re7">continue</span><span class="br0">)</span>i<span class="sy0">++</span><span class="br0">)</span>
</pre></div>
</div>
<p>This code uses continue to jump over a specific number, so it will only
print 0 to 5, and 7 to 9.</p>
<a name="Comprehensions"></a>
<h2><span class="mw-headline">Comprehensions</span></h2>
<h2><span class="mw-headline">包含</span></h2>
<p>Ioke's Enumerable mimic makes it really easy to use higher order operations
to transform and work with collections of data. But in some cases the code for
doing that might not be as clear as it could be. Comprehensions allow a list,
set or dict to be created based on a more abstract definition of what should be
done. The specific parts of a comprehension are generators, filters and the
mapping. The generators are what data to work on, the filters chooses more
specifically among the generated data, and the mapping decides what the output
should look like.</p>
<p>The following example does three nested iterations and returns all
combinations where the product of the number is larger than 100:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
for<span class="br0">(</span>x<span class="sy0"><-</span>1<span class="sy0">..</span>20, y<span class="sy0"><-</span>1<span class="sy0">..</span>20, z<span class="sy0"><-</span>1<span class="sy0">..</span>20, val<span class="sy0">=</span>x<span class="sy0">*</span>y<span class="sy0">*</span>z, val<span class="sy0">></span><span class="nu0">100</span>,<span class="br0">[</span>x, y, z, val<span class="br0">]</span><span class="br0">)</span>
</pre></div>
</div>
<p>This code neatly shows all things you can do in a comprehension. The final
argument will always be the output mapping, which in this case is a list of the
three variables, and their product. The generator parts is first a name, the
<- operator followed by an expression that is Enumerable. You can also see
that one of the expressions is an assignment, that can be used later. Finally,
there is a conditional that limits what the output will be. The more or less
equivalent expression using Enumerable methods would be 1..20 flatMap(x, 1..20
flatMap(y, 1..20 filter(z, x*y*z > 100) map([x,y,z,x*y*z]))). In my eyes,
the for-comprehension is much more readable.</p>
<p>There are two variations on this. The first one is when you want the output
to be a Set of things instead of a List. The code is exactly the same, except
instead of using for, you use for:set. There is also a for:dict version, for
more esoteric usages.</p>
<a name="Code"></a>
<h1><span class="mw-headline">Code</span></h1>
<h1><span class="mw-headline">コード</span></h1>
<p>Many of the things you do in Ioke will directly manipulate code. Since the
messages that make up code is really easy to get hold of, this manipulation
comes easy too. Ioke takes the Lisp philosophy of "code is data" to heart. The
basic unit of a piece of code is a Message. A Message has a name, a next and
prev pointer, and any number of arguments. When you manipulate a message, the
argument list will contain messages too - and if the next or prev pointers are
not nil, they will point to other messages. It serves well to remember that
except for the message itself, all code will be evaluated in the context of a
receiver and a ground. The ground is necessary because arguments to be
evaluated need to be run in some specific context, even though the current
receiver is not the same as the ground.</p>
<p>The current types of code can be divided into three different categories.
These are methods, macros and blocks. Native methods are all of the kind
JavaMethod, but can have any kind of semantics - including semantics that look
like macros. Most native methods do have the same semantics as regular methods,
however.</p>
<a name="Methods"></a>
<h2><span class="mw-headline">Methods</span></h2>
<h2><span class="mw-headline">メソッド</span></h2>
<p>A method in Ioke is executable code that is activatable. A method can take
arguments of several different types. The arguments to a method will always be
evaluated before the code in the method starts to execute. An Ioke method is
defined using the "method" method. All Ioke methods have the kind
DefaultMethod. This leaves the room open to define other kinds of methods, if
need be. DefaultMethod's could be implemented using macros, but at this point
they aren't. A DefaultMethod can have a name - and will get a name the first
time it is assigned to a cell.</p>
<p>It is really easy to define and use a simple method. The easiest case is to
define a method that is empty. This method will just return nil:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span><span class="br0">)</span>m<span class="co1">;; call the method</span>
</pre></div>
</div>
<p>Since methods are activatable, when you name a cell that contains a method,
that method will be invoked. To stop that behavior, use the "cell" method.</p>
<p>The definition of a method can take several different pieces. These are a
documentation string, definitions of positional required arguments, definitions
of positional optional arguments, definitions of keyword arguments, definition
of a rest argument, definition of a keyword rest argument and the actual code
of the method.</p>
<p>Let's take these one by one. First, if the the first element of a call to
"method" is a literal text, and there is at least one more argument in the
definition, then that text will be the documentation text for the method:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="co1">;; a method that returns "foo"</span>m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span><span class="st0">"foo"</span><span class="br0">)</span><span class="co1">;; a method that returns nil, but</span><span class="co1">;; has the documentation text "foo"</span>m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span><span class="st0">"foo"</span>,<span class="re6"><span class="re7">nil</span></span><span class="br0">)</span>
</pre></div>
</div>
<p>A method can take any number of required positional arguments. These will be
checked when a method is called, and if not enough -- or too many -- arguments
are provided, an error will be signalled.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>x, x println<span class="br0">)</span>m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>x, y, z, x<span class="sy0">*</span>y<span class="sy0">+</span>z<span class="br0">)</span>
</pre></div>
</div>
<p>The first method takes one argument and prints that argument. The second
method takes three arguments and return the product of the two first added to
the third.</p>
<p>A method can also have optional positional arguments. In that case the
optional arguments must follow the required arguments. Optional arguments need
to have a default value -- in fact, that is how you distinguish them from
required arguments. The arity of method calls will still be checked, but using
minimum and maximum values instead. The default value for an argument should be
code that can be executed in the context of the running method, so a default
value can refer to earlier positional arguments. A default value can also do
quite complex things, if need be, although it's not really recommended.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="co1">;; takes zero or one arguments</span>m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>x<span class="nu0">42</span>, x println<span class="br0">)</span><span class="co1">;; takes one to three arguments</span>m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>x, y<span class="nu0">42</span>, z<span class="nu0">25</span>, x<span class="sy0">*</span>y<span class="sy0">+</span>z<span class="br0">)</span>
</pre></div>
</div>
<p>The syntax for optional arguments is to just write a space after the name of
the argument, and then write the code to generate the default value after
it.</p>
<p>A method can also have keyword arguments. Keyword arguments are checked,
just like regular arguments, and you can't generally give keyword arguments to
a method not expecting it. Nor can you give unexpected keyword arguments to a
method that takes other keywords. Keyword arguments can never be required. They
can have default values, which will default to nil if not provided. They can be
defined anywhere among the arguments -- the only reason to reorder them is that
default values of other optional arguments can use prior defined keyword
arguments.</p>
<p>A keyword argument is defined just like a regular argument, except that it
ends in a colon.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>foo<span class="re12"><span class="re13">:</span>,</span>bar<span class="re13">:</span><span class="nu0">42</span>, foo println bar println<span class="br0">)</span>
</pre></div>
</div>
<p>Just as with regular optional arguments, you supply the default value of the
keyword argument after a space. The cells for the keyword arguments will be the
same as their names, without the ending colon. The above code would print nil
and 42 if no arguments were specified. It's important to remember that keyword
arguments and positional arguments do not interact -- except for when
calculating default values. When assigning values it's always possible to see
what is positional and what is a keyword argument.</p>
<p>Ioke methods can collect positional arguments into a list. This allow
methods to take variable number of arguments. The rule is that all other
positional arguments are first calculated, and the remaining positional
arguments will be added to the rest argument. If no positional arguments are
available, the rest argument will be empty. A rest argument is defined by
preceding it with a plus sign in the argument definition. For clarity a rest
argument should be defined last in the list, although it doesn't exactly matter
anyway.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span><span class="sy0">+</span>rest, rest println<span class="br0">)</span>m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>x, y<span class="nu0">42</span>,<span class="re5">+</span>rest, rest println<span class="br0">)</span>
</pre></div>
</div>
<p>The above code defines one method that only takes one rest argument. That
means the method can take any number of arguments and all of them will be
collected into a list. The second method takes one required argument, one
optional argument and any number of extra arguments. So if four arguments are
given, the rest argument will contain two.</p>
<p>The final type of argument is keyword rest arguments. Just like positional
rest arguments, a keyword rest argument can collect all keywords given to a
method, no matter what. If a keyword rest argument is used, no conditions will
be signalled if an unknown keyword is given to a method. If other keywords are
defined, these keywords will not show up in the keyword rest argument. The
keyword rest argument is defined by preceding the name with a +: sigil, and the
keyword rest argument will be a Dict instead of a list. The keys will be
symbols but without the ending colon.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span><span class="sy0">+</span><span class="re12"><span class="re13">:</span>krest,</span>krest println<span class="br0">)</span>m<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>x, y<span class="re12"><span class="re13">:</span>,</span><span class="re5">+</span>rest,<span class="sy0">+</span><span class="re12"><span class="re13">:</span>krest,</span><span class="br0">[</span>x, y, rest, krest<span class="br0">]</span><span class="br0">)</span>
</pre></div>
</div>
<p>The above code first creates a method that can take any number of keyword
arguments but nothing else. The second method takes one required positional
argument, one keyword argument, rest arguments and keyword rest arguments, and
returns a new list containing all the arguments given to it.</p>
<p>The final argument to the method method should always be the code to
execute. This code will be executed in the context of a receiver, that is the
object the method is activated on. A method execution also happens in the
context of the method activation context, where local variables are stored.
This activation context contain some predefined variables that can be used.
These are "self", "@", "currentMessage" and "surroundingContext". Both "self"
and "@" refer to the receiver of the method call. "currentMessage" returns the
message that initiated the activation of the method, and "surroundingContext"
returns the object that represents the context where this method was called
from. Both "self" and "@" can be used to specify that something should be
assigned to the receiver, for example.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
createNewCell<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span>@foo<span class="sy0">=</span><span class="nu0">42</span><span class="br0">)</span>
</pre></div>
</div>
<p>The method create above will create assign the value 42 to the cell "foo" on
the object the method was called on.</p>
<p>When calling a method, you specify positional arguments separated with
commas. You can provide keyword arguments in any order, in any place inside the
braces:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="co1">;; the method foo takes any kind of argument</span>foo foo<span class="br0">(</span><span class="br0">)</span>foo<span class="br0">(</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">)</span>foo<span class="br0">(</span>blarg<span class="re13">:</span><span class="nu0">42</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span><span class="br0">)</span>foo<span class="br0">(</span>quux<span class="re13">:</span><span class="nu0">42</span><span class="sy0">*</span><span class="nu0">2</span><span class="br0">)</span>
</pre></div>
</div>
<p>To give a keyword argument, you just write it exactly like you define
keyword arugments - a name followed by a colon.</p>
<p>Sometimes it can be useful to be able to take a list of values and give them
as positional arguments. The same can be useful to do with a dict of names. You
can do that using splatting. This is done by preceding a list or a dict with an
asterisk. This will result in the method getting the values inside of it as if
the arguments were given directly. You can splat several things to the same
invocation.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
dc<span class="sy0">=</span><span class="br0">{</span>foo<span class="re13">:</span><span class="nu0">42</span>, bar<span class="re13">:</span><span class="nu0">13</span><span class="br0">}</span>ls<span class="sy0">=</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span><span class="br0">]</span>ls2<span class="sy0">=</span><span class="br0">[</span><span class="nu0">42</span>,<span class="nu0">43</span>,<span class="nu0">44</span><span class="br0">]</span>foo<span class="br0">(</span><span class="sy0">*</span>dc<span class="br0">)</span><span class="co1">;; the same as:</span>foo<span class="br0">(</span>foo<span class="re13">:</span><span class="nu0">42</span>, bar<span class="re13">:</span><span class="nu0">13</span><span class="br0">)</span>foo<span class="br0">(</span><span class="sy0">*</span>ls<span class="br0">)</span><span class="co1">;; the same as:</span>foo<span class="br0">(</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span><span class="br0">)</span>foo<span class="br0">(</span><span class="sy0">*</span>ls2,<span class="nu0">111</span>,<span class="sy0">*</span>dc,<span class="sy0">*</span>ls<span class="br0">)</span><span class="co1">;; the same as:</span>foo<span class="br0">(</span><span class="nu0">42</span>,<span class="nu0">43</span>,<span class="nu0">44</span>,<span class="nu0">111</span>, foo<span class="re13">:</span><span class="nu0">42</span>, bar<span class="re13">:</span><span class="nu0">13</span>,<span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span><span class="br0">)</span>
</pre></div>
</div>
<p>If you try to splat something that can't be splatted, a condition will be
signalled.</p>
<a name="Macros"></a>
<h2><span class="mw-headline">Macros</span></h2>
<h2><span class="mw-headline">マクロ</span></h2>
<p>The main difference between a macro and a method in Ioke is that the
arguments to a macro are not evaluated before they are sent to the macro. That
means you have to use macros to send raw message chains in an invocation. In
most languages, this kind of feature is generally called call-by-name. When a
macro gets called, it will get access to a cell called "call" which is a mimic
of the kind Call. This gives access to information about the call and makes it
possible to evaluate the code sent as arguments, check how many arguments are
supplied, and so on.</p>
<p>A macro is created using the "macro" cell on DefaultBehavior. This will
return a mimic of DefaultMacro. Since macros can't define arguments, it's a bit
easier to describe than methods, but the things that can be done with macros
are also a bit more interesting than what can be achieved with methods. One
important thing to keep in mind is that most macros can not receive splatted
arguments. In most cases keyword arguments aren't available either - but they
could be faked if needed. Macros should generally be used to implement control
structures and things that need to manipulate code in different ways.</p>
<p>Just like a method, a macro gets evaluated on a specific receiver. It also
gets the same kind of method activation context, but the contents of it is a
bit different. Specifically, the context for a macro contains cells named
"self", "@", "currentMessage", "surroundingContext" and "call". It's the "call"
cell that is most important. It is a mimic of Call, and Call defines several
important methods for manipulating the call environment. These are:</p>
<dl><dt>arguments</dt>
<dd>This method returns a list containing the unevaluated arguments given to
this message. Any kind of manipulation can be done with these arguments.</dd>
<dt>ground</dt>
<dd>Returns the ground in which the call was initiated. This is necessary to
evaluate arguments in their own environment.</dd>
<dt>message</dt>
<dd>The currently executing message. This is the same as the "currentMessage"
cell in the macro activation context.</dd>
<dt>evaluatedArguments</dt>
<dd>Returns a list containing all arguments, evaluated according to the regular
rules (but not handling splatting or keywords).</dd>
<dt>resendToMethod</dt>
<dd>Allows a specific message to be resent to another method, without manually
copying lots of information.</dd>
</dl><p>These methods are a bit hard to understand, so I'll take some examples from
the implementation of Ioke, and show how macros are used here.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="re9"><span class="re11">Mixins</span></span><span class="re11">Enumerable</span>map<span class="sy0">=</span><span class="re8">macro</span><span class="br0">(</span><span class="st0">"takes one or two arguments. if one argument is given, it will be evaluated as a message chain on each element in the enumerable, and then the result will be collected in a new List. if two arguments are given, the first one should be an unevaluated argument name, which will be bound inside the scope of executing the second piece of code. it's important to notice that the one argument form will establish no context, while the two argument form establishes a new lexical closure."</span>, len<span class="sy0">=</span>call arguments length result<span class="sy0">=</span>list<span class="br0">(</span><span class="br0">)</span>if<span class="br0">(</span>len<span class="sy0">==</span><span class="nu0">1</span>, code<span class="sy0">=</span>call arguments first<span class="re6">self</span>each<span class="br0">(</span>n, result<span class="sy0"><<</span>code evaluateOn<span class="br0">(</span>call ground, cell<span class="br0">(</span><span class="re12"><span class="re13">:</span>n<span class="br0">)</span><span class="br0">)</span><span class="br0">)</span>,</span>code<span class="sy0">=</span><span class="re9"><span class="re11">Lexical</span>Block</span>createFrom<span class="br0">(</span>call arguments, call ground<span class="br0">)</span><span class="re6">self</span>each<span class="br0">(</span>n, result<span class="sy0"><<</span>code call<span class="br0">(</span>cell<span class="br0">(</span><span class="re12"><span class="re13">:</span>n<span class="br0">)</span><span class="br0">)</span><span class="br0">)</span><span class="br0">)</span></span>result<span class="br0">)</span>
</pre></div>
</div>
<p>The code above implements map, one of the methods from Enumerable. The map
method allows one collection to be mapped in a predefined way into something
else. It can take either one or two arguments. If one argument is given, that
is a message chain to apply, and then collect the results. If two arguments are
given, the first is the argument name to use, and the second is the code to
execute for each entry.</p>
<p>The first step is to figure out how many arguments have been given. This is
done by checking the length of the "call arguments" cell. If we have a length
of one, we know that the first argument is a piece of code to apply, so we
assign that argument to a cell called "code". Now, "code" will be a mimic of
Message, and Message has a method called "evaluateOn", that can be used to
fully evaluate a message chain. And that's exactly what we do for each element
in the collection we are in. The result of evaluateOn is added to the result
list. We use "call ground" to get the correct ground for the code to be
evaluated in.</p>
<p>If we get two arguments, it's possible to take a shortcut and generate a
lexical block from those arguments, and then use that. So we call "LexicalBlock
createFrom" and send in the arguments and the ground, and then call that piece
of code once for each element in the collection.</p>
<p>It is a bit tricky to figure out how macros work. I recommend looking at the
implementations of some of the core Ioke methods/macros, since these use much
of the functionality.</p>
<a name="Blocks"></a>
<h2><span class="mw-headline">Blocks</span></h2>
<h2><span class="mw-headline">ブロック</span></h2>
<p>A lexical block allows the execution of a piece of code in the lexical
context of some other code, instead of in a dynamic object scope. A lexical
block does not have a receiver. Instead, it just establishes a new lexical
context, and executes the code in that. The exact effect that has on
assignments has been<a href="/wiki/index.php/Guide:Assignment" title="Guide:Assignment">described</a>earlier.</p>
<p>A lexical block can be created using either the "fn" or the "fnx" methods of
DefaultBehavior. The main difference between the two is that a block created
with "fnx" will be activatable, while something created with "fn" will not.
Lexical blocks handle arguments exactly the same way as methods, so a lexical
block can take optional arguments, keyword arguments, rest arguments and so on.
Both "fn" and "fnx" also take optional documentation text.</p>
<p>A block created with the "fn" method can be invoked using the "call" method
of the kind<a href="http://ioke.org/dok/kinds/LexicalBlock.html" class="external text" title="http://ioke.org/dok/kinds/LexicalBlock.html"><code>LexicalBlock</code></a>.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
x<span class="sy0">=</span><span class="re8">fn</span><span class="br0">(</span>z, z println<span class="br0">)</span>x call<span class="br0">(</span><span class="nu0">42</span><span class="br0">)</span>
</pre></div>
</div>
<p>If a block created with the "fn" method takes one or more explicit
parameters it can also be activated like a regular method. The reason for this
is shown in the code snippet below. Here the result of invoking the block
referred to by "x" is passed to "y" (which may be a regular method or even
another block). If "x" would be fully non-activatable, "x" would be passed to
"y" as is with the argument thrown away. In other words, that would be dead
code. However, you can still refer to the block as "x" without an invocation to
happen.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
x<span class="sy0">=</span><span class="re8">fn</span><span class="br0">(</span>z, z<span class="sy0">+</span><span class="nu0">42</span><span class="br0">)</span>y<span class="br0">(</span>x<span class="br0">(</span><span class="nu0">100</span><span class="br0">)</span><span class="br0">)</span><span class="co1">;; activates the block with argument 100 and passes the result to y</span>x<span class="co1">;; refers to the block without activating it</span>
</pre></div>
</div>
<p>A block created with the "fnx" method is activatable per se and thus can be
activated like a regular method. The default is to use "fn" to create inactive
blocks though, since blocks are generally used to pass pieces of code
around.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
y<span class="sy0">=</span><span class="re8">fnx</span><span class="br0">(</span>z, z println<span class="br0">)</span>y<span class="br0">(</span><span class="nu0">42</span><span class="br0">)</span>
</pre></div>
</div>
<p>A lexical block is a regular kind of object that can be assigned to any
cell, just like other objects. Lexical blocks mimic LexicalBlock, and blocks
don't have names. In contrast to methods and macros, no extra cells will be
added to the activation context for a lexical block.</p>
<a name="Lecros"></a>
<h2><span class="mw-headline">Lecros</span></h2>
<h2><span class="mw-headline">レクロ</span></h2>
<p>A macro works exactly like a method, in that it always has a receiver, and
that receiver is available inside the macro as 'self' and '@'. In some
circumstances it can be really useful to have a macro that behaves like a
lexical block instead - being lexical so it can use cells defined outside of
the definition of the macro. These macros won't have access to 'self' or '@',
since they don't have a receiver in that way. Where such a macro is called is
only based on namespacing.</p>
<p>Ioke supports these kind of macros. They are all mimics of the kind
LexicalMacro, and they are created using the method 'lecro'. A LexicalMacro is
activatable by default, but a non-activatable lecro can be created using
lecrox. The 'lecro' method takes the same arguments as 'macro', and the only
real difference is the way it handles outside cells and the receiver value. A
lecro also has a cell called outerScope that can be used if you need to
explicitly access something in the outer name space - such as call.</p>
<a name="Syntax_2"></a>
<h2><span class="mw-headline">Syntax</span></h2>
<h2><span class="mw-headline">構文</span></h2>
<p>Ioke supports loads of stuff with the standard<code>macro</code>, but
sometimes these are a bit too low level for commonly used operations. Syntax is
one of those cases: you can achieve the same goals with macros, but you don't
really want to. Many features in Ioke S are implemented using syntax.</p>
<p>You can define syntax using the<code>syntax</code>method. This returns a
mimic of<code>DefaultSyntax</code>. You can use the same kind of cells in a
syntax as you can in a macro. What is different with syntax is that syntax can
only return one of two things. The first is<code>nil</code>, and the second is
a message chain. A syntax will only be executed once at every point in the
message chains, because after a syntax executes the first time, it will replace
itself with the result of that evaluation. If that evaluation
returns<code>nil</code>, syntax will just remove itself from the message
chain.</p>
<p>You can use this for many things, but one of the more useful things you can
do is translate a high level declarative definition of something into a low
level executable version. That is exactly how for comprehensions are
implemented.</p>
<p>Syntactic macros are fairly advanced, and take some time to grok. They are
incredibly useful though, and they are used all over the standard library to
achieve all manner of interesting things. Take a look there and things should
hopefully become clearer. It's also a must to read the section on message chain
manipulation and quoting in this guide to make syntax macros readable.</p>
<a name="Destructuring"></a>
<h2><span class="mw-headline">Destructuring</span></h2>
<h2><span class="mw-headline">構造の分解</span></h2>
<p>A common problem with macros is that you want to take several different
combinations of arguments, and do different things depending on how many you
get. Say you might want to take one code argument, but also two optional
arguments that should be evaluated. All of that code turns out to be highly
repetetive, so Ioke contains a collection of syntax macros that make it easier
to write these things. These are collectively called destructuring syntax.</p>
<p>Let us say we have a macro that can be called with any of three types of
argument list: [code], [evaluatedArgument, code], or [evaluatedArgument, code,
evaluatedArgument]. The stuff that should happen is totally different for each
of these cases. With a regular macro the code would look something like
this:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
foo<span class="sy0">=</span><span class="re8">macro</span><span class="br0">(</span>len<span class="sy0">=</span>call arguments length case<span class="br0">(</span>len,<span class="nu0">1</span>, code<span class="sy0">=</span>call arguments<span class="br0">[</span><span class="nu0">0</span><span class="br0">]</span><span class="co1">; do something with the code</span>,<span class="nu0">2</span>, arg1<span class="sy0">=</span>call argAt<span class="br0">(</span><span class="nu0">0</span><span class="br0">)</span>code<span class="sy0">=</span>call arguments<span class="br0">[</span><span class="nu0">1</span><span class="br0">]</span><span class="co1">; do something with the code and arg</span>,<span class="nu0">3</span>, arg1<span class="sy0">=</span>call argAt<span class="br0">(</span><span class="nu0">0</span><span class="br0">)</span>code<span class="sy0">=</span>call arguments<span class="br0">[</span><span class="nu0">1</span><span class="br0">]</span>arg2<span class="sy0">=</span>call argAt<span class="br0">(</span><span class="nu0">2</span><span class="br0">)</span><span class="co1">; do something with the code and args</span><span class="br0">)</span><span class="br0">)</span>
</pre></div>
</div>
<p>As you can see it's really a lot of code to see what happens here, and it is
very imperative in style. But, if I instead use dmacro - which is the
destructuring version of macro - it looks like this:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
foo<span class="sy0">=</span><span class="re8">dmacro</span><span class="br0">(</span><span class="br0">[</span>code<span class="br0">]</span><span class="co1">; do something with the code</span>,<span class="br0">[</span><span class="sy0">></span>arg1, code<span class="br0">]</span><span class="co1">; do something with the code and arg</span>,<span class="br0">[</span><span class="sy0">></span>arg1, code,<span class="sy0">></span>arg2<span class="br0">]</span><span class="co1">; do something with the code and args</span><span class="br0">)</span>
</pre></div>
</div>
<p>dmacro will automatically check the length and extract the different
arguments. The right arrow before the names of arg1 and arg2 marks that these
should be evaluated. And what is more, dmacro will generate code that also
generates a good condition if no argument matching works out. If you give zero
arguments to the first version, it will fail silently. The dmacro will complain
immediately. The dmacro destructuring syntax actually supports several more
ways of ripping arguments apart. You can find this information in the doks for
dmacro. Also, there are equivalent versions of dmacro for lecro, lecrox and
syntax, called dlecro, dlecrox and dsyntax. They do the same thing, except they
act like lecros or syntax instead.</p>
<a name="Message_chains"></a>
<h2><span class="mw-headline">Message chains</span></h2>
<h2><span class="mw-headline">メッセージ鎖</span></h2>
<p>In many cases a macro will take code that is not wrapped up inside of a
method, macro or block. These pieces of code are called message chains, since
their representation will be a raw Message mimic. The chains are quite
flexible, since they can be taken apart, modified and put together again. They
can also be unevaluated and used as data definitions of some kind. That's how
the argument handling to methods are implemented, for example. Since the call
to "method" can be seen as a regular call to a macro, the argument descriptions
are actually just unevaluated message chains that are picked apart to tease out
the argument names. The same technique is applicable in any macro usage.</p>
<p>The term message chain fragment is also used to specifically mean a message
chain that is meant to be put together with something and evaluated. Picture a
daisy chain that gets added at the end of another chain and then executed.
That's what happens if you execute something like<code>[1, 2, 3]
map(*2)</code>. In this case the call to<code>*</code>with the argument 2 will
be a message chain fragment that will be put together with a new receiver
before execution.</p>
<p>To handle syntax correctly - but also to generally handle manipulation of
message chains - it is important to know about the available methods to do
this. I have added quite a lot of nice stuff that makes it easy to work with
message chains.</p>
<p>First, messages are actually<code>Enumerable</code>, so you can use
any<code>Enumerable</code>methods on them. The enumeration always starts at the
receiver. It will not proceed into arguments, just following the next-pointer.
To create a new message or message chain, there are several helpful methods and
operators. The first method is called<code>message</code>and takes an evaluated
name and returns a new message with that name.<code>Message from</code>takes
one argument that will not be evaluated and returns a message chain
corresponding to that argument.<code>Message fromText</code>parses text and
returns the message chain for it.<code>Message wrap</code>takes an evaluated
argument and returns a message that will always return that value. As will be
mentioned later, Message has<code>next=</code>and<code>prev=</code>methods that
you can use to set the next and previous pointers. Message also
has<code>appendArgument</code>and<code>prependArgument</code>that allow you to
add new arguments to the message arguments.</p>
<p>The most used versions for creating message chains are short cuts for the
above. Let us begin with creation. Instead of<code>Message from</code>you can
use '. That is a single quote mark. The message after that will be unevaluated
and returned as a message chain. If you use a `, a backtick, that is equivalent
to<code>Message wrap</code>. And then we have '', that is two single quotes
after each other. This message is generally called metaquote or quasiquote. It
works the same as ', except that it will find any place where ` is used and
insert the value of evaluating the message after the ` and insert that into the
current message chain. Finally, '' will replace a `` with a literal `
message.</p>
<p>You can add new arguments to a message by using the << operator. This
operator returns the receiver.</p>
<p>If you want to chain together a message chain,
using<code>next=</code>and<code>prev=</code>is pretty tedious. You can instead
use the -> operator. This will chain together the left hand side and the
right hand side messages, and return the right hand side message.</p>
<p>I think it is time for some examples:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="co1">; create a new message with name foo</span>x<span class="sy0">=</span>'foo<span class="co1">; add two arguments to the foo message</span>arg<span class="sy0">=</span>'<span class="br0">(</span>bar quux<span class="br0">)</span><span class="br0">(</span>x<span class="sy0"><<</span>arg<span class="br0">)</span><span class="sy0"><<</span>'baz<span class="co1">; what we have done so far could be done with:</span>x<span class="sy0">=</span>'<span class="br0">(</span>foo<span class="br0">(</span>bar quux, baz<span class="br0">)</span><span class="br0">)</span>y<span class="sy0">=</span>'blurg<span class="co1">; chain together x and y</span>x<span class="sy0">-></span>y<span class="co1">; the above is equivalent to</span>if<span class="br0">(</span>y prev, y prev next<span class="sy0">=</span><span class="re6"><span class="re7">nil</span></span><span class="br0">)</span>x next<span class="sy0">=</span>y y prev<span class="sy0">=</span>x val<span class="sy0">=</span><span class="nu0">42</span><span class="co1">; insert the message chain in x</span>''<span class="br0">(</span>foo bar<span class="br0">(</span>`val<span class="br0">)</span>`x<span class="br0">)</span><span class="co1">; the above will return the same as</span>'<span class="br0">(</span>foo bar<span class="br0">(</span><span class="nu0">42</span><span class="br0">)</span>foo<span class="br0">(</span>bar quux, baz<span class="br0">)</span><span class="br0">)</span>
</pre></div>
</div>
<p>To understand these operators, you need to have a clear understanding of how
the internals of message chains work. Once that clicks, these should be fairly
straight forward to understand.</p>
<a name="Introspection_and_reflection"></a>
<h1><span class="mw-headline">Introspection and reflection</span></h1>
<h1><span class="mw-headline">内部構造とリフレクション</span></h1>
<p>Ioke supports quite fancy introspection and reflection capabilities. In
Ioke, reflection includes the ability to change data dynamically, as well as
introspect on it. Since the message based structure of a program is available
at runtime, most things can be changed dynamically. The internal structure of a
program is also very easy to inspect.</p>
<p>All objects in Ioke have some core methods that are used to look at them.
Some come from Base, and some come from DefaultBehavior. The rest of the
reflection and metaprogramming capabilities belong to the Message kind.</p>
<dl><dt>kind</dt>
<dd>Should be a text that gives the full name of the kind this object is
closest mimic to. Except for nil, true and false, this will return a text that
starts with a capital letter.</dd>
</dl><div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="re11">Foo</span><span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span><span class="re11">Foo</span><span class="re6">mimic</span>kind println<span class="re11">Foo</span><span class="re11">Bar</span><span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span><span class="re11">Foo</span><span class="re11">Bar</span><span class="re6">mimic</span>kind println
</pre></div>
</div>
<p>This code will first print "Foo", and then print "Foo Bar", since an object
assigned to a cell with a capital initial letter will get a new kind value.</p>
<dl><dt>kind?</dt>
<dd>Takes one text argument and returns true if the object has that kind
anywhere in its mimic chain.</dd>
</dl><div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="re11">Foo</span><span class="sy0"> = </span><span class="re9"><span class="re11">Origin </span></span><span class="re6">mimic </span>foo <span class="sy0">= </span><span class="re11">Foo </span><span class="re6">mimic </span>foo kind?<span class="br0">(</span><span class="st0">"foo"</span><span class="br0">)</span><span class="co1">;; false </span>foo kind?<span class="br0">(</span><span class="st0">"Foo"</span><span class="br0">)</span><span class="co1">;; true </span>foo kind?<span class="br0">(</span><span class="st0">"Text"</span><span class="br0">)</span><span class="co1">;; false</span> foo kind?<span class="br0">(</span><span class="st0">"Origin"</span><span class="br0">)</span><span class="co1">;; true</span> foo kind?<span class="br0">(</span><span class="st0">"Ground"</span><span class="br0">)</span><span class="co1">;; true </span>foo kind?<span class="br0">(</span><span class="st0">"DefaultBehavior"</span><span class="br0">)</span><span class="co1">;; true </span>foo kind?<span class="br0">(</span><span class="st0">"Base"</span><span class="br0">)</span><span class="co1">;; true</span>
</pre></div>
</div>
<p>As you can see in this example, "kind?" can return true for several
different texts.</p>
<dl><dt>notice</dt>
<dd>When looking at objects, there are two ways to get information about them,
notice and inspect. If you want a brief description of an object where it's
important that the description doesn't take up much space, notice should be
used. If an exhaustive description is needed, inspect should be used instead.
For some objects these both return the same thing, but for Origin mimics, the
difference is large.</dd>
</dl><div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="re11">Foo</span><span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span><span class="re11">Foo</span>x<span class="sy0">=</span><span class="st0">"blarg"</span><span class="re11">Foo</span>y<span class="sy0">=</span><span class="nu0">42</span><span class="re11">Foo</span>notice<span class="co1">;; Foo_0x7CBDE6</span>
</pre></div>
</div>
<p>The default notice for Origin mimics will combine the kind and the unique
hex id for the object, and create a text of that. The "notice" method should be
overridden to provide better information in most cases.</p>
<dl><dt>inspect</dt>
<dd>In contrast to notice, inspect is used to get exhaustive information. If a
composite object is asked for its inspect, a quite large dump of information
will often be shown. For a new object the output will be smaller, but usually
still larger than the notice for it.</dd>
</dl><div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="re11">Foo</span><span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span><span class="re11">Foo</span>x<span class="sy0">=</span><span class="st0">"blarg"</span><span class="re11">Foo</span>y<span class="sy0">=</span><span class="nu0">42</span><span class="re11">Foo</span>inspect println
</pre></div>
</div>
<p>This will print:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="re11">Foo</span>_<span class="re1">0x7CBDE6</span><span class="re13">:</span>kind <span class="sy0">=</span><span class="st0">"Foo"</span>x <span class="sy0">=</span><span class="st0">"blarg"</span>y <span class="sy0">=</span><span class="nu0">42</span>
</pre></div>
</div>
<p>If another representation makes more sense for inspection, "inspect" should
definitely be overridden by custom objects.</p>
<dl><dt>uniqueHexId</dt>
<dd>This method is used to return a text that contains a unique hex identity
for an object. This text is guaranteed to be unique within a virtual machine
for any object, and is the mechanism that "inspect" and "notice" uses.</dd>
</dl><dl><dt>cellSummary</dt>
<dd>Calling "inspect" on any Origin mimic will dispatch to "cellSummary", which
displays all the cell information about a specific object.</dd>
</dl><dl><dt>cell</dt>
<dd>The "cell" method can be used for two different things. The first one is to
get access to a value without activating it, and the second is to get access to
a cell based on a name that you don't know at the time you're writing the
program. The "cell" method takes one argument that is the name of the cell to
fetch. The fetching works the same as regular cell lookup, except that
activation doesn't happen. This means that a condition will still be signalled
if you try to get something that doesn't exist.</dd>
</dl><div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
x<span class="sy0">=</span><span class="nu0">42</span>cell<span class="br0">(</span><span class="re12"><span class="re13">:</span>x<span class="br0">)</span></span><span class="co1">;; 42</span>x<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span><span class="br0">)</span>cell<span class="br0">(</span><span class="re12"><span class="re13">:</span>x<span class="br0">)</span></span><span class="co1">;; the method object</span>name<span class="sy0">=</span><span class="re12"><span class="re13">:</span>foo</span>cell<span class="br0">(</span>name<span class="br0">)</span><span class="co1">;; the value of foo</span>
</pre></div>
</div>
<dl><dt>cell=</dt>
<dd>Just as with "cell", "cell=" can be used to set cells that you don't know
the name of at the time of writing the program. As discussed in the chapter on
assignment, cell= can also be used to set cells that can't be set in the
regular way due to naming strangeness.</dd>
</dl><dl><dt>cell?</dt>
<dd>If you're not sure if a cell exists, using "cell?" is the way to find out.
Give it a name and it returns true or false depending on if that cell
exists.</dd>
</dl><dl><dt>cellNames</dt>
<dd>If you want to get the names of all the cells an object contains, you can
get that with cellNames. By default, cellNames will only return the names of
cells that belong to the receiver, but if an argument of true is sent to the
call, the resulting list will contain the names of all cells of all mimics
too.</dd>
</dl><div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
x<span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span>x f<span class="sy0">=</span><span class="nu0">42</span>x cellNames<span class="co1">;; return [:f]</span>x cellNames<span class="br0">(</span><span class="re6"><span class="re7">true</span></span><span class="br0">)</span><span class="co1">;; return a long list, including :f</span>
</pre></div>
</div>
<dl><dt>cells</dt>
<dd>Just like cellNames return the names of all the cells, the "cells" method
will return a Dict of all the cells with their values. And just like cellNames,
cells take an optional boolean argument on whether to include the cells of
mimics too.</dd>
</dl><div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
x<span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span>x f<span class="sy0">=</span><span class="nu0">42</span>x cells<span class="co1">;; return {f: 42}</span>x cells<span class="br0">(</span><span class="re6"><span class="re7">true</span></span><span class="br0">)</span><span class="co1">;; return a large dict, including f: 42</span>
</pre></div>
</div>
<dl><dt>mimics</dt>
<dd>Returns a list of all direct mimics of the receiver.</dd>
</dl><dl><dt>mimics?</dt>
<dd>Takes one object as argument and returns true or false depending on if the
argument is anywhere in the receiving objects mimic chain.</dd>
</dl><dl><dt>message</dt>
<dd>Takes one symbol argument and creates a new Message mimic with that
argument as its name.</dd>
</dl><dl><dt>Message code</dt>
<dd>Returns a text that describes the code this message chain represents. It
will hide some of the internal shuffling, but operators will be displayed using
canonical form.</dd>
</dl><dl><dt>Message formattedCode</dt>
<dd>Returns a text that is formatted and indented in a canonical way. This
method is used to generate the documentation code for DokGen, among other
things.</dd>
</dl><dl><dt>Message evalArgAt</dt>
<dd>Takes the index of the argument to evaluate, and the ground to evaluate it
on - returns the result of evaluating the argument.</dd>
</dl><dl><dt>Message fromText</dt>
<dd>Takes one text argument that should contain Ioke code, and returns the
parsed message chain from that code, without evaluating it.</dd>
</dl><dl><dt>Message doText</dt>
<dd>Takes one text argument that should contain Ioke code, and returns the
result of evaluating that code in the current context.</dd>
</dl><dl><dt>Message filename</dt>
<dd>Returns the filename where the receiving message was defined.</dd>
</dl><dl><dt>Message line</dt>
<dd>Returns the line number where the receiving message was defined.</dd>
</dl><dl><dt>Message position</dt>
<dd>Returns the position in the line where the receiving message was
defined.</dd>
</dl><dl><dt>Message name</dt>
<dd>Returns the name of the message. The name of the message is what you
generally talk about when saying you send a message. It can also be called the
selector in other languages.</dd>
</dl><dl><dt>Message name=</dt>
<dd>Update the message with a new name. From this point on the message will
only have that name, so doing this on a message that is part of an existing
message chain will change the behavior of that code:</dd>
</dl><div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
msg<span class="sy0">=</span><span class="re9"><span class="re11">Message</span></span>fromText<span class="br0">(</span><span class="st0">"2 + 1"</span><span class="br0">)</span>msg next name<span class="sy0">=</span><span class="st0">"-"</span>msg code<span class="co1">;; "2 -(1)"</span>
</pre></div>
</div>
<dl><dt>Message prev</dt>
<dd>Returns the prev pointer of this message, or nil if no prev pointer
exists.</dd>
</dl><dl><dt>Message prev=</dt>
<dd>Sets the prev pointer of a message. The new value should be either nil or
another message.</dd>
</dl><dl><dt>Message next</dt>
<dd>Returns the next pointer of this message, or nil if no next pointer
exists.</dd>
</dl><dl><dt>Message next=</dt>
<dd>Sets the next pointer of a message. The new value should be either nil or
another message.</dd>
</dl><dl><dt>Message sendTo</dt>
<dd>Sends a message to an object. It's important to realize that sendTo will
not evaluate the whole message chain -- it will only send one message with
arguments to an object.</dd>
</dl><dl><dt>Message keyword?</dt>
<dd>Returns true if this message is a keyword message, and false
otherwise.</dd>
</dl><p>There are many more methods that can be used to do interesting introspection
and reflection in Ioke. The reference documentation includes them all. Most of
the interesting stuff can be found on the Message kind.</p>
<dl><dt>send</dt>
<dd>In many cases you want to activate something activatable in a cell, with a
specific receiver. You can do this using send. You can send messages to most
objects. Send takes one argument that should evaluate to the name of the
message to send, and then sends along all other arguments given to send to the
new message. These arguments will remain unevaluated, and will be evaluated at
the leisure of the final method activated.</dd>
</dl><a name="Aspects"></a>
<h1><span class="mw-headline">Aspects</span></h1>
<h1><span class="mw-headline">アスペクト</span></h1>
<p>In many circumstances you might want to do several different things in a
specific method. That generally goes against good software engineering, that
says every piece of code should only have one responsibility. Aspect oriented
programming tackles this by allowing you to slice code along a different
dimension compared to the regular object oriented paradigm. Ioke has a small
version of this, that allow you to add advice to cells. This advice can be
before, after or around. All of them will get access to the arguments given in
the original message, but after-advice also gets access to the value returned
from the main cell. Finally, around-advice also gets the responsibility to
invoke the original cell, so an around-advice could choose to not invoke it at
all, or it could invoke it with different arguments, or maybe invoke it several
times.</p>
<p>Ioke currently only allows you to add or remove advice. To be able to remove
advice, you need to name it when adding it. Unnamed advice can not be removed.
Advice can be wrapped. It will be applied in an outside-in approach, where the
most recently added advice will execute first.</p>
<p>The return value of before and after advice doesn't matter, but the return
value of around-advice will be interpreted as the new return value of the
message send.</p>
<p>To manipulate advice in Ioke, you need to describe what to manipulate. This
description will return a Pointcut, that can then be used to inject advice at
that point. Pointcuts can be defined in several ways. The easiest is to define
it in terms of a cell name. Using this approach is the only way to define
advice for non-existent cells.</p>
<p>To create a Pointcut, call before, after or around on the receiver where the
Pointcut should belong. The arguments specify what should be matched by the
pointcut. You can see some examples of pointcuts here:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="co1">; matches cells foo and bar</span><span class="re9"><span class="re11">Text</span></span>before<span class="br0">(</span><span class="re12"><span class="re13">:</span>foo,</span><span class="re12"><span class="re13">:</span>bar<span class="br0">)</span></span>X<span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span><span class="co1">; will not match anything</span>X around<span class="br0">(</span>matching<span class="re13">:</span><span class="re12"><span class="re13">:</span>anyFromSelf<span class="br0">)</span></span>X foo<span class="sy0">=</span><span class="nu0">123</span><span class="co1">; will now match foo</span>X around<span class="br0">(</span>matching<span class="re13">:</span><span class="re12"><span class="re13">:</span>anyFromSelf<span class="br0">)</span></span><span class="co1">; any cell name matching the regexp</span>X after<span class="br0">(</span>matching<span class="re13">:</span><span class="sy0">#/</span>foo<span class="sy0">/</span><span class="br0">)</span><span class="co1">; matches any at all, except foo</span>X before<span class="br0">(</span>matching<span class="re13">:</span><span class="re12"><span class="re13">:</span>any,</span>except<span class="re13">:</span><span class="re12"><span class="re13">:</span>foo<span class="br0">)</span></span><span class="co1">; matches any at all, except anything that matches foo</span>X before<span class="br0">(</span>matching<span class="re13">:</span><span class="re12"><span class="re13">:</span>any,</span>except<span class="re13">:</span><span class="sy0">#/</span>foo<span class="sy0">/</span><span class="br0">)</span><span class="co1">; use a block for matching</span>X around<span class="br0">(</span>matching<span class="re13">:</span><span class="re8">fn</span><span class="br0">(</span>x, x<span class="sy0">==</span><span class="re12"><span class="re13">:</span>blurg<span class="br0">)</span><span class="br0">)</span></span><span class="co1">; use a list to provide alternatives</span>X before<span class="br0">(</span>matching<span class="re13">:</span><span class="br0">[</span><span class="sy0">#/</span>foo<span class="sy0">/</span>,<span class="sy0">#/</span>bar<span class="sy0">/</span><span class="br0">]</span><span class="br0">)</span>
</pre></div>
</div>
<p>As you can see from these examples, the pointcuts can be fairly advanced and
specific in what they match. The option to send in a block makes it possible to
check any property while matching.</p>
<p>OK, once you have a Pointcut, there are three different methods you can
call. These are <<, add, and remove!. The first one adds an unnamed
advice, the second adds a named advice and the third one removes a named
advice. Advice is any object that can be activated or called, so a method, a
block, a macro or a syntax is fine.</p>
<p>It's time to see what it looks like to add advice. Before-advice is the
easiest kind. The important thing to remember is that the code will get the
same arguments as the original call, which means it will also signal an error
if the arguments doesn't match.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
X before<span class="br0">(</span><span class="re12"><span class="re13">:</span>foo<span class="br0">)</span></span><span class="sy0"><<</span><span class="re8">method</span><span class="br0">(</span>x,<span class="st0">"got #{x}"</span>println<span class="br0">)</span>X before<span class="br0">(</span>matching<span class="re13">:</span><span class="re12"><span class="re13">:</span>anyFromSelf<span class="br0">)</span></span><span class="sy0"><<</span><span class="re8">macro</span><span class="br0">(</span><span class="st0">"called #{call message name}"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>This code doesn't do anything strange at all.</p>
<p>Next up we have after-advice. The only difference here is that after-advice
automatically gets a cell that is set to adviceResult, that can be used inside
the method.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
X after<span class="br0">(</span><span class="re12"><span class="re13">:</span>foo<span class="br0">)</span></span><span class="sy0"><<</span><span class="re8">method</span><span class="br0">(</span><span class="sy0">+</span>args,<span class="st0">"foo resulted in: #{aspectResult}"</span>println<span class="br0">)</span>
</pre></div>
</div>
<p>Remember that the result value of before and after advice doesn't count. It
is thrown away. But these methods can still affect things by side effects. They
can also be used for validation. A condition signalled inside of an advice
would have the same effect as if done in the method itself - namely
interrupting the flow of control.</p>
<p>The final advice is around advice. These are different in two ways. First,
they get access to a cell called aspectCall, which can be used to invoke the
real cell (and the next chain of advice, of course). The second difference is
that the result of the around advice will be the return value from the cell.
So, you can imagine the around-advice executing instead of the original code.
If you forget to invoke it, the original cell won't be invoked at all.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
X around<span class="br0">(</span><span class="re12"><span class="re13">:</span>non_existant<span class="br0">)</span></span><span class="sy0"><<</span><span class="re8">method</span><span class="br0">(</span><span class="nu0">42</span><span class="br0">)</span>X around<span class="br0">(</span><span class="re12"><span class="re13">:</span>foo<span class="br0">)</span></span><span class="sy0"><<</span><span class="re8">macro</span><span class="br0">(</span>arg1, arg2,<span class="st0">"before"</span>println res<span class="sy0">=</span>aspectResult<span class="br0">(</span>arg2, arg1<span class="br0">)</span><span class="st0">"got: #{res}"</span>println<span class="nu0">42</span><span class="br0">)</span>
</pre></div>
</div>
<p>The first piece of code show that you can actually use an around advice
around something that doesn't exist. But if you do call aspectCall inside of
it, that will generate a NoSuchCell condition, of course. In the second example
we first log some information, then invoke the original code with switched
argument order, saves away the result, prints the result, and finally returns
42. There you can see most of the things that can be done inside of an around
macro.</p>
<p>The aspect system in Ioke is implemented in Ioke itself, and is fairly small
at the moment. The guiding principle behind it is that it shouldn't have an
impact on code that doesn't use it. It is a highly useful feature that makes it
possible to decompose code substantially. As an example of a common place for
aspect usage is initialization. This is defined as an around-advice that looks
like this:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="re9"><span class="re11">Origin</span></span>around<span class="br0">(</span><span class="re12"><span class="re13">:</span><span class="re6">mimic</span><span class="br0">)</span></span><span class="sy0"><<</span><span class="re8">method</span><span class="br0">(</span><span class="sy0">+</span>rest,<span class="sy0">+</span><span class="re12"><span class="re13">:</span>krest,</span>newMimic<span class="sy0">=</span>aspectCall if<span class="br0">(</span>newMimic cell?<span class="br0">(</span><span class="re12"><span class="re13">:</span>initialize<span class="br0">)</span>,</span>newMimic initialize<span class="br0">(</span><span class="sy0">*</span>rest,<span class="sy0">*</span>krest<span class="br0">)</span><span class="br0">)</span>newMimic<span class="br0">)</span>
</pre></div>
</div>
<p>Note first that the around advice takes any kind of arguments, but doesn't
send them along to mimic. Instead it checks if there is an initialize-cell, and
in that case invokes it with the arguments given to the mimic call. It finally
returns the original result.</p>
<a name="Importing"></a>
<h1><span class="mw-headline">Importing</span></h1>
<h1><span class="mw-headline">外部コードの利用</span></h1>
<p>To import new code into Ioke, the method<code>use</code>should be used. The
terminology is that you give "use" a name of a module to include, and if that
module has already been included it will not be evaluated again. If it has not
been included,<code>use</code>will try to find the module using several
different heuristics. It will add a<tt>.ik</tt>to the name and try to look up a
file of that name - but it will also try to look it up without a<tt>.ik</tt>,
if a full file name has been given. Several different places will be searched,
and the exact order and what will be searched can be found by calling
the<code>System loadPath</code>method. This will return a list of all the
places that Ioke uses to search for modules. This list can be modified to add
more directories to the load path at runtime.</p>
<p>If a module of the specified name can't be found, a condition will be
signalled.</p>
<a name="Core_kinds"></a>
<h1><span class="mw-headline">Core kinds</span></h1>
<h1><span class="mw-headline">よく使うkind</span></h1>
<p>Ioke obviously contains lots of different data types, but there are some
that are much more important than others. In this chapter I'll take a look at
these and talk about how to work with them correctly.</p>
<a name="Conditions"></a>
<h2><span class="mw-headline">Conditions</span></h2>
<p>One of the major parts of Ioke is the condition system. Unlike most other
programming languages, Ioke doesn't have exceptions. Instead it has conditions,
where errors are a specific kind of condition. The condition system comprises
several different things. Specifically, the condition system uses the kinds
Condition, Restart, Handler and Rescue. Restarts are mostly orthogonal to the
rest of the system.</p>
<p>The way the condition system works is this. When something happens, a
program can elect to signal a condition. This can be done using "signal!",
"warn!" or "error!". Both "warn!" and "error!" use "signal!" under the covers,
but do some other things as well. A condition will always mimic Condition. Each
of these three methods can be called in three different ways. First, you can
call them with a text argument. In that case the signalled condition will be
the default for that type. (The default for "signal!" is Condition Default. The
default for "warn!" is Condition Warning Default and the default for "error!"
is Condition Error Default.) A new mimic of the default condition will be
created, and a cell called text will be set to the text argument. The second
variation is to give an instance of an existing condition to one of the
methods. In that case that condition will be signalled unmodified. Finally, the
third version gives a condition mimic and one or more keyword arguments with
data to set on that condition. In that case a mimic of the condition will be
created, and then cells with data set based on the arguments.</p>
<p>If a signal is not handled, nothing happens.</p>
<p>If a warning is not handled, a message will be printed with the text of that
warning.</p>
<p>If an error is not handled, the debugger will be invoked - if a debugger is
available. Otherwise the program will be terminated.</p>
<p>A Rescue allows conditions to unwind the stack to the place where the rescue
is established. Combining rescues and conditions looks a lot like regular
exception handling in other programming languages.</p>
<p>A Handler on the other hand will run code in the dynamic context of the
place where the condition was signalled. A handler can invoke restarts to
handle an error state at the place it happened, and as such doesn't have to
actually unwind the stack anywhere. Any number of handlers can run - the last
handler to run will be either the last handler, the handler that activates a
restart, or the last handler before a valid rescue for that condition.</p>
<p>A restart is a way to allow ways of getting back to a valid state. Take the
example of referring to a cell that doesn't exist. Before signalling a
condition, Ioke will set up restarts so you can provide a value to use in the
case a cell doesn't exist. This restart will use that new value and continue
execution at the point where it would otherwise have failed.</p>
<p>A restart can have a name. If it doesn't have a name it can only be used
interactively. You can use findRestart to get hold of the closest restart with
a given name. You can invoke a given restart with invokeRestart, which takes
either the name of a restart or a restart mimic. Finally, you can get all
available restarts using availableRestarts.</p>
<p>Both handlers, rescues and restarts are established inside a call to the
bind macro. All arguments to this macro need to be either handlers, rescues or
restarts, except for the last argument which should be the code to execute.</p>
<p>You create a new handler by calling the method "handle". You create a new
rescue by calling the method "rescue". You create a new restart by calling the
method "restart". These all take funky arguments, so refer to the reference to
better understand how they work.</p>
<p>This small example doesn't necessarily show the power of conditions, but it
can give an idea about how it works.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="co1">;; to handle any problem</span>bind<span class="br0">(</span>rescue<span class="br0">(</span><span class="re8">fn</span><span class="br0">(</span>c,<span class="re6"><span class="re7">nil</span></span><span class="br0">)</span><span class="br0">)</span>,<span class="co1">;; do nothing in the rescue</span>error!<span class="br0">(</span><span class="st0">"This is bad!!"</span><span class="br0">)</span><span class="br0">)</span><span class="co1">;; to print all conditions happening, but not do anything</span>bind<span class="br0">(</span>handle<span class="br0">(</span><span class="re8">fn</span><span class="br0">(</span>c, c println<span class="br0">)</span><span class="br0">)</span>, signal!<span class="br0">(</span><span class="st0">"something"</span><span class="br0">)</span>signal!<span class="br0">(</span><span class="st0">"something more"</span><span class="br0">)</span>warn!<span class="br0">(</span><span class="st0">"A warning!!"</span><span class="br0">)</span><span class="br0">)</span><span class="co1">;; rescue either of two conditions</span>C1<span class="sy0">=</span><span class="re9"><span class="re11">Condition</span></span><span class="re11">Error</span><span class="re6">mimic</span>C2<span class="sy0">=</span><span class="re9"><span class="re11">Condition</span></span><span class="re11">Error</span><span class="re6">mimic</span>bind<span class="br0">(</span>rescue<span class="br0">(</span>C1, C2,<span class="re8">fn</span><span class="br0">(</span>c,<span class="st0">"got an error: #{c}"</span>println<span class="br0">)</span><span class="br0">)</span>, error!<span class="br0">(</span>C1<span class="br0">)</span><span class="br0">)</span><span class="co1">;; invoke a restart when no such cell is signaled</span>bind<span class="br0">(</span>handle<span class="br0">(</span><span class="re9"><span class="re11">Condition</span></span><span class="re11">Error</span><span class="re11">No</span>SuchCell,<span class="re8">fn</span><span class="br0">(</span>c, invokeRestart<span class="br0">(</span><span class="re12"><span class="re13">:</span>useValue,</span><span class="nu0">42</span><span class="br0">)</span><span class="br0">)</span><span class="br0">)</span>, blarg println<span class="br0">)</span><span class="co1">;; will print 42</span><span class="co1">;; establish a restart</span>bind<span class="br0">(</span>restart<span class="br0">(</span>something,<span class="re8">fn</span><span class="br0">(</span><span class="sy0">+</span>args, args println<span class="br0">)</span><span class="br0">)</span>, invokeRestart<span class="br0">(</span><span class="re12"><span class="re13">:</span>something,</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">)</span><span class="br0">)</span>
</pre></div>
</div>
<p>The code above shows several different things you can do with the condition
system. It is a very powerful system, so I recommend trying to understand it.
It lies at the core of many things in Ioke, and some parts will not make sense
without a deep understanding of conditions. For more information on what such a
system is capable of, look for documentation about the Common Lisp condition
system, which has been a heavy influence on Ioke. Also, the debugger in IIk
uses the condition system to implement its functionality.</p>
<p>There are many conditions defined in the core of Ioke, and they are used by
the implementation to signal error conditions of different kinds. Refer to the
reference to see which conditions are available.</p>
<p>Finally, one thing that you might miss if you're used to exceptions in other
languages, is a construct that makes it possible to ensure that code gets
executed, even if a non-local flow control happens. Don't despair, Ioke has
one. It is called ensure, and works mostly like ensure in Ruby, and finally in
Java. It takes one main code argument, followed by zero or more arguments that
contain the code to always make sure executes. It looks like this:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
ensure<span class="br0">(</span>conn<span class="sy0">=</span><span class="re11">Database</span>open conn SELECT<span class="sy0">*</span>FROM a_table, conn close!, conn reallyClose!, conn reallyReallyReallyClose!<span class="br0">)</span>
</pre></div>
</div>
<p>This code uses a hypothetical database library, opens up a connection, does
something, and then in three different ensure blocks tries to ensure that it
really is closed afterwards. The return value of the ensure block will still be
the return value of the last expression in the main code. Non local flow
control can happen inside of the ensure block, but exactly what will happen is
undefined -- so avoid it, please.</p>
<a name="Text_2"></a>
<h2><span class="mw-headline">Text</span></h2>
<p>In Ioke, the equivalent of Strings in other languages are called Text. This
better describes the purpose of the type. Ioke Text is immutable. All
operations that would change the text returns a new object instead. If you are
used to Java strings or Ruby strings, then most operations available on Ioke
Texts will not come as a surprise.</p>
<p>To create a new Text, you use the literal syntax as described in the syntax
chapter. You can use interpolation to include dynamic data.</p>
<p>You can do several things with Ioke text. These examples show some of the
methods:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="co1">;; repeat a text several times</span><span class="st0">"foo"</span><span class="sy0">*</span><span class="nu0">3</span><span class="co1">;; => "foofoofoo"</span><span class="co1">;; concatenate two texts</span><span class="st0">"foo"</span><span class="sy0">+</span><span class="st0">"bar"</span><span class="co1">;; => "foobar"</span><span class="co1">;; get the character at a specific index</span><span class="st0">"foo"</span><span class="br0">[</span><span class="nu0">1</span><span class="br0">]</span><span class="co1">;; => 111</span><span class="co1">;; get a subset of text</span><span class="st0">"foo"</span><span class="br0">[</span>1<span class="sy0">..</span>1<span class="br0">]</span><span class="co1">;; => "o"</span><span class="st0">"foo"</span><span class="br0">[</span>0<span class="sy0">..</span>1<span class="br0">]</span><span class="co1">;; => "fo"</span><span class="st0">"foo"</span><span class="br0">[</span>0<span class="sy0">...</span>1<span class="br0">]</span><span class="co1">;; => "f"</span><span class="st0">"foxtrot"</span><span class="br0">[</span>1<span class="sy0">..</span><span class="re0">-</span><span class="nu0">1</span><span class="br0">]</span><span class="co1">;; => "oxtrot"</span><span class="st0">"foxtrot"</span><span class="br0">[</span>1<span class="sy0">...</span><span class="re0">-</span><span class="nu0">1</span><span class="br0">]</span><span class="co1">;; => "oxtro"</span><span class="co1">;; is a text empty?</span><span class="st0">"foo"</span>empty?<span class="co1">;; => false</span><span class="st0">""</span>empty?<span class="co1">;; => true</span><span class="co1">;; the length of the text</span><span class="st0">"foo"</span>length<span class="co1">;; => 3</span><span class="st0">""</span>length<span class="co1">;; => 0</span><span class="co1">;; replace the first occurrence of something with something else</span><span class="st0">"hello fox fob folk"</span>replace<span class="br0">(</span><span class="st0">"fo"</span>,<span class="st0">"ba"</span><span class="br0">)</span><span class="co1">;; => "hello bax fob folk"</span><span class="co1">;; replace all occurrences of something with something else</span><span class="st0">"hello fox fob folk"</span>replaceAll<span class="br0">(</span><span class="st0">"fo"</span>,<span class="st0">"ba"</span><span class="br0">)</span><span class="co1">;; => "hello bax bab balk"</span><span class="co1">;; split around a text</span><span class="st0">"foo bar bax"</span>split<span class="br0">(</span><span class="st0">" "</span><span class="br0">)</span><span class="co1">;; => ["foo", "bar", "bax"]</span>
</pre></div>
</div>
<p>The Text kind contains lots of useful functionality like this. The purpose
is to make it really easy to massage text of any kind.</p>
<p>One important tool for doing that is the "format" method. This is a mix
between C printf and Common Lisp format. At the moment, it only contains a
small amount of functionality, but it can still be very convenient.
Specifically you can print each element in a list directly by using format,
instead of concatenating text yourself.</p>
<p>The "format" method takes format specifiers that begin with %, and then
inserts one of its arguments in different ways depending on what kind of format
specifier is used.</p>
<p>Some examples of format follow:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="co1">;; insert simple value as text</span><span class="st0">"%s"</span>format<span class="br0">(</span><span class="nu0">123</span><span class="br0">)</span><span class="co1">;; => "123"</span><span class="co1">;; insert value right justified by 6</span><span class="st0">"%6s"</span>format<span class="br0">(</span><span class="nu0">123</span><span class="br0">)</span><span class="co1">;; => " 123"</span><span class="co1">;; insert value left justified by 6</span><span class="st0">"%-6s"</span>format<span class="br0">(</span><span class="nu0">123</span><span class="br0">)</span><span class="co1">;; => "123 "</span><span class="co1">;; insert two values</span><span class="st0">"%s: %s"</span>format<span class="br0">(</span><span class="nu0">123</span>,<span class="nu0">321</span><span class="br0">)</span><span class="co1">;; => "123: 321"</span><span class="co1">;; insert a list of values formatted the same</span><span class="st0">"%[%s, %]<span class="es0">\n</span>"</span>format<span class="br0">(</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">]</span><span class="br0">)</span><span class="co1">;; => "1, 2, 3, \n"</span><span class="co1">;; insert a dict of values formatted the same</span><span class="st0">"%:[%s => %s, %]<span class="es0">\n</span>"</span>format<span class="br0">(</span><span class="br0">{</span>sam<span class="re13">:</span><span class="nu0">3</span>, toddy<span class="re13">:</span><span class="nu0">10</span><span class="br0">}</span><span class="br0">)</span><span class="co1">;; => "sam => 3, toddy => 10, \n"</span><span class="co1">;; insert splatted values from a list</span><span class="st0">"wow: %*[%s: %s %]"</span>format<span class="br0">(</span><span class="br0">[</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span><span class="br0">]</span>,<span class="br0">[</span><span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">]</span>,<span class="br0">[</span><span class="nu0">3</span>,<span class="nu0">4</span><span class="br0">]</span><span class="br0">]</span><span class="br0">)</span><span class="co1">;; => "wow: 1: 2 2: 3 3: 4 "</span>
</pre></div>
</div>
<a name="Numbers"></a>
<h2><span class="mw-headline">Numbers</span></h2>
<p>As mentioned in the section on syntax, Ioke supports decimal numbers,
integers and ratios. A Ratio will be created when two integers can't be divided
evenly. A Ratio will always use the GCD. In most cases Ratios, Decimals and
Integers can interact with each other as would be expected. The one thing that
might surprise people is that Ioke doesn't have any inexact floating point data
type. Instead, decimals are exact and can have any size. This means they are
well suited to represent such things as money, since operations will always
have well defined results.</p>
<p>All expected math works fine on Ioke numbers. The reference for numbers more
closely specify what is possible. One thing to notice is that the % operator
implements modulus, not remainder. This might be unintuitive for some
developers. What that means is that it is not an error to ask for the modulus
of 0: "13 % 0", since there is no division necessary in this operation.</p>
<p>In addition to the above, Integers have the "times" method described
earlier. It can also return the successor and predecessor of itself with the
"pred" and "succ" methods.</p>
<a name="Lists"></a>
<h2><span class="mw-headline">Lists</span></h2>
<p>Ioke has lists that expand to the size needed. These lists can be created
using a simple literal syntax. They can contain any kind of element, including
itself (although don't try to print such a list). Ioke List mixes in the
Enumerable mixin, which gives it quite powerful capabilities.</p>
<p>A list can be created using the "list" or "[]" methods:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="co1">;; an empty list</span><span class="br0">[</span><span class="br0">]</span><span class="co1">;; the same list created in two different ways</span>list<span class="br0">(</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">)</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">]</span><span class="co1">;; a list with different elements</span><span class="br0">[</span><span class="nu0">1</span>,<span class="st0">"one"</span>,<span class="re12"><span class="re13">:</span>one<span class="br0">]</span></span>
</pre></div>
</div>
<p>Except for the Enumerable methods, List also defines many other methods that
can be highly useful. Some examples are shown below:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
l<span class="sy0">=</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">]</span><span class="co1">;; add two lists together</span>l<span class="sy0">+</span>l<span class="co1">;; => [1, 2, 3, 1, 2, 3]</span><span class="co1">;; return the difference of two lists</span>l<span class="sy0">-</span><span class="br0">[</span><span class="nu0">2</span><span class="br0">]</span><span class="co1">;; => [1, 3]</span><span class="co1">;; add a new value to a list</span>l<span class="sy0"><<</span><span class="nu0">42</span>l<span class="sy0">==</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">42</span><span class="br0">]</span><span class="co1">;; => true</span><span class="co1">;; get a specific element from the list</span>l<span class="br0">[</span><span class="nu0">0</span><span class="br0">]</span><span class="co1">;; => 1</span><span class="co1">;; -1 returns the last, -2 the next to last</span>l<span class="br0">[</span><span class="re0">-</span><span class="nu0">1</span><span class="br0">]</span><span class="co1">;; => 42</span><span class="co1">;; an index outside the boundaries return nil</span>l<span class="br0">[</span><span class="nu0">10</span><span class="br0">]</span><span class="co1">;; => nil</span><span class="co1">;; assign a new value</span>l<span class="br0">[</span><span class="nu0">3</span><span class="br0">]</span><span class="sy0">=</span><span class="nu0">40</span>l<span class="sy0">==</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">40</span><span class="br0">]</span><span class="co1">;; => true</span>l<span class="br0">[</span><span class="re0">-</span><span class="nu0">1</span><span class="br0">]</span><span class="sy0">=</span><span class="nu0">39</span>l<span class="sy0">==</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">39</span><span class="br0">]</span><span class="co1">;; => true</span><span class="co1">;; assign an out of bounds value</span>l<span class="br0">[</span><span class="nu0">10</span><span class="br0">]</span><span class="sy0">=</span><span class="nu0">13</span>l<span class="sy0">==</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">39</span>,<span class="re6"><span class="re7">nil</span></span>,<span class="re6"><span class="re7">nil</span></span>,<span class="re6"><span class="re7">nil</span></span>,<span class="re6"><span class="re7">nil</span></span>,<span class="re6"><span class="re7">nil</span></span>,<span class="re6"><span class="re7">nil</span></span>,<span class="nu0">13</span><span class="br0">]</span><span class="co1">;; => true</span><span class="co1">;; at and at= is the same as [] and []=</span>l at<span class="br0">(</span><span class="nu0">0</span><span class="br0">)</span><span class="co1">;; => 1</span><span class="co1">;; empty the list</span>l clear! l<span class="sy0">==</span><span class="br0">[</span><span class="br0">]</span><span class="co1">;; => true</span><span class="co1">;; follows the each protocol</span>l each<span class="br0">(</span>println<span class="br0">)</span><span class="co1">;; is empty?</span>l empty?<span class="co1">;; => true</span><span class="co1">;; does it include an element?</span>l include?<span class="br0">(</span><span class="re12"><span class="re13">:</span>foo<span class="br0">)</span></span><span class="co1">;; => false</span><span class="co1">;; the last element</span>l last<span class="co1">;; => nil</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span><span class="br0">]</span>last<span class="co1">;; => 2</span><span class="co1">;; the length</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span><span class="br0">]</span>length<span class="co1">;; => 2</span><span class="co1">;; first value</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span><span class="br0">]</span>first<span class="co1">;; => 1</span><span class="co1">;; rest except for first</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">]</span>rest<span class="co1">;; => [2, 3]</span><span class="co1">;; returns a new sorted list</span><span class="br0">[</span><span class="nu0">3</span>,<span class="nu0">2</span>,<span class="nu0">1</span><span class="br0">]</span>sort<span class="co1">;; => [1, 2, 3]</span><span class="co1">;; sorts in place</span>l<span class="sy0">=</span><span class="br0">[</span><span class="nu0">3</span>,<span class="nu0">2</span>,<span class="nu0">1</span><span class="br0">]</span>l sort! l<span class="sy0">==</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span><span class="br0">]</span><span class="co1">;; => true</span>
</pre></div>
</div>
<a name="Dicts"></a>
<h2><span class="mw-headline">Dicts</span></h2>
<p>A Dict is a dictionary of key-value mappings. The mappings are unordered,
and there can only ever be one key with the same value. Any kind of Ioke object
can be used as a key. There is no problem with having the same value for
different keys. The default implementation of Dict uses a hash-based
implementation. That's not necessarily always true for all dicts. The iteration
order is not necessarily stable either, so don't write code that depends on
it.</p>
<p>Creating a dict is done using either the "dict" or the "{}" methods. Both of
these expect either keyword arguments or mimics of Pair. If keyword arguments,
these keywords will be used as symbol keys. That's the most common thing, so it
makes sense to have that happen automatically. Dicts also try to print
themselves that way.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
dict<span class="br0">(</span><span class="nu0">1</span><span class="sy0">=></span><span class="nu0">2</span>,<span class="nu0">3</span><span class="sy0">=></span><span class="nu0">4</span><span class="br0">)</span><span class="co1">;; these two are the same</span>dict<span class="br0">(</span>foo<span class="re13">:</span><span class="st0">"bar"</span>, baaz<span class="re13">:</span><span class="st0">"quux"</span><span class="br0">)</span>dict<span class="br0">(</span><span class="re12"><span class="re13">:</span>foo</span><span class="sy0">=></span><span class="st0">"bar"</span>,<span class="re12"><span class="re13">:</span>baaz</span><span class="sy0">=></span><span class="st0">"quux"</span><span class="br0">)</span><span class="br0">{</span><span class="nu0">1</span><span class="sy0">=></span><span class="nu0">2</span>,<span class="nu0">3</span><span class="sy0">=></span><span class="nu0">4</span><span class="br0">}</span><span class="co1">;; these two are the same</span><span class="br0">{</span>foo<span class="re13">:</span><span class="st0">"bar"</span>, baaz<span class="re13">:</span><span class="st0">"quux"</span><span class="br0">}</span><span class="br0">{</span><span class="re12"><span class="re13">:</span>foo</span><span class="sy0">=></span><span class="st0">"bar"</span>,<span class="re12"><span class="re13">:</span>baaz</span><span class="sy0">=></span><span class="st0">"quux"</span><span class="br0">}</span><span class="co1">;; the formats can be combined:</span><span class="br0">{</span><span class="nu0">1</span><span class="sy0">=></span><span class="nu0">2</span>, foo<span class="re13">:</span><span class="nu0">42</span>,<span class="st0">"bar"</span><span class="sy0">=></span><span class="st0">"qux"</span><span class="br0">}</span>
</pre></div>
</div>
<p>The literal Pair syntax (using =>) will not necessarily instantiate real
pairs for this.</p>
<p>Dicts mix in Enumerable. When using each, what will be yielded are mimics of
Pair, where the first value will be the key and the second will be value. Just
like Lists, Dicts have several useful methods in themselves:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
d<span class="sy0">=</span><span class="br0">{</span>one<span class="re13">:</span><span class="st0">"two"</span>,<span class="nu0">3</span><span class="sy0">=></span><span class="nu0">4</span><span class="br0">}</span><span class="co1">;; lookup with [], "at" works the same</span>d<span class="br0">[</span><span class="re12"><span class="re13">:</span>one<span class="br0">]</span></span><span class="co1">;; => "two"</span>d<span class="br0">[</span><span class="re12"><span class="re13">:</span>two<span class="br0">]</span></span><span class="co1">;; => nil</span>d<span class="br0">[</span><span class="nu0">3</span><span class="br0">]</span><span class="co1">;; => 4</span>d<span class="br0">[</span><span class="nu0">4</span><span class="br0">]</span><span class="co1">;; => nil</span><span class="co1">;; assign values with []=</span>d<span class="br0">[</span><span class="re12"><span class="re13">:</span>one<span class="br0">]</span></span><span class="sy0">=</span><span class="st0">"three"</span>d<span class="br0">[</span><span class="re12"><span class="re13">:</span>new<span class="br0">]</span></span><span class="sy0">=</span><span class="st0">"wow!"</span>d<span class="sy0">==</span><span class="br0">{</span>one<span class="re13">:</span><span class="st0">"three"</span>,<span class="nu0">3</span><span class="sy0">=></span><span class="nu0">4</span>, new<span class="re13">:</span><span class="st0">"wow!"</span><span class="br0">}</span><span class="co1">;; iterate over it</span>d each<span class="br0">(</span>value println<span class="br0">)</span><span class="co1">;; get all keys</span>d keys<span class="sy0">==</span>set<span class="br0">(</span><span class="re12"><span class="re13">:</span>one,</span><span class="re12"><span class="re13">:</span>new,</span><span class="nu0">3</span><span class="br0">)</span>
</pre></div>
</div>
<a name="Sets"></a>
<h4><span class="mw-headline">Sets</span></h4>
<p>If you want an object that work like a mathematical set, Ioke provides such
a kind for you. There is no support for literal syntax for sets, but you can
create new with the set method. A set can be iterated over and it is
Enumerable. You can add and remove elements, and check for membership.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
x<span class="sy0">=</span>set<span class="br0">(</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">3</span>,<span class="nu0">2</span>,<span class="nu0">1</span><span class="br0">)</span>x map<span class="br0">(</span><span class="sy0">*</span><span class="nu0">2</span><span class="br0">)</span>sort<span class="co1">; => [2, 4, 6]</span>x<span class="sy0">===</span><span class="nu0">1</span><span class="co1">; => true</span>x<span class="sy0">===</span><span class="nu0">0</span><span class="co1">; => false</span>x remove!<span class="br0">(</span><span class="nu0">2</span><span class="br0">)</span>x<span class="sy0">===</span><span class="nu0">2</span><span class="co1">; => false</span>x<span class="sy0"><<</span><span class="nu0">4</span>x<span class="sy0">===</span><span class="nu0">4</span><span class="co1">; => true</span>
</pre></div>
</div>
<a name="Ranges_and_Pairs"></a>
<h4><span class="mw-headline">Ranges and Pairs</span></h4>
<p>Both ranges and pairs tie two values together. They also have literal syntax
to create them, since they are very useful in many circumstances.</p>
<p>A Range defines two endpoints. A Range is Enumerable and you can also check
for membership. It's also convenient to send Ranges to the "List []" method. A
Range can be exclusive or inclusive. If it's inclusive it includes the end
value, and if it is exclusive it doesn't.</p>
<p>An addition to Ioke S is the possibility of inverted ranges. If the first
value is larger than the second value, then the range is inverted. This puts
slightly different demands on the objects inside of it. Specifically, if you
want to iterate over the elements, the kind you're using need to have a method
called 'pred' for predecessor, instead of 'succ' for successor. Membership can
still be tested, as long as <=> is defined. So you can do something like
this: ("foo".."aoo") === "boo". It's mostly useful for iterating in the
opposite direction, like with 10..1, for example.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="co1">;; literal syntax for inclusive range</span>1<span class="sy0">..</span>10<span class="co1">;; literal syntax for exclusive range</span>1<span class="sy0">...</span>10<span class="co1">;; check for membership</span><span class="br0">(</span>1<span class="sy0">..</span>10<span class="br0">)</span><span class="sy0">===</span><span class="nu0">5</span><span class="co1">;; => true</span><span class="br0">(</span>1<span class="sy0">..</span>10<span class="br0">)</span><span class="sy0">===</span><span class="nu0">10</span><span class="co1">;; => true</span><span class="br0">(</span>1<span class="sy0">..</span>10<span class="br0">)</span><span class="sy0">===</span><span class="nu0">11</span><span class="co1">;; => false</span><span class="br0">(</span>1<span class="sy0">...</span>10<span class="br0">)</span><span class="sy0">===</span><span class="nu0">5</span><span class="co1">;; => true</span><span class="br0">(</span>1<span class="sy0">...</span>10<span class="br0">)</span><span class="sy0">===</span><span class="nu0">10</span><span class="co1">;; => false</span><span class="br0">(</span>1<span class="sy0">...</span>10<span class="br0">)</span><span class="sy0">===</span><span class="nu0">11</span><span class="co1">;; => false</span><span class="co1">;; get the from value</span><span class="br0">(</span>1<span class="sy0">..</span>10<span class="br0">)</span>from<span class="sy0">==</span><span class="nu0">1</span><span class="co1">;; => true</span><span class="br0">(</span>1<span class="sy0">...</span>10<span class="br0">)</span>from<span class="sy0">==</span><span class="nu0">1</span><span class="co1">;; => true</span><span class="co1">;; get the to value</span><span class="br0">(</span>1<span class="sy0">..</span>10<span class="br0">)</span>to<span class="sy0">==</span><span class="nu0">10</span><span class="co1">;; => true</span><span class="br0">(</span>1<span class="sy0">...</span>10<span class="br0">)</span>to<span class="sy0">==</span><span class="nu0">10</span><span class="co1">;; => true</span><span class="co1">;; is this range exclusive?</span><span class="br0">(</span>1<span class="sy0">..</span>10<span class="br0">)</span>exclusive?<span class="co1">;; => false</span><span class="br0">(</span>1<span class="sy0">...</span>10<span class="br0">)</span>exclusive?<span class="co1">;; => true</span><span class="co1">;; is this range inclusive?</span><span class="br0">(</span>1<span class="sy0">..</span>10<span class="br0">)</span>inclusive?<span class="co1">;; => true</span><span class="br0">(</span>1<span class="sy0">...</span>10<span class="br0">)</span>inclusive?<span class="co1">;; => false</span>
</pre></div>
</div>
<p>A Pair represents a combination of two values. They don't have to be of the
same kind. They can have any kind of relationship. Since Pairs are often used
to represent the elements of Dicts, it is very useful to refer to the first
value as the "key", and the second value as the "value".</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="co1">;; literal syntax for a pair</span><span class="st0">"foo"</span><span class="sy0">=></span><span class="st0">"bar"</span><span class="co1">;; getting the first value</span><span class="br0">(</span><span class="st0">"foo"</span><span class="sy0">=></span><span class="st0">"bar"</span><span class="br0">)</span>first<span class="co1">;; => "foo"</span><span class="br0">(</span><span class="st0">"foo"</span><span class="sy0">=></span><span class="st0">"bar"</span><span class="br0">)</span>key<span class="co1">;; => "foo"</span><span class="co1">;; getting the second value</span><span class="br0">(</span><span class="st0">"foo"</span><span class="sy0">=></span><span class="st0">"bar"</span><span class="br0">)</span>second<span class="co1">;; => "bar"</span><span class="br0">(</span><span class="st0">"foo"</span><span class="sy0">=></span><span class="st0">"bar"</span><span class="br0">)</span>value<span class="co1">;; => "bar"</span>
</pre></div>
</div>
<a name="Enumerable"></a>
<h2><span class="mw-headline">Enumerable</span></h2>
<p>One of the most important mixins in Ioke is Mixins Enumerable - the place
where most of the collection functionality is available. The contract for any
kind that wants to be Enumerable is that it should implement each in the manner
described earlier. If it does that it can mixin Enumerable and get access to
all the methods defined in it. I'm not going to show all the available methods,
but just a few useful examples here. Note that any method name that ends with
Fn takes a block instead of a raw message chain.</p>
<p>Almost all methods in Enumerable take variable amounts of arguments and do
different things depending on how many arguments are provided. The general rule
is that if there is only one argument, it should be a message chain, and if
there are two or more arguments the last one should be code, and the rest
should be names of arguments to use in that code.</p>
<p>Mapping a collection into a another collection can be done using map or
mapFn. These are aliased as collect and collectFn too.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
l<span class="sy0">=</span><span class="br0">[</span><span class="nu0">10</span>,<span class="nu0">20</span>,<span class="nu0">30</span>,<span class="nu0">40</span><span class="br0">]</span><span class="co1">;; mapping into text</span>l map<span class="br0">(</span>asText<span class="br0">)</span><span class="co1">;; => ["10", "20", "30", "40"]</span>l map<span class="br0">(</span>n, n asText<span class="br0">)</span><span class="co1">;; => ["10", "20", "30", "40"]</span><span class="co1">;; exponentiation</span>l map<span class="br0">(</span><span class="sy0">**</span><span class="nu0">2</span><span class="br0">)</span><span class="co1">;; => [100, 400, 900, 1600]</span>l map<span class="br0">(</span>n, n<span class="sy0">*</span>n<span class="br0">)</span><span class="co1">;; => [100, 400, 900, 1600]</span>
</pre></div>
</div>
<p>Filtering the contents of a collection can be done using select, which is
aliased as filter and findAll.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="co1">;; with no arguments, return all true things</span><span class="br0">[</span><span class="re6"><span class="re7">nil</span></span>,<span class="re6"><span class="re7">false</span></span>,<span class="nu0">13</span>,<span class="nu0">42</span><span class="br0">]</span>select<span class="co1">;; => [13, 42]</span>l<span class="sy0">=</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span>,<span class="nu0">5</span>,<span class="nu0">6</span><span class="br0">]</span><span class="co1">;; all elements over 3</span>l select<span class="br0">(</span><span class="sy0">></span><span class="nu0">3</span><span class="br0">)</span><span class="co1">;; => [4, 5, 6]</span>l select<span class="br0">(</span>n, n<span class="sy0">></span><span class="nu0">3</span><span class="br0">)</span><span class="co1">;; => [4, 5, 6]</span>
</pre></div>
</div>
<p>A very common operation is to create one object based on the contents of a
collection. This operation has different names in different languages. In Ioke
it is called inject, but it is aliased as reduce and fold.</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
l<span class="sy0">=</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span>,<span class="nu0">5</span><span class="br0">]</span><span class="co1">;; inject around a message chain</span>l inject<span class="br0">(</span><span class="sy0">+</span><span class="br0">)</span><span class="co1">;; => 15</span>l inject<span class="br0">(</span><span class="sy0">*</span><span class="br0">)</span><span class="co1">;; => 120</span><span class="co1">;; with one arg</span>l inject<span class="br0">(</span>n,<span class="sy0">*</span>n<span class="br0">)</span><span class="co1">;; => 120</span>l inject<span class="br0">(</span>n,<span class="re5">+</span>n<span class="sy0">*</span><span class="nu0">2</span><span class="br0">)</span><span class="co1">;; => 29</span><span class="co1">;; with two args</span>l inject<span class="br0">(</span>sum, n, sum<span class="sy0">*</span>n<span class="br0">)</span><span class="co1">;; => 120</span>l inject<span class="br0">(</span>sum, n, sum<span class="sy0">*</span><span class="nu0">2</span><span class="sy0">+</span>n<span class="sy0">*</span><span class="nu0">3</span><span class="br0">)</span><span class="co1">;; => 139</span><span class="co1">;; with three args</span>l inject<span class="br0">(</span><span class="nu0">1</span>, sum, n, sum<span class="sy0">*</span>n<span class="br0">)</span><span class="co1">;; => 120</span>l inject<span class="br0">(</span><span class="nu0">10</span>, sum, n, sum<span class="sy0">*</span>n<span class="br0">)</span><span class="co1">;; => 1200</span>
</pre></div>
</div>
<a name="Regexps"></a>
<h2><span class="mw-headline">Regexps</span></h2>
<p>Regular expressions allow the matching of text against an abstract pattern.
Ioke uses the JRegex engine to implement regular expressions. This means Ioke
supports quite advanced expressions. Exactly what kind of regular expression
syntax is supported can be found at<a href="http://jregex.sf.net" class="external free" title="http://jregex.sf.net">http://jregex.sf.net</a>. This
section will describe how you interact with regular expressions from Ioke.</p>
<p>There are two kinds that are used when working with regular expression.
First, Regexp, which represents an actual pattern. The second is Regexp Match,
which contains information about a regular expression match. It is this match
that can be used to extract most information about where and how a complicated
expression matched.</p>
<p>The standard way of matching something is with the match method. This method
is aliased as =~, which is the idiomatic usage. It takes anything that can be
converted to a text and returns nil if it fails to match anything, or a Regexp
Match if it matches.</p>
<p>You can create a new Regexp from a text by using the Regexp from method. You
can quote all meta characters in a text by using the Regexp quote method.
Finally, if you just want to get all the text pieces that match for a regular
expression, you can use Regexp allMatches. It takes a text and returns a list
of all the text pieces where the Regexp matched.</p>
<p>You can also investigate a Regexp, by asking for its pattern (the pattern
method), its flags (the flag method), and the named groups it defines. The
names of the named groups can be inspected with the names method.</p>
<p>A Regexp Match is specific to one specific match. You will always get a new
one every time you try to match against something. A match has a target, which
is the original text the regular expression was matched against. So if I do #/
.. / =~ "abc fo bar", then the whole "abc fo bar" is the target. You get the
target from a match by using the target method. A match can also be asked for
the named groups the regular expression it was matched against support. This is
also done with the names method. Match also has two methods beforeMatch and
afterMatch, that returns the text before and after the match. The match method
returns the text comprising the actual match. The captures method will return a
list of all the captured groups in this match. The asList method returns the
same things as captures, except it also includes the full match text.</p>
<p>To figure out the indices where groups start or end, you can use the start
or end methods. These take an optional index that defaults to zero, where group
zero is the full match. They can also take a text or symbol that should be the
name of a named group. The offset method returns a pair of the beginning and
end offset of the group asked for. It works the same as start and end, with
regards to what argument it takes.</p>
<p>You can use the [] method on Match to extract the one or several pieces of
matches. If m is a match, then all of these are valid expressions: m[0].
m[1..3]. m[:foo]. m[-2], where the ranges return several groups, and the
negative index returns indexed from the end of the list of captures.</p>
<p>Finally, a Regexp Match implements pass. It does this in such a way that if
you use named groups, you can extract the value for that group by calling a
method named the same as that group name. An example of this:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
number<span class="sy0">=</span><span class="st0">"555-12345"</span>m<span class="sy0">=</span><span class="sy0">#/</span><span class="br0">(</span><span class="br0">{</span>areaCode<span class="br0">}</span>\d<span class="br0">{</span><span class="nu0">3</span><span class="br0">}</span><span class="br0">)</span><span class="sy0">-</span><span class="br0">(</span><span class="br0">{</span>localNumber<span class="br0">}</span>\d<span class="br0">{</span><span class="nu0">5</span><span class="br0">}</span><span class="br0">)</span><span class="sy0">/</span><span class="sy0">=~</span>number m areaCode println m localNumber println
</pre></div>
</div>
<a name="FileSystem"></a>
<h2><span class="mw-headline">FileSystem</span></h2>
<p>The FileSystem kind allows access to functionality in the file system. It is
the entry point to any manipulation of files and directories, and it can also
be used to get listings of existing files. The reference includes good
information about the existing methods in the FileSystem kind.</p>
<a name="Other_things"></a>
<h2><span class="mw-headline">Other things</span></h2>
<p>Ioke supports transforming an object into another object through the use of
the method become!. After an object becomes another object, those two objects
are indistinguishable from Ioke. This makes it really easy to do transparent
proxies, futures and other things like that. To use it, do something like
this:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
x<span class="sy0">=</span><span class="st0">"foo"</span>y<span class="sy0">=</span><span class="st0">"bar"</span>x become!<span class="br0">(</span>y<span class="br0">)</span>x same?<span class="br0">(</span>y<span class="br0">)</span><span class="co1">; => true</span>
</pre></div>
</div>
<p>In Ioke, objects can also be frozen. When an object is frozen it cannot be
modified in any way. Any try at modifying a frozen object will result in a
condition. This can be really helpful to track down problems in code, and make
assertions about what should be possible. You freeze an Ioke object by calling
freeze! on it. You can unfreeze it by calling thaw! on it. You can also check
if something is frozen by calling frozen? on it.</p>
<a name="Java_integration"></a>
<h1><span class="mw-headline">Java integration</span></h1>
<h1><span class="mw-headline">Javaとの統合</span></h1>
<p>Java classes can be accessed by their full name, separated with colon
instead of dots:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
h<span class="sy0"> = </span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map</span> new
</pre></div>
</div>
<p>You can invoke methods as expected, although the rules for this are a bit
intricate. Specifically, the rules are that when calling methods that take any
kind of primitive arguments (most of the types in java.lang), these values will
be unwrapped. That means for a method taking an int, you can send in a wrapped
Java Integer, but you can also send in an Ioke Number Rational, and it will be
unwrapped correctly. You can send Text and Symbol to methods taking
Strings.</p>
<p>If you send in data to a method taking Object, you will not get the expected
result in all cases. Specifically, in these cases Ioke will unwrap wrapped Java
objects, but will not coerce the primitive types. So doing<code>h put("foo",
"bar")</code>will not coerce Text into java.util.String. However, if you have a
java.lang.String that has been modified from the Ioke side - adding cells for
example - then that String will be unwrapped before sent to the method
call.</p>
<p>The return value from a Java invocation will never be modified, except that
null will always be changed into nil, and Java booleans will be transformed
into Ioke booleans. This means that if you wrap a Java object, do some
modifications to it, and then let it go through a Java call, what you will get
back is probably not the wrapped version of that object. Of course, later on if
you try to call a method on the object, you will still use the wrapped
data.</p>
<p>The general rule for overloading is that overloaded methods will be sorted
from the most specific to the most general.</p>
<a name="Casts"></a>
<h2><span class="mw-headline">Casts</span></h2>
<p>Ioke Java integration supports casts in the same way as Java does. The main
difference is that the cast will be evaluated at runtime, not compile time. The
name to cast to will be unevaluated. Valid names are either Object, String, any
Java class name where dots are separated with colons, and a few special ones to
handle primitive values. These names are byte, int, integer, long, short, char,
character, float, double and boolean. Casting looks like this:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
x<span class="sy0">=</span><span class="re11">Foo</span>new x bar<span class="br0">(</span><span class="br0">(</span>short<span class="br0">)</span><span class="nu0">123</span>,<span class="br0">(</span>org<span class="re12"><span class="re13">:</span>something</span><span class="re12"><span class="re13">:</span><span class="re11">Interface</span><span class="br0">)</span>anObj<span class="br0">)</span></span>
</pre></div>
</div>
<a name="Class_methods"></a>
<h2><span class="mw-headline">Class methods</span></h2>
<p>Methods that belong to the Java class java.lang.Class are treated a bit
differently from the way other Java methods work. The reason for this is a bit
intricate to explain, but basically comes down to the dichotomy between the way
mimicking works in Ioke, and the way inheritance works in Java.</p>
<p>The easiest way to explain this might be to take a look at
java.util.ArrayList. In Java the hierarchy looks like this (somewhat
simplified)</p>
<pre>
instance >> ArrayList -> AbstractList -> AbstractCollection -> Object -> Serializable -> Cloneable -> Iterable -> Collection -> List -> RandomAccess
</pre>
<p>Note here that all capitalized words are names of classes. The Class itself
is not part of the inheritance structure, because Java has two namespaces. In
Ioke, the above hierarchy basically ends up looking like this:</p>
<pre>
instance -> ArrayList -> Class -> AbstractList -> Class -> AbstractCollection -> Class -> Object -> Class -> Serializable -> Class -> Cloneable -> Class -> Iterable -> Class -> Collection -> Class -> List -> Class -> RandomAccess -> Class
</pre>
<p>This is slightly simplified too, but the basic idea is that Class has to be
part of the same inheritance chain, because there only exists one namespace in
Ioke.</p>
<p>And that is why there is a need to have these methods named differently. So,
for example, say that you want to invoke the<code>toString</code>method
on<code>java:util:HashMap</code>. To do that, you do it like
this:<code>java:util:HashMap class:toString</code>. Note that you can actually
use the<code>class:</code>methods on instances of a class too. The result will
be the same as if the receiver had been that class instead of the instance.</p>
<a name="Fields"></a>
<h2><span class="mw-headline">Fields</span></h2>
<p>Accessing Java fields can be done by prepending the field name
with<code>field:</code>. The exact mechanics of this is that a Java field will
result in one or two Ioke methods. That means that the fields are not
represented as cells directly on the object. If the field is not final, a
setter will be also be generated for it. The setter follows the same rules as
invocations of regular methods, with regards to casting and choice of unpacking
of arguments.</p>
<p>There is a slight gotcha with this scheme. If you try to set a field that is
final, you will end up overwriting the accessor for that field - so it's
important to be really careful to not set final fields. In the long run, it
might be an idea to implement a setter that signals a condition when this
happens, but doing that gives the impression that you can set the value - since
the setter is there.</p>
<p>Ioke doesn't care if a field is private or protected. All fields are
accessible.</p>
<p>A small example - say that you have a java object in<code>foo</code>. This
Java object has two fields
called<code>oneThing</code>and<code>anotherThing</code>. Then you can work with
it like this:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
foo field<span class="re12"><span class="re13">:</span>oneThing</span>println foo field<span class="re12"><span class="re13">:</span>anotherThing</span><span class="sy0">=</span><span class="st0">"Bar"</span><span class="re9"><span class="re11">System</span></span>out println<span class="br0">(</span>foo field<span class="re12"><span class="re13">:</span>anotherThing<span class="br0">)</span></span>
</pre></div>
</div>
<p>Note that static fields work the same way - so you can access the Java
streams directly like this, for example:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
java<span class="re12"><span class="re13">:</span>lang</span><span class="re12"><span class="re13">:</span><span class="re9"><span class="re11">System</span></span></span>field<span class="re12"><span class="re13">:</span>out</span>println<span class="br0">(</span><span class="st0">"some text"</span><span class="br0">)</span>
</pre></div>
</div>
<a name="Importing_2"></a>
<h2><span class="mw-headline">Importing</span></h2>
<p>Ioke can import classes just as Java can. The way to do it looks a bit
different, though. Also, in Ioke an import only means that a local name will be
assigned to a class. It will not necessarily be globally visible, unless you
import in a global scope. It's also important to keep in mind that imports will
not happen if they might shadow or overwrite a name. If you want that, you will
have to do a manual assignment instead.</p>
<p>There are three ways of using the method<code>import</code>. The first one
is simply to import one class with the same name as it already has:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="co1">;; these are all equivalent</span><span class="re11">Hash</span>Map<span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map</span>import<span class="br0">(</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map<span class="br0">)</span></span>import java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map</span><span class="co1">;; you can also import directly into a scope</span>foo<span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span>foo import<span class="br0">(</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Linked</span>HashMap<span class="br0">)</span></span>foo<span class="re11">Linked</span>HashMap new
</pre></div>
</div>
<p>Note that you can only give one class to import when using the above
way.</p>
<p>The second way to import is when you want to rename the imports. This allow
you to import several classes from different packages and also rename them at
the same time. This is done using keyword arguments to import:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="co1">;; these are all equivalent</span><span class="re11">Foo</span><span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map</span><span class="re11">Bar</span><span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>lang</span><span class="re12"><span class="re13">:</span><span class="re11">String</span></span>import<span class="br0">(</span><span class="re11">Foo</span><span class="re13">:</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map,</span><span class="re11">Bar</span><span class="re13">:</span>java<span class="re12"><span class="re13">:</span>lang</span><span class="re12"><span class="re13">:</span><span class="re11">String</span><span class="br0">)</span></span><span class="co1">;; you can do the same in a new scope:</span>foo<span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span>foo import<span class="br0">(</span><span class="re11">Foo</span><span class="re13">:</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map,</span><span class="re11">Bar</span><span class="re13">:</span>java<span class="re12"><span class="re13">:</span>lang</span><span class="re12"><span class="re13">:</span><span class="re11">String</span><span class="br0">)</span></span>foo<span class="re11">Foo</span>new
</pre></div>
</div>
<p>The third way allow you to import several classes from the same package.
Note that to use this way, you need to provide at least one class name, in
addition to the package name:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="co1">;; these are the same as the following import</span><span class="re11">Hash</span>Map<span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map</span><span class="re11">Linked</span>List<span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Linked</span>List</span><span class="re11">Array</span>List<span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>util</span><span class="re12"><span class="re13">:</span><span class="re11">Array</span>List</span>import<span class="br0">(</span><span class="re12"><span class="re13">:</span>java</span><span class="re12"><span class="re13">:</span>util,</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map,</span><span class="re12"><span class="re13">:</span><span class="re11">Linked</span>List,</span><span class="re12"><span class="re13">:</span><span class="re11">Array</span>List<span class="br0">)</span></span><span class="co1">;; and just as above, you can do it in a scope too</span>foo<span class="sy0">=</span><span class="re9"><span class="re11">Origin</span></span><span class="re6">mimic</span>foo import<span class="br0">(</span><span class="re12"><span class="re13">:</span>java</span><span class="re12"><span class="re13">:</span>util,</span><span class="re12"><span class="re13">:</span><span class="re11">Hash</span>Map,</span><span class="re12"><span class="re13">:</span><span class="re11">Linked</span>List,</span><span class="re12"><span class="re13">:</span><span class="re11">Array</span>List<span class="br0">)</span></span>foo<span class="re11">Linked</span>List new
</pre></div>
</div>
<a name="Java_native_arrays"></a>
<h2><span class="mw-headline">Java native arrays</span></h2>
<p>In general, working with Java native arrays work exactly like you would
expect. The main difference is how you create them. For working with native
arrays of primitive types, you can use the primitive type names, which
are:<em>java:byte</em>,<em>java:short</em>,<em>java:char</em>,<em>java:int</em>,<em>java:long</em>,<em>java:float</em>and<em>java:double</em>.
When setting or getting values from these arrays, they will work exactly like
the coercions for regular Java methods.</p>
<p>You can either create a new empty array, or you can initialize it based on
an existing Ioke list:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
x<span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>short<span class="br0">[</span><span class="nu0">5</span><span class="br0">]</span></span>new x<span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>short<span class="br0">[</span><span class="br0">]</span></span>from<span class="br0">(</span><span class="br0">[</span><span class="nu0">1</span>,<span class="nu0">2</span>,<span class="nu0">3</span>,<span class="nu0">4</span>,<span class="nu0">5</span><span class="br0">]</span><span class="br0">)</span>
</pre></div>
</div>
<p>The first version creates a JavaArrayProxyCreator with dimension one, and
length 5. The call to<em>new</em>will generate the actual array from this. You
can create multidimensional arrays by adding new pairs of square brackets.</p>
<p>In the second example, the call to square-brackets without an argument, will
return the type of that array class. We then call<em>from</em>on that type,
which will take an Ioke list, and generate an equivalent Java native array.</p>
<p>You can set and get values in Java arrays, just as you would with Ioke
lists:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
x<span class="sy0">=</span>java<span class="re12"><span class="re13">:</span>char<span class="br0">[</span><span class="nu0">10</span><span class="br0">]</span></span>new x<span class="br0">[</span><span class="nu0">5</span><span class="br0">]</span><span class="sy0">=</span><span class="nu0">10</span>x<span class="br0">[</span><span class="nu0">6</span><span class="br0">]</span><span class="sy0">=</span><span class="nu0">13</span>x<span class="br0">[</span><span class="nu0">5</span><span class="br0">]</span>println
</pre></div>
</div>
<p>Finally, Java native arrays implement<em>each</em>, and mimic<em>Mixins
Enumerable</em>, which means that most things you expect to be able to do with
them will work correctly.</p>
<a name="Adding_jar-files_to_the_CLASSPATH"></a>
<h2><span class="mw-headline">Adding jar-files to the CLASSPATH</span></h2>
<p>If you dynamically want to add new jar-files to the CLASSPATH, you can do
that using<em>use</em>. There are two ways of doing it - you can either be
implicit or explicit, depending on if the module name is unique to a jar-file
or not:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="re6">use</span><span class="br0">(</span><span class="st0">"the_jar_file"</span><span class="br0">)</span><span class="re6">use</span><span class="br0">(</span><span class="st0">"the_jar_file.jar"</span><span class="br0">)</span><span class="re6">use</span>jar<span class="br0">(</span><span class="st0">"the_jar_file"</span><span class="br0">)</span>
</pre></div>
</div>
<a name="Implementing_and_extending_Java_types"></a>
<h2><span class="mw-headline">Implementing and extending Java types</span></h2>
<p><a href="/wiki/index.php/Ioke_E" title="Ioke E">Ioke E</a>supports
implementing Java interfaces from Ioke, and extending Java classes. This
machinery is all done with the method<code>integrate</code>.</p>
<p>The<code>integrate</code>method takes one or more Java types (it doesn't
matter if it's classes or interfaces, but it can only take at most one class),
and then returns a new class that is magic in that it will proxy back all calls
to the Ioke object, if it defines a method with the corresponding name. This
scheme works for most things, but there are some things to keep in mind too.
The most important one is that if you override a method that is overloaded in
Java-land, it is the responsibility of the Ioke method to handle all the
overloads.</p>
<p>Using it is very simple:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
<span class="re11">Ioke</span>Runnable<span class="sy0">=</span>integrate<span class="br0">(</span>java<span class="re12"><span class="re13">:</span>lang</span><span class="re12"><span class="re13">:</span><span class="re11">Runnable</span><span class="br0">)</span></span><span class="re11">Ioke</span>Runnable run<span class="sy0">=</span><span class="re8">method</span><span class="br0">(</span><span class="st0">"running!"</span>println<span class="br0">)</span>java<span class="re12"><span class="re13">:</span>lang</span><span class="re12"><span class="re13">:</span><span class="re11">Thread</span></span>new<span class="br0">(</span><span class="re11">Ioke</span>Runnable new<span class="br0">)</span>
</pre></div>
</div>
<p>Note that you have to use the<code>new</code>method to create new instances
of this object. In this way it behaves exactly like regular objects in Java
integration. And just in the same way, doing mimic will not copy the internal
Java object, just the outwards Ioke object.</p>
<p>Integration takes care of handling coercion of arguments and return values
into what Java expects.</p>
<a name="Coercing_lexical_blocks_to_interfaces"></a>
<h3><span class="mw-headline">Coercing lexical blocks to interfaces</span></h3>
<p>Ioke contains a mechanism that will automatically try to coerce anything
code-like into an interface or abstract class if no other matching overload can
be found for a method. So, that means you can do something like this, and it
will work as expected:</p>
<div dir="ltr" style="text-align:left;">
<div class="ioke source-ioke" style="font-family:monospace;">
<pre class="de1">
javax<span class="re12"><span class="re13">:</span>swing</span><span class="re12"><span class="re13">:</span>JButton</span>new addActionListener<span class="br0">(</span><span class="re8">fn</span><span class="br0">(</span>e,<span class="st0">"button pressed"</span>println<span class="br0">)</span><span class="br0">)</span>
</pre></div>
</div>
<a name="Libraries"></a>
<h1><span class="mw-headline">Libraries</span></h1>
<h1><span class="mw-headline">ライブラリ</span></h1>
<p>Ioke ships with several small libraries that are useful for different tasks.
The main ones are IIk, ISpec and DokGen, and these will be documented a bit
more in this chapter. All of them are considered a core part of Ioke since the
functionality they provide is tied to the distribution.</p>
<a name="IIk"></a>
<h2><span class="mw-headline">IIk</span></h2>
<dl><dd>
<div class="noprint"><em>Main article:<a href="/wiki/index.php/Iik" title="Iik">Iik</a></em></div>
</dd>
</dl><p>IIk is the interactive Ioke prompt, which will run if you give no arguments
to the ioke script. At the IIk prompt you can execute mostly all the same kind
of code that could execute inside of an Ioke script file. The main difference
is that this code will not be assigned to Ground, but instead will run in
another context that is specific for the purposes of IIk.</p>
<a name="ISpec"></a>
<h2><span class="mw-headline">ISpec</span></h2>
<dl><dd>
<div class="noprint"><em>Main article:<a href="/wiki/index.php/ISpec" title="ISpec">ISpec</a></em></div>
</dd>
</dl><p>ISpec is a minimal port of the Ruby RSpec framework for behavior-driven
development. It supports the bare minimum to allow testing of Ioke itself. The
current Ioke test suite is completely written in ISpec, and it seems to be a
capable environment.</p>
<a name="DokGen"></a>
<h2><span class="mw-headline">DokGen</span></h2>
<dl><dd>
<div class="noprint"><em>Main article:<a href="/wiki/index.php/DokGen" title="DokGen">DokGen</a></em></div>
</dd>
</dl><p>DokGen is the tool that is used to generate the reference documentation for
Ioke, and it generates output similar to<a href="http://rdoc.sourceforge.net/" class="external text" title="http://rdoc.sourceforge.net/">RDoc</a>. Its goal
is to be a general purpose tool for any Ioke application.</p>
<a name="What_is_missing"></a>
<h1><span class="mw-headline">What is missing</span></h1>
<h1><span class="mw-headline">ないもの</span></h1>
<p>Ioke E is not a finished Ioke version. I seriously doubt Ioke will ever be
complete. The core mechanics of the language I'm feeling fairly confident in,
but the core libraries are generally only partially implemented. They are much
more complete than for the Ioke S release, but there still exist large holes in
it.</p>
<p>Concurrency support is missing, and so is any kind of advanced IO. Package
management and other libraries like that is now starting to become necessary.
Finally, alternative implementations for other platforms is also in the
pipeline to happen sooner or later.</p>
<p>There is a<a href="/wiki/index.php/Todo" title="Todo">Todo</a>list where we
gather those things that should be done, sooner or later.</p>
<a name="Future_plans"></a>
<h1><span class="mw-headline">Future plans</span></h1>
<h1><span class="mw-headline">今後の予定</span></h1>
<p>I have many plans for the future of Ioke. The next major version of Ioke
will be called<a href="/wiki/index.php?title=Ioke_P&action=edit&redlink=1" class="new" title="Ioke P (not yet written)">Ioke P</a>. Exactly what it will contain we'll have
to see, but feel free to add your requests and ideas to<a href="/wiki/index.php/Todo" title="Todo">our TODO list</a>.</p>
<div class="printfooter">Retrieved from "<a href="http://ioke.org/wiki/index.php/Guide">http://ioke.org/wiki/index.php/Guide</a>"</div>
<div class="visualClear"> </div>
</div>
</div>
</div>
<div id="column-one">
<div id="p-cactions" class="portlet">
<h5>Views</h5>
<div class="pBody">
<ul><li id="ca-nstab-main" class="selected"><a href="/wiki/index.php/Guide" title="View the content page [c]">Page</a></li>
<li id="ca-talk" class="new"><a href="/wiki/index.php?title=Talk:Guide&action=edit" title="Discussion about the content page [t]">Discussion</a></li>
<li id="ca-viewsource"><a href="/wiki/index.php?title=Guide&action=edit" title="This page is protected. You can view its source. [e]">View
source</a></li>
<li id="ca-history"><a href="/wiki/index.php?title=Guide&action=history" title="Past versions of this page. [h]">History</a></li>
</ul></div>
</div>
<div class="portlet" id="p-personal">
<h5>Personal tools</h5>
<div class="pBody">
<ul><li id="pt-login"><a href="/wiki/index.php?title=Special:UserLogin&returnto=Guide" title="You are encouraged to log in, it is not mandatory however. [o]">Log in /
create account</a></li>
</ul></div>
</div>
<div class="portlet" id="p-logo"> </div>
<div class="generated-sidebar portlet" id="p-">
<div class="pBody">
<ul><li id="n-News"><a href="/wiki/index.php/News">News</a></li>
<li id="n-About-Ioke"><a href="http://ioke.org/index.html">About Ioke</a></li>
<li id="n-Guide"><a href="/wiki/index.php/Guide">Guide</a></li>
<li id="n-Download-x"><a href="http://ioke.org/download.html">Download</a></li>
<li id="n-Project-page"><a href="http://ioke.kenai.com">Project page</a></li>
<li id="n-Reference"><a href="http://ioke.org/dok/index.html">Reference</a></li>
<li id="n-Resources"><a href="/wiki/index.php/Resources">Resources</a></li>
<li id="n-Wiki"><a href="http://ioke.org/wiki">Wiki</a></li>
</ul></div>
</div>
<div class="generated-sidebar portlet" id="p-Wiki">
<h5>Wiki</h5>
<div class="pBody">
<ul><li id="n-mainpage-description"><a href="/wiki/index.php/Main_Page">Main
Page</a></li>
<li id="n-recentchanges"><a href="/wiki/index.php/Special:RecentChanges" title="The list of recent changes in the wiki. [r]">Recent changes</a></li>
</ul></div>
</div>
<div id="p-search" class="portlet">
<h5>Search</h5>
<div id="searchBody" class="pBody">
<div> </div>
</div>
</div>
<div class="portlet" id="p-tb">
<h5>Toolbox</h5>
<div class="pBody">
<ul><li id="t-whatlinkshere"><a href="/wiki/index.php/Special:WhatLinksHere/Guide" title="List of all wiki pages that link here [j]">What links here</a></li>
<li id="t-recentchangeslinked"><a href="/wiki/index.php/Special:RecentChangesLinked/Guide" title="Recent changes in pages linked from this page [k]">Related changes</a></li>
<li id="t-specialpages"><a href="/wiki/index.php/Special:SpecialPages" title="List of all special pages [q]">Special pages</a></li>
<li id="t-print"><a href="/wiki/index.php?title=Guide&printable=yes" title="Printable version of this page [p]">Printable version</a></li>
<li id="t-permalink"><a href="/wiki/index.php?title=Guide&oldid=230" title="Permanent link to this version of the page">Permanent link</a></li>
</ul></div>
</div>
</div>
<br /><div id="footer">
<ul id="f-list"><li id="lastmod">This page was last modified on 5 April 2009, at 14:32.</li>
<li id="viewcount">This page has been accessed 6,503 times.</li>
<li id="copyright">Content is available under<a href="http://www.gnu.org/copyleft/fdl.html" class="external" title="http://www.gnu.org/copyleft/fdl.html">GNU Free Documentation License
1.2</a>.</li>
<li id="privacy"><a href="/wiki/index.php/IokeWiki:Privacy_policy" title="IokeWiki:Privacy policy">Privacy policy</a></li>
<li id="about"><a href="/wiki/index.php/IokeWiki:About" title="IokeWiki:About">About IokeWiki</a></li>
<li id="disclaimer"><a href="/wiki/index.php/IokeWiki:General_disclaimer" title="IokeWiki:General disclaimer">Disclaimers</a></li>
</ul></div>
</div>