IokeWiki - User contributions [en]

Main Page

2009-11-04T01:09:36Z

Cv: revert spam

__NOTOC__
Welcome to the Ioke wiki. This wiki is dedicated to everything that has to do with the Ioke programming language.

<table width="100%" cellpadding="10">
<tr valign="top">
<td>
== About Ioke ==

* [[Guide|Programming Guide]]
* [[Pitfalls|Common pitfalls]]
* [[Future plans]]

== Versions ==

* [[Ioke 0]]
* [[Ioke S]]
* [[Ioke E]]
* [[Ioke P]]
* [[Ioke F]]
</td>
<td>
== Libraries ==
* [[Cane]]
* [[DokGen]]
* [[IIk]]
* [[IOpt]]
* [[ISpec]]
* [[Mike]]
* [[TextScanner]]
</td>
<td>

== Development process ==

* [[Todo]]
* [[Cooperation with Git]]
* [[Editors]]

== Events ==

* Ioke at Amsterdam.rb, February 23rd 2009. (already been)
* Language creation with Ioke and JRuby case studies
** At ThoughtWorks and QCon Geek Night, London, March 10th 2009.
** Video here: [http://skillsmatter.com/podcast/java-jee/language-on-jvm]
* Ioke - A Folding Language, at ThoughtWorks Geek Night, Bangalore, April 21st 2009
** More info here: [http://www.thoughtworker.com/events/geek-night-ola-bini]
* Ioke - A Folding Language, at Skills Matter, London, May 14th 2009
** More info and signup: [http://skillsmatter.com/event/java-jee/ljc-meetup-346]
* Ioke for Ruby Developers at RailsWayCon, Berlin, May 26th 2009
** More info here: [http://it-republik.de/conferences/railswaycon/]
</td>
</tr>
</table>

Todo

2009-03-06T19:40:05Z

Cv:

This page contains a brief list of things that remains to be done. It should link to a page with more information when needed.

== Core language ==

* [[Java integration planning|Java integration]] - [[User:Olabini|Ola Bini]]
* [[Concurrency planning|Concurrency primitives]]
* Assignment
** [[Destructuring assignment ideas|Destructuring assignment]] with ()
* Units

== Core libraries ==

* [[Socket]]
* [[Tuple]]
* [[Iik]]
** Saving history to file

== Applications ==

* [[Cane planning|Cane]]

== Other libraries ==

* SQL interaction DSL
* JRuby integration

== Implementation ==

* Chained/Linked map structure - [[Martin Elwin]]
* Saving/restoring VM state to disk (a la Smalltalk image)
* [[CLR runtime planning|CLR runtime]]
* [[V8 runtime planning|V8 runtime]]

Guide:Code

2009-02-07T13:59:04Z

Cv: /* Syntax */

= Code =

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.

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.

== Methods ==

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.

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:

<source lang="ioke">m = method()
m ;; call the method</source>
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.

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.

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:

<source lang="ioke">;; a method that returns "foo"
m = method("foo")

;; a method that returns nil, but
;; has the documentation text "foo"
m = method("foo", nil)</source>
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.

<source lang="ioke">m = method(x, x println)
m = method(x, y, z,
x * y + z)</source>
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.

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.

<source lang="ioke">;; takes zero or one arguments
m = method(x 42, x println)

;; takes one to three arguments
m = method(x, y 42, z 25,
x*y + z)</source>
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.

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.

A keyword argument is defined just like a regular argument, except that it ends in a colon.

<source lang="ioke">m = method(foo:, bar: 42,
foo println
bar println
)</source>
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.

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.

<source lang="ioke">m = method(+rest,
rest println)

m = method(x, y 42, +rest,
rest println)</source>
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.

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.

<source lang="ioke">m = method(+:krest,
krest println)

m = method(x, y:, +rest, +:krest,
[x, y, rest, krest])</source>
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.

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.

<source lang="ioke">createNewCell = method(
@foo = 42
)</source>
The method create above will create assign the value 42 to the cell "foo" on the object the method was called on.

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:

<source lang="ioke">;; the method foo takes any kind of argument
foo
foo()
foo(1, 2, 3)
foo(blarg: 42, 2, 3, 4)
foo(quux: 42*2)</source>
To give a keyword argument, you just write it exactly like you define keyword arugments - a name followed by a colon.

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.

<source lang="ioke">dc = {foo: 42, bar: 13}
ls = [1, 2, 3, 4]
ls2 = [42, 43, 44]

foo(*dc)
;; the same as:
foo(foo: 42, bar: 13)

foo(*ls)
;; the same as:
foo(1, 2, 3, 4)

foo(*ls2, 111, *dc, *ls)
;; the same as:
foo(42, 43, 44, 111, foo: 42, bar: 13, 1, 2, 3, 4)</source>
If you try to splat something that can't be splatted, a condition will be signalled.

== Macros ==

The main difference between a macro and a method in Ioke is that the arguments to a macro is 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.

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 is 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.

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:

; arguments
: This method returns a list containing the unevaluated arguments given to this message. Any kind of manipulation can be done with these arguments.
; ground
: Returns the ground in which the call was initiated. This is necessary to evaluate arguments in their own environment.
; message
: The currently executing message. This is the same as the "currentMessage" cell in the macro activation context.
; evaluatedArguments
: Returns a list containing all arguments, evaluated according to the regular rules (but not handling splatting or keywords).
; resendToMethod
: Allows a specific message to be resent to another method, without manually copying lots of information.
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.

<source lang="ioke">Mixins Enumerable map = macro(
"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.",

len = call arguments length
result = list()
if(len == 1,
code = call arguments first
self each(n, result << code evaluateOn(call ground, cell(:n))),

code = LexicalBlock createFrom(call arguments, call ground)
self each(n, result << code call(cell(:n))))
result)</source>
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.

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 exacty 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.

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.

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.

== Blocks ==

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 [[Guide:Assignment|described]] earlier.

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.

A block created with the "fn" method can be invoked using the "call" method of the kind [http://ioke.org/dok/kinds/LexicalBlock.html <code>LexicalBlock</code>].

<source lang="ioke">
x = fn(z, z println)
x call(42)
</source>

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.

<source lang="ioke">
x = fn(z, z + 42)
y(x(100)) ;; activates the block with argument 100 and passes the result to y
x ;; refers to the block without activating it
</source>

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.

<source lang="ioke">
y = fnx(z, z println)
y(42)
</source>

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.

== Lecros ==

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.

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.

== Syntax ==

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.

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.

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.

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.

== Destructuring ==

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.

Let us say we have a macro that either [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:

<source lang="ioke">foo = macro(
len = call arguments length
case(len,
1,
code = call arguments[0]
; do something with the code
,
2,
arg1 = call argAt(0)
code = call arguments[1]
; do something with the code and arg
,
3,
arg1 = call argAt(0)
code = call arguments[1]
arg2 = call argAt(2)
; do something with the code and args
))</source>
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:

<source lang="ioke">foo = dmacro(
[code]
; do something with the code
,
[>arg1, code]
; do something with the code and arg
,
[>arg1, code, >arg2]
; do something with the code and args
)</source>
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.

== Message chains ==

In many cases a macro will take code that is not wrapped up inside of a method, macro or block. These pieces of code is called message chains, since their representation will be to 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.

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.

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.

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.

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 <nowiki>''</nowiki>, 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, <nowiki>''</nowiki> will replace a `` with a literal ` message.

You can add new arguments to a message by using the << operator. This operator returns the receiver.

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.

I think it is time for some examples:

<source lang="ioke">; create a new message with name foo
x = 'foo

; add two arguments to the foo message
arg = '(bar quux)
(x << arg) << 'baz

; what we have done so far could be done with:
x = '(foo(bar quux, baz))

y = 'blurg
; chain together x and y
x -> y

; the above is equivalent to
if(y prev,
y prev next = nil)
x next = y
y prev = x

val = 42

; insert the message chain in x
''(foo bar(`val) `x)

; the above will return the same as
'(foo bar(42) foo(bar quux, baz))</source>
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.

Guide:Introduction

2009-01-27T07:46:09Z

Cv: /* Building Ioke */

= Introduction =

Ioke is a general purpose language. It is a strongly typed, extremely dynamic, prototype object oriented language. It is [http://en.wikipedia.org/wiki/Homoiconicity homoiconic] and its closest ancestors are [http://iolanguage.com Io], [http://www.smalltalk.org Smalltalk], [http://www.ruby-lang.org Ruby] and [http://en.wikipedia.org/wiki/Lisp_programming_language Lisp] - but it's quite a distance from all of them. It looks a lot like Io, to a limit.

Ioke is a ''folding'' 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.

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.

You're probably reading this guide at [http://ioke.org/guide.html ioke.org]. That is the official home of the project, although some of the project functionality is hosted at [http://ioke.kenai.com Kenai], where such things as mailing lists and a bug tracker is available. The canonical source repository for Ioke is on [http://github.org/olabini/ioke/tree/master GitHub].

The current version of Ioke is called [[Ioke S]]. The naming of Ioke will change regularly with major revisions. There are two different versions in play here. Ioke S is the name and version of the language and core libraries. The initial implementation for Ioke S is called <tt>ikj 0.2.0</tt>, and the version numbers are not interdependent. The next major version of Ioke will be called [[Ioke E]], and you can find information about it in the chapter on [[#Future_plans|future plans]].

This programming guide -- together with the reference for your current version -- should be the complete document needed to understand Ioke S, 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.

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 [[#Objects|Objects]], skim that bit, and then start over once words like ''Origin'', ''cell'' and ''mimic'' make sense.

== Vision ==

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.

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?

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.

Are still Lisp and Smalltalk 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.

Simplicity doesn't mean lack of power. Small, simple, orthogonal functionality can be more powerful than larger, complicated abstractions that don't fit together.

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.

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.

== Getting started ==

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 [http://ioke.org/download.html download page], and grab one of the distributions. At the time of writing the full version of Ioke is Ioke S ikj 0.2.0. Choose the latest download in the 0.2-series for this document to apply.

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.

=== Building Ioke ===

If you'd like to build Ioke from source, make sure you have a recent version of the [http://java.sun.com/javase/downloads/index.jsp Java Development Kit] installed (1.5.0 or higher, preferrably 1.6.0) and [http://ant.apache.org Apache Ant]. You must have the <tt>ant</tt> script reachable from your <tt>PATH</tt> variable. Then, simply check out the source code from the [http://github.org/olabini/ioke/tree/master main repository], and built 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>.

=== Running scripts ===

To run an Ioke script, you can generally just use the <tt>ioke</tt> command:

<pre>$ ioke helloWorld.ik
Hello world</pre>

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:

<pre>$ ioke -e'"Hello world" println' -e'"Goodbye world" println'
Hello world
Goodbye world</pre>

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.

The <tt>ioke</tt> command has several helpful command line options, which can change what happens during execution. These are:

; -Cdirectory
: 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.
; -d
: Enable debug output.
; -e script
: Execute script, as describe above. May occur more than once on a command line.
; -h<br />
--help
: Display help information, including descriptions of these command line options.
; -Idirectory
: Add directory to the load path of Ioke. May occur more than once on a command line.
; -JjvmOptions
: 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.
; --copyright
: Print copyright information and exit.
; --version
: Print version information and exit
; --server
: Run the JVM in server Hotspot mode
; --client
: Run the JVM in client Hotspot mode (the default)
; --
: Mark the end of options to the <tt>ioke</tt> script, anything after this are options to be sent to the code running.
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.

=== Interactive mode ===

If no code to execute has been specified to the <tt>ioke</tt> script, [[IIk|IIk - Interactive Ioke]] - 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 [[Conditions|condition]] 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.

IIk will try to use Readline through JLine if your platform supports it.

IIk will be more closely described later, but just to give you a glimpse, this is how a small session could look like:

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

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.

Guide:Introduction

2009-01-27T07:44:05Z

Cv: /* Getting started */

= Introduction =

Ioke is a general purpose language. It is a strongly typed, extremely dynamic, prototype object oriented language. It is [http://en.wikipedia.org/wiki/Homoiconicity homoiconic] and its closest ancestors are [http://iolanguage.com Io], [http://www.smalltalk.org Smalltalk], [http://www.ruby-lang.org Ruby] and [http://en.wikipedia.org/wiki/Lisp_programming_language Lisp] - but it's quite a distance from all of them. It looks a lot like Io, to a limit.

Ioke is a ''folding'' 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.

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.

You're probably reading this guide at [http://ioke.org/guide.html ioke.org]. That is the official home of the project, although some of the project functionality is hosted at [http://ioke.kenai.com Kenai], where such things as mailing lists and a bug tracker is available. The canonical source repository for Ioke is on [http://github.org/olabini/ioke/tree/master GitHub].

The current version of Ioke is called [[Ioke S]]. The naming of Ioke will change regularly with major revisions. There are two different versions in play here. Ioke S is the name and version of the language and core libraries. The initial implementation for Ioke S is called <tt>ikj 0.2.0</tt>, and the version numbers are not interdependent. The next major version of Ioke will be called [[Ioke E]], and you can find information about it in the chapter on [[#Future_plans|future plans]].

This programming guide -- together with the reference for your current version -- should be the complete document needed to understand Ioke S, 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.

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 [[#Objects|Objects]], skim that bit, and then start over once words like ''Origin'', ''cell'' and ''mimic'' make sense.

== Vision ==

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.

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?

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.

Are still Lisp and Smalltalk 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.

Simplicity doesn't mean lack of power. Small, simple, orthogonal functionality can be more powerful than larger, complicated abstractions that don't fit together.

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.

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.

== Getting started ==

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 [http://ioke.org/download.html download page], and grab one of the distributions. At the time of writing the full version of Ioke is Ioke S ikj 0.2.0. Choose the latest download in the 0.2-series for this document to apply.

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.

=== Building Ioke ===

If you'd like to build Ioke from source, make sure you have a recent version of the [http://java.sun.com/javase/downloads/index.jsp Java Development Kit] installed (1.5.0 or higher, preferrably 1.6.0) and [http://ant.apache.org Apache Ant]. You must have the <tt>ant</tt> script reachable from your <tt>PATH</tt> variable. Then, simply check out the source code from the [[main repository]], and built it using <tt>ant</tt>.

=== Running scripts ===

To run an Ioke script, you can generally just use the <tt>ioke</tt> command:

<pre>$ ioke helloWorld.ik
Hello world</pre>

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:

<pre>$ ioke -e'"Hello world" println' -e'"Goodbye world" println'
Hello world
Goodbye world</pre>

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.

The <tt>ioke</tt> command has several helpful command line options, which can change what happens during execution. These are:

; -Cdirectory
: 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.
; -d
: Enable debug output.
; -e script
: Execute script, as describe above. May occur more than once on a command line.
; -h<br />
--help
: Display help information, including descriptions of these command line options.
; -Idirectory
: Add directory to the load path of Ioke. May occur more than once on a command line.
; -JjvmOptions
: 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.
; --copyright
: Print copyright information and exit.
; --version
: Print version information and exit
; --server
: Run the JVM in server Hotspot mode
; --client
: Run the JVM in client Hotspot mode (the default)
; --
: Mark the end of options to the <tt>ioke</tt> script, anything after this are options to be sent to the code running.
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.

=== Interactive mode ===

If no code to execute has been specified to the <tt>ioke</tt> script, [[IIk|IIk - Interactive Ioke]] - 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 [[Conditions|condition]] 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.

IIk will try to use Readline through JLine if your platform supports it.

IIk will be more closely described later, but just to give you a glimpse, this is how a small session could look like:

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

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.

Todo

2009-01-26T20:28:15Z

Cv:

This page contains a brief list of things that remains to be done. It should link to a page with more information when needed.

== Core language ==

* [[Java integration planning|Java integration]]
* [[Concurrency planning|Concurrency primitives]]
* Assignment
** [[Destructuring assignment ideas|Destructuring assignment]] with ()
* Units

== Core libraries ==

* [[List]]
** Removing elements
* [[Socket]]
* [[Tuple]]
* [[Iik]]
** Saving history to file

== Applications ==

* [[Cane planning|Cane]]

== Other libraries ==

* SQL interaction DSL
* JRuby integration

== Implementation ==

* Chained/Linked map structure
* [[CLR runtime planning|CLR runtime]]
* [[V8 runtime planning|V8 runtime]]

2009-01-26T02:57:59Z

Cv: Replacing page with '{{:Future plans}}'

IIk

2009-01-26T00:34:31Z

Cv: IIk moved to Iik

#REDIRECT [[Iik]]

Guide:Libraries

2009-01-26T00:32:39Z

Cv: /* IIk */

= Libraries =

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.

== IIk ==

{{main|Iik}}

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.

IIk provides the possibility to exit using either "exit" or "close". Both of these will in fact signal a condition of kind "IIk Exit".

IIk will use readline if possible. That means that you can do the regular shell editing most other REPLs have support for, including using the up and down keys to scroll through earlier executed code.

IIk has a simple debugger that will be invoked when a condition is not handled. This debugger allows you to execute any kind of code and also to invoke restarts. As an example, the code below refers to a cell that doesn't exist. A condition is signalled and the debugger invoked. I choose to invoke the restart named useValue and provide the value 42. That value is returned and I'm back at the IIk prompt. In the next line I do the same thing again with the same name. This time I choose the storeValue restart and provide the value 43. And after that there exists a cell with the name foo and the value 43.

<pre>Iik> foo
*** - couldn't find cell 'foo' on 'Ground_0x26E9F9' (Condition Error NoSuchCell)

foo [<init>:1:0]

The following restarts are available:
0: storeValue (Store value for: foo)
1: useValue (Use value for: foo)
2: abort (restart: abort)
3: quit (restart: quit)

dbg:> 1
dbg::newValue> 42
+> 42

+> 42

iik> foo
*** - couldn't find cell 'foo' on 'Ground_0x26E9F9' (Condition Error NoSuchCell)

foo [<init>:1:0]

The following restarts are available:
0: storeValue (Store value for: foo)
1: useValue (Use value for: foo)
2: abort (restart: abort)
3: quit (restart: quit)

dbg:> 0
dbg::newValue> 43
+> 43

+> 43

iik> foo
+> 43</pre>
The Ioke debugger is quite powerful. If you were to execute any other Ioke code, that code will actually be executed in the context of the place where the condition was signalled. So it is possible to fix more complicated things in this manner too.

== ISpec ==

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.

The ispec command line tool takes one argument -- "-f" to specify which format to print in. The default is "p" for progress, which only shows one dot for each test run. The "s" alternative shows the longer spec format. To run all tests in a directory with spec format:

<pre>ispec -fs test_dir</pre>
This command will find all files ending in _spec.ik and run the specs defined in them. If a single file is specified, only the tests in that file will run. If more than one directory or file is specified on the command line, all the tests will be run together. Provided the spec files all use the ispec module, the files can be run directly with the ioke-command too.

A full test file utilizing most of the parts of ISpec looks like this:

<pre>use("ispec")

describe(Foo,
it("should have the correct kind",
Foo should have kind("Foo")
Foo kind should == "Foo"
Foo kind should match(#/Fo+/)
)

it("should be possible to mimic",
m = Foo mimic
m should have kind("Foo")
m should not be same(Foo)
m should mimic(Foo)
)

describe("aMethod",
it("should not return nil",
Foo aMethod should not be nil
)

it("should return a number that can be multiplied",
(Foo aMethod * 2) should == 12
)
)

describe("aBadMethod",
it("should signal a condition",
fn(Foo aBadMethod) should signal(Condition Error BadBadBed)
)
)
)</pre>
This code first makes sure to use ISpec, then describes Foo. The describe method takes either kinds or texts describing what's under test. This can be nested arbitrarily deep. A test is defined with the "it" method, which takes a text describing the test first, and the implementation of the test as the second argument. If the second argument is left out, the test is considered pending.

Assertions are done using the "should" method. This returns an expectation that can check several different things against the original receiver. Using == is the simplest expectation and checks that a value equals another. By adding the not method call inbetween, the expectation is inversed. There are some predefined expectations. Except for ==, these are mimic, match and signal. The signal expectation makes sure that a condition is signalled in the code. The match expectation will check a text value against a regular expression. The mimic expectation checks whether an object mimics another.

The words "be" and "have" are ignored in the expectations. They are so called fluff words - that are only there to make it more readable.

If an expectation receives a message it doesn't know about, it uses pass to check a dynamic property. For example, something like "foo should be same(x)" will end up calling "same?" with x as an argument. The same thing happens in the above code to check for kind. There exists no kind expectation. Instead the kind checking will go check for "kind?".

== DokGen ==

{{main|DokGen}}

DokGen is the tool that is used to generate the reference documentation for Ioke. The goal is that it will be a general purpose tool for any Ioke application. It extracts the documentation information from defined objects and then generates an HTML structure from it that can be easily navigated. If specs are available for objects and methods, it will try to incorporate these together with the documentation. At the moment, there is no way to run dokgen on a subset of Ioke code, but that should be available very soon now. At the moment, running the dokgen script will create a directory called "dok" which contains the full documentation. It will use all specs it can find in the directory test.

Iik

2009-01-26T00:32:36Z

Cv: New page: 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...

Guide:Syntax

2009-01-26T00:19:45Z

Cv: New page: = Syntax = 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 me...

= Syntax =

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.

An informal BNF description of Ioke looks like this:

<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>
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 "foo().bar(quux(42)).baaz()" would be expressed as "foo() bar(quux(42)) baaz()", or more succinctly "foo bar(quux(42)) baaz" in Ioke.

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.

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.

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 restructions. 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.

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.

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.

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 [http://{{SERVERNAME}}/#code code].

== Literal values ==

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.

=== Text ===

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 no alternate syntax for text. 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:

; \b
: Inserts the bell character, that is represented in ASCII by the decimal value 8.
; \e
: 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.
; \t
: Inserts the TAB character - ASCII decimal 9.
; \n
: Inserts the newline character - ASCII decimal 10.
; \f
: Inserts the form feed character - ASCII decimal 12.
; \r
: Inserts the carriage return character - ASCII decimal 13.
; \"
: Inserts the double quote character - ASCII decimal 34.
; \\
: Inserts the backslash character - ASCII decimal 92.
; \[newline]
: Inserts nothing at all. Used to escape necessary newlines, without having them show up in the output text.
; \#
: Inserts a literal hash character - ASCII decimal 35.
; \uABCD
: Inserts the Unicode codepoint corresponding to the hexadecimal value of the four characters following the "u". All four hexadecimal characters need to be specified.
; \7, \12, \316
: 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.
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.

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.

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.

Some examples:

<pre>"foo"

"flax \
mux"

"one two #{three} \b four"

#[you don't really "#{1+2+3}" believe that?]</pre>

=== Regular expressions ===

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:

<pre>#//
#r[]

#/foo/
#r[foo]

#/fo+/x
#r[fo+]x

#/bla #{"foo"} bar/
#r[bla #{"foo"} bar]</pre>
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 o, x, p, n, 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.

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.

=== Integers ===

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.

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.

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.

A literal integer will be transformed into a call to internal:createNumber, which takes one native Java String from which to create the number.

Some examples:

<pre>1234444444444444444444444444444444444444235234534534

0

0xFFFFF</pre>

=== Decimals ===

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.

A literal decimal will be transformed into a call to internal:createDecimal, which takes one native Java String from which to create the decimal.

Some examples:

<pre>0.0

1E6

1E-32

23.4445e10</pre>

=== Symbols ===

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.

Some examples:

<pre>:foo

:flaxBarFoo

:""

:"mux mex mox \n ::::::::"</pre>

== Operator shuffling ==

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 too -- although I recommend adding parenthesis when something is possibly unclear.

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.

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.

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.

At the time of writing, the available operators - in order of precedence - are these:

* !
* ?
* $
* ~
* #
* **
* *
* /
* %
* +
* -
* <<
* >>
* <=>
* >
* <
* <=
* >=
* <>
* <>>
* ==
* !=
* ===
* =~
* !~
* &
* ^
* |
* &&
* ?&
* ||
* ?|
* ..
* ...
* =>
* <->
* ->
* +>
* !>
* &>
* %>
* #>
* @>
* />
* *>
* ?>
* |>
* ^>
* ~>
* ->>
* +>>
* !>>
* &>>
* %>>
* #>>
* @>>
* />>
* *>>
* ?>>
* |>>
* ^>>
* ~>>
* =>>
* **>
* **>>
* &&>
* &&>>
* ||>
* ||>>
* $>
* $>>
* +=
* -=
* **=
* *=
* /=
* %=
* and
* nand
* &=
* &&=
* ^=
* or
* xor
* nor
* |=
* ||=
* <<=
* >>=
* <-
* return

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.

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.

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.

== Assignment shuffling ==

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.

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:

<pre>foo = 1 + 2
=(foo, 1 +(2))

Ground foo *= "text"
Ground *=(foo, "text")

bar foo(123) = 42
bar =(foo(123), 42)

flux++
++(flux)</pre>

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 [http://{{SERVERNAME}}/#assignment assignment]. 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.

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.

The currently available assignment operators are:

* =
* ++
* --
* +=
* -=
* /=
* **=
* *=
* %=
* &=
* &&=
* |=
* ||=
* ^=
* <<=
* >>=
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.

== Inverted operators ==

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.

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:

<pre>"foo" :: [1, 2, 3, 4] map(asText)
;; will be translated to
[1, 2, 3, 4] map(asText) ::("foo")

;; provided we have an inverted
;; operator called 'doit'
abc foo quux doit another time
;; will be translated to
another time doit(abc foo quux)</pre>
=== Execution model ===

The way an Ioke program work 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 Ground. 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.

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 "foo bar(flux bar) quux" involves 5 different messages.

# The message "foo" is sent to Ground, which is the current ground and also the default receiver.
# The message "bar" is sent to the result of the "foo" message. The value returned will be activated.
# The cell "bar" contains a method in this case, and that method expects one argument, so that forces evaluation of the arguments.
# The message "flux" is sent to Ground, since it's the ground and there is no prior message inside of an argument list.
# The message "bar" is sent to the result of the "flux" message.
# The result of the "bar" message is used as the argument value given to the outside "bar" method.
# The message "quux" is sent to the result of the initial "bar" message.
# The result of the quux message is thrown away, unless this code is part of a larger piece of code.
This description generally describes what happens in the case of this code. The more general control flow is this:

# A message is encountered
# If the message is a symbol message, the corresponding symbol will be returned.
# Otherwise the name of the message will be looked up in the receiver, or in the receivers mimics.
# If the name is found and is not activatable, the value of that name (the cell) is returned.
# If the name is found and is activatable, it will be activated, with the current ground, receiver and message sent to the activatable object.
# If the name is not found, a second search is done for the name "pass". If a pass is found, use that instead of the name of the original message, and go back to 4.
# If a pass is not found, signal a Condition Error NoSuchCell condition.
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 [http://{{SERVERNAME}}/#code code]

Guide:Introduction

2009-01-26T00:15:23Z

Cv: /* Introduction */

= Introduction =

Ioke is a general purpose language. It is a strongly typed, extremely dynamic, prototype object oriented language. It is [http://en.wikipedia.org/wiki/Homoiconicity homoiconic] and its closest ancestors are [http://iolanguage.com Io], [http://www.smalltalk.org Smalltalk], [http://www.ruby-lang.org Ruby] and [http://en.wikipedia.org/wiki/Lisp_programming_language Lisp] - but it's quite a distance from all of them. It looks a lot like Io, to a limit.

Ioke is a ''folding'' 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.

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.

You're probably reading this guide at [http://ioke.org/guide.html ioke.org]. That is the official home of the project, although some of the project functionality is hosted at [http://ioke.kenai.org Kenai], where such things as mailing lists and a bug tracker is available. The canonical source repository for Ioke is on [http://github.org/olabini/ioke/tree/master GitHub].

The current version of Ioke is called [Ioke S]. The naming of Ioke will change regularly with major revisions. There are two different versions in play here. Ioke S is the name and version of the language and core libraries. The initial implementation for Ioke S is called <tt>ikj 0.2.0</tt>, and the version numbers are not interdependent. The next major version of Ioke will be called [Ioke E], and you can find information about it in the chapter on [[#Future_plans|future plans]].

This programming guide -- together with the reference for your current version -- should be the complete document needed to understand Ioke S, 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.

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 [[#Objects|Objects]], skim that bit, and then start over once words like ''Origin'', ''cell'' and ''mimic'' make sense.

== Vision ==

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.

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?

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.

Are still Lisp and Smalltalk 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.

Simplicity doesn't mean lack of power. Small, simple, orthogonal functionality can be more powerful than larger, complicated abstractions that don't fit together.

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.

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.

== Getting started ==

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 [http://ioke.org/download.html download page], and grab one of the distributions. At the time of writing the full version of Ioke is Ioke S ikj 0.2.0. Choose the latest download in the 0.2-series for this document to apply.

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.

=== Running scripts ===

To run an Ioke script, you can generally just use the <tt>ioke</tt> command:

<pre>$ ioke helloWorld.ik
Hello world</pre>

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:

<pre>$ ioke -e'"Hello world" println' -e'"Goodbye world" println'
Hello world
Goodbye world</pre>

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.

The <tt>ioke</tt> command has several helpful command line options, which can change what happens during execution. These are:

; -Cdirectory
: 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.
; -d
: Enable debug output.
; -e script
: Execute script, as describe above. May occur more than once on a command line.
; -h<br />
--help
: Display help information, including descriptions of these command line options.
; -Idirectory
: Add directory to the load path of Ioke. May occur more than once on a command line.
; -JjvmOptions
: 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.
; --copyright
: Print copyright information and exit.
; --version
: Print version information and exit
; --server
: Run the JVM in server Hotspot mode
; --client
: Run the JVM in client Hotspot mode (the default)
; --
: Mark the end of options to the <tt>ioke</tt> script, anything after this are options to be sent to the code running.
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.

=== Interactive mode ===

If no code to execute has been specified to the <tt>ioke</tt> script, [[IIk|IIk - Interactive Ioke]] - 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 [[Conditions|condition]] 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.

IIk will try to use Readline through JLine if your platform supports it.

IIk will be more closely described later, but just to give you a glimpse, this is how a small session could look like:

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

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.

Template:Main

2009-01-25T23:51:06Z

Cv:

:<div class="noprint">''Main article: [[{{{1}}}]]</div><noinclude>

== Usage ==

To link to a "main article" on a topic, use {{main|The other article}}.

== See also ==

* {{tl|Further}}

[[Category:Section templates|{{PAGENAME}}]]
[[Category:List templates|{{PAGENAME}}]]
</noinclude>

Template:Main

2009-01-25T23:50:26Z

Cv:

:<div class="noprint">''Main article: [[{{{1}}}]]</div>

<noinclude>
== Usage ==

To link to a "main article" on a topic, use {{main|The other article}}.

== See also ==

* {{tl|Further}}

[[Category:Section templates|{{PAGENAME}}]]
[[Category:List templates|{{PAGENAME}}]]
</noinclude>

Template:Main

2009-01-25T23:50:01Z

Cv:

:<div class="noprint">''Main article: [{{{1}}}]</div>

<noinclude>
== Usage ==

To link to a "main article" on a topic, use {{main|The other article}}.

== See also ==

* {{tl|Further}}

[[Category:Section templates|{{PAGENAME}}]]
[[Category:List templates|{{PAGENAME}}]]
</noinclude>