Guide:Libraries - Revision history

Cv: /* DokGen */

2009-01-26T00:41:06Z

‎DokGen

Cv: /* ISpec */

2009-01-26T00:36:59Z

‎ISpec

Cv: /* IIk */

2009-01-26T00:36:28Z

‎IIk

Cv: /* IIk */

2009-01-26T00:32:39Z

‎IIk

Cv: /* DokGen */

2009-01-25T23:40:09Z

‎DokGen

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

2009-01-25T23:23:31Z

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

New page

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

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

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.

← Older revision		Revision as of 00:41, 26 January 2009
Line 19:		Line 19:
	{{main\|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.	+	DokGen is the tool that is used to generate the reference documentation for Ioke, and it generates output similar to [http://rdoc.sourceforge.net/ RDoc]. Its goal is to be a general purpose tool for any Ioke application.

← Older revision		Revision as of 00:36, 26 January 2009
Line 8:		Line 8:

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

← Older revision		Revision as of 00:32, 26 January 2009
Line 4:		Line 4:

	== IIk ==		== 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 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.

← Older revision		Revision as of 23:40, 25 January 2009
Line 105:		Line 105:

	== DokGen ==		== 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.		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.

@@ Line 10: / Line 10: @@
 == 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.
 == DokGen ==