Documentation of ALICE

Part I Introduction

Alice is a application to create and execute language quizzes. A quiz can be as simple as a set of questions and answers however complex quizzes where alice calculates conjugations of language constructs (like verbs, adjectives ...) are also possible. When a quiz is run you can answer the questions by typing in the answer or choosing the answer from a multiple choice list. Statistics are also generated counting the number of correct answers, incorrect answers and the times you have used a hint.

I have developped Alice especially as a tool to help me learning Japanese, hence all the examples are about learning Japanese, however it as well suited to learn French, Dutch, English .... If you use Alice to create your own quizzes and want to share them with the world, please contact me via the Discussion Forum of SourceForge.

Alice itself is written in Clojure and thus runs on the Java Virtual Machine, meaning that a installation of Java is neccessary. Also if you have to input special characters (kanji, hiragana, katakana, ...) you are yourself responsible for the installation of the fonts, input method editor and so one.

Alice is hosted on Sourceforge see Alice. You can download Aice using the following link Alice Downloads. The following files are available:

File	Description
alice-0.1.tgz	Binary distribution for Linux
alice-0.1.msi	Binary distribution for Windows
alice.src.tgz	Leiningen source project
alice.doc.tgz	Lyx source code of the documentation

Installation instructions are in this document at Chapter 4 Getting Started.

Part II Concepts

Alice is based on the following conceptual objects:

0.1 Rules

A rule represent a question or answer in a quiz. There are two kind of rules :

0.1.1 Value rule

This rule represents fixed values that are associated with a question or answer. The cards that make up a quiz provides the values associated with the value rules, if we evaluate a value rule in the context of a card the value given in the card for the value rule is returned. A value rule consists of the following components:

Rule name:: This rule represents fixed values that are associated with a question or answer. The cards that make up a quiz provides the values associated with the value rules, if we evaluate a value rule in the context of a card the value given in the card for the value rule is returned. A value rule consist es of the following components.
Example of value:: Used in the definition of match rules to see the effect of applying a match rule.
Font size of rule:: Used in a test to specify the font size of the displayed value (needed for example to display in a readable format kanji, hiragana or katakana characters)

Example: The following are two value rules

English rule:
Japanese rule:

Cards for the quiz must then provide values for the English and Japanese rules, something like :

Card	Rule Name	Value
1	English	Mother
1	Japanese	おかあさん
2	English	Umbrella
2	Japanese	かさ

0.1.2 Match rule

This rule is used to represent conjugations of verbs, adjectives … . A match rule consists of the following components:

Rule name:

Used to identify the rule, must be unique. In a test this is displayed to indicate the question (providing information on which the answer must be based) or the answer that must be given.

Input rule:

The rule that provides the input value of the match-replace-destination operation.

Font size of rule:

Used in a test to specify the font size of the displayed value (needed for example to display in a readable format kanji, hiragana or katakana characters)

Match, replace and destination expressions:

Match: This is a regular expression (see regular expressions) that is used to search for a pattern in the value of the input rule.
Replace: This is the expression that replaced the pattern found in the input rule value using the match rule.
Destination: Specifies the result of the match rule, * represents the result of the match/replace operation, {rule name} represents a rule (value or match) and the other characters are used literally.

The algorithm used is the following: To calculate the value of a match rule in the context of a card we evaluate the input rule in the context of the card. Then we use in order the match expression of the match/replace/destination rules until we find a match expression that matches with a sub-string of the input value. Using this match/replace/destination rule we do a regular expression search and replace on the value of the input rule using match expression/replace expression producing the value for *. Finally replace in the destination every occurrence of * by the value of * and every {rule name} by the evaluated value of the rule with name rule name. The order of the match/replace/destination sub-rules is important in cases more matches are possible.

Example: Assume that we have two value rules ValueOne, ValueTwo with for card 1 the values 'Test' and Proef and that we have a match rule defined as follows:
Rule name:

MatchExample

Match expression:

s[Tt]$ (this matches with sT or st at the end of a string)

Replace expression:

xxx

Destination:

H*{ValueTwo}ello

The match rule the evaluated in the context of card nr 1 to HTexxxProefello

0.2 Question sets

Question sets define which of the rules should be used for questions, answers or should be hidden from the test (these rules are typically match rules used for calculating inter medium values like stems). One or more question sets can be defined, for a actual test for a card the question set that contains the most filled in answers will be used, typically question sets with all blank answers for a certain card will not be used. This allows to have different questions, answers for different cards (for example some cards are used as simple translations in a test, other cards give different conjugations of verbs).

0.3 Cards

Cards contains the values for the different value rules and provides a context to evaluate a rule in (value rules evaluates to the value on the card in the context of the card, match rules are calculated based on the evaluation of the value rules, the match, replace expressions and the destinations).

0.4 Quizzes

A quiz is the combination of rules, question sets and cards. It is the basis where a test is defined on.

0.5 Test sets

A test set defines a subset of the cards that is used for the test (so that a test does not have to use all the cards). We can create a test set based on one of the following:

All the cards

Cards using a given question set as the preferred question set

Cards in a range (defined by a start index and the nr of cards)

Cards with errors (where we define a range of errors between a minimum and maximum)

Part III User Manual

0.6 Menu structure

Part IV Getting started

0.7 Installing

0.7.1 Prerequirements

Alice is written in clojure and needs a java runtime to execute. Testing has been done using the Java 1.8 runtime. You can download the java runtime from the following locations if needed.

Open JDK a open source implementation of java
Official Oracle JRE the official java release at oracle.

If you create tests that needs special characters (like hiragana, katakana, kanji ...), make sure that you have installed the correct fonts and input method editors and knows how to use them.

0.7.2 Linux installation

0.7.2.1 Automatic installation on Linux

Download the alice-0.1.tgz file in a work directory.

cd to your work directory.

Extract the alice-0.1.tgz using tar -xvf alice-0.1.tgz.

Execute cd ./alice-0.1.tgz

Execute su to become super user, run then ./install.sh to install alice. The following screen will appear:

image: 14_home_marc_workspace_Alice_documentation_pasted15.png

with the following controls:

Installation directory:: The directory where alice will be installed (default /usr/local/alice). Use the (…) button to start a dialog box to choose the installation directory. If the installion directory already exists and has content during the installation, the installer will make a backup copy of the existing directory. The path of the backup copy is <installation directory>.n (where n=1,2,…).
Directory for executable:: The directory where the program that starts alice (see Application name), You should choose a directory that is in your PATH environment variable (like /usr/local/bin which is the default).
Application name:: The program name that you will use to start alice. If this file already exists in the directory for the executable, the installation program will make a backup of the executable with name <Application name>.n (where n=1,2,…).
Install:: The button to start the installation, when the installation is finished the button changes in a Finish button that you can press to finish the installation.

The following window will be displayed if you have successfully installed alice:

image: 15_home_marc_workspace_Alice_documentation_pasted16.png

From now on you can start Alice from the command prompt using the application name. If you want to add Alice to your menus you have to do it yourself using the instructions provided by your particular Linux system.

0.7.2.2 Manual installation on Linux

Download the the alice-0.1.tgz file in a work directory.

cd to your work directory.

Extract the alice-0.1.tgz using tar -xvf alice-0.1.tgz.

Execute cd ./alice-0.1.tgz

Create the installation directory of your choice using mkdir.

Copy the documents folder to your installation directory.

Copy the alice.jar file to your installation.

In a directory referenced by your PATH variable create a alice script containing the text java -jar <installation directory>/alice.jar -action RUN -install-dir -install-dir <installation directory>

Use chmod a+rx to give the alice script execution rights.

0.7.3 Installing on Windows

0.7.3.1 Automatic installation on windows

Download and run alice.msi.

The following screen appears, press Next to proceed, cancel to stop

image: 16_home_marc_workspace_Alice_documentation_pasted17.png

The following screen allows you to select the installation directory, press next to proceed, cancel to stop.

image: 17_home_marc_workspace_Alice_documentation_pasted18.png

If you get the following message, press the Yes button (I do not want to pay MS to be a know publisher).

image: 18_home_marc_workspace_Alice_documentation_pasted19.png

Finally press Finish on the following screen.

image: 19_home_marc_workspace_Alice_documentation_pasted20.png

0.7.3.2 Manual installing Alice on windows

Download and expand alice.zip.

Create a install directory in Program Files or Program Files (x86).

Copy the Documents folder from the expanded zip file to the installation directory.

Copy the alice.jar file to the install directory.

Make a shortcut of the alice.jar file on your desktop or in your start menu.

0.8 Creating a simple test using only value rules

The simplest way to create a quiz is use only value rules. This allows you to create a simple test that test translations of words from one language in another. Let's create a test that test for the translation of English words in Japanese words where we assume that one english word can have at a maximum 2 translations in Japanese. To do this follow the following steps:

Start alice.

Use File.New Quiz to create a new quiz, the following window will open

image: 20_home_marc_workspace_Alice_documentation_pasted21.png

Press the New value button (or press alt-v), the screen changes to

image: 21_home_marc_workspace_Alice_documentation_pasted22.png

Fill in the Rule name textbox with 'English' and Example of value with 'Mother', press the New value button again (alt-v). The screen changes to:

image: 22_home_marc_workspace_Alice_documentation_pasted23.png

Fill in the Rule name textbox with 'Japanese' and Example of value with 'おかあさん', press the New value button again (or alt-v).

Fill in the Rule name textbox with 'Japanese (...)' and Example of value with 'かさ'. You should end with the following screen:

image: 23_home_marc_workspace_Alice_documentation_pasted24.png

We have now created the value rules for or quiz. Use now the Quiz.Edit question sets(group rules in answers/questions) menu to divide the rules in answers and questions. The following screen appears:

image: 24_home_marc_workspace_Alice_documentation_pasted25.png

Select the 'English' rule and press add in Questions, select the 'Japanese' rule and press add in Answers and finally select the 'Japanse (...)' rule and press add in Answers. In the Type combobox select either All (all the answers must be correct but order can be different) or Some (at least one answer should be corretct). As 'Japanese' and 'Japanese (...) are on the same level (we just want to give two possible translations to a english word) Exact would be a wrong error. The result should look like the following:

image: 25_home_marc_workspace_Alice_documentation_pasted29.png

Next we create two cards for our quiz, so use the Quiz.Edit cards of quiz to get the following screen:

Fill in the English textbox with 'Mother', the Japanese textbox with 'おかあさん' and the Japanese (...) textbox with 'はは' (an alternative translation for mother). Press the Create button to create the next card. Fill in the English textbox with 'Umbrella' and the Japanese textbox with 'かさ', do not fill in the Japanese (...) textbox (we have only one translation). Experiment with the Previous/Next to scroll forwards/backwards through the list of parts. The final screen should be like:

image: 27_home_marc_workspace_Alice_documentation_pasted28.png

Next create a test set containing all the cards you have created, using Quiz.Edit Test Set. This is enogh to include all the cards in the test.

Next use Test.Do the test to test out the test that you have just created.

0.9 Creating a complex test using match rules

As a example of a complex test using match rules we create a quiz that can be used to conjugate japanese verbs in the masu form. First we create the value rules to base the match rules on. So use the menu File.New quiz and create the following value rules (see previous section for instructions how to do this)

Rule Name	Example of value	Font size of rule
English		13
Dictionary		13

The screen should look something like:

image: 28_home_marc_workspace_Alice_documentation_pasted30.png

Now use the following steps to create the match rules for the conjugation.

Create the match rules for the stem of Yodan verbs. So press New Match (or alt-m) to create a match rule.

Fill in the Rule name: textbox with Yodan, choose Dictionary for the Input Rule and 13 for the Font size of rule.

Fill in the Match expression: with [うつるくぐすぬむぶ] followed by $ (make sure that your input method editor is not in Japanese when you do this), leave the Replace expression empty and fill in * in the Destination. This match/replace/destination combination will remove the trailing う of a Dictionary value. You can test this by typing in かう in the Test input text field and pressing the Test rule button, the Result test should display か.

you should end with the following screen

image: 29_home_marc_workspace_Alice_documentation_pasted31.png

Next we create the match rule for the stem of Ichidan verbs, so press the New Match button and fill in Rule name: with Ichidan, choose 'Dictionary' for the Input rule: and 13 for Font aice of rule. Next fill in 'える$' for the Match expressioon (again make sure that for $ you do not use the input method editor of Japanese characters), fill in 'え' for the Replace expression and '*' for the Destination textbox.

Press the New button to create a new Match/Replace/Destiantion sub-rule. Use now a combination of (5) and (6) to create the following Match/Replace/Destination sub-rules
.

Match	Replace	Destination	Description
える$	え	*	Replace える at end by え
いる$	い	*	Replace いる at end by い
ける$	け	*	Replace ける at end by け
げる$	げ	*	Replace げる at end by げ
きる$	き	*	Replace きる at end by き
ぎる$	ぎ	*	Replace ぎる at end by ぎ
へる$	く	*	Replace へる at end by へ
べる$	ぐ	*	Replace べる at end by べ
ぺる$	ぷ	*	Replace ぺる at end by ぷ
ひる$	ひ	*	Replace ひる at end by ひ
びる$	ぶ	*	Replace びる at end by び
ぴる$	ぷ	*	Replace ぴる at end by ぴ
せる$	せ	*	Replace せる at end by せ
ぜる$	べ	*	Replace ぜる at end by げ
しる$	し	*	Replace しる at end by し
じる$	じ	*	Replace じる at end by じ
ねる$	ね	*	Replace ねる at end by ね
にる$	に	*	Replace にる at end by に
てる$	て	*	Replace てる at end by て
でる$	で	*	Replace でる at end by で
ちる$	ち	*	Replace ちる at end by ち
める$	ぬ	*	Replace める at end by め
みる$	み	*	Replace みる at end by み
りる$	り	*	Replace りる at end by り
れる$	れ	*	Replace れる at end by れ

You should have a window looking as follows

image: 30_home_marc_workspace_Alice_documentation_pasted36.png

Next we construct the Base 2 of Yodan verbs, so repeat (5)-(6) to create a match rule with Rule Name: 'Yodan Base 2', Input Rule: 'Dictionary', Font size of rule 13 and sub-rules based on the following table

Match	Replace	Destination	Description (note Yodan has removed matching char)
う$		{Yodan}い	Replace う by い
つ$		{Yodan}ち	Replace つ by ち
る$		{Yodan}り	Replace る by り
く$		{Yodan}き	Replace く by き
ぐ$		{Yodan}ぎ	Replace ぐ by ぎ
す$		{Yodan}し	Replace す by し
ぬ$		{Yodan}に	Replace ぬ by に
む$		{Yodan}み	Replace む by み
ぶ$		{Yodan}び	Replace ぶ by び

Next we construct the Base 2 of Ichidan verbs, so repeat (5)-(6) to create a match rule with Rule Name: 'Ichidan Base 2', Input Rule: 'Dictionary', Font size of rule 13 and a sub-rule with Match expression: [えいけげきぎへべぺひびぴせぜしじねにてでちめみりれ]る$, Replace expression: '' and Destination '{Ichidan}

Next we create the Base 2 of all verbs (taking in account that かえる and はいる are actual Yodan verbs. Repeat (5)-(6) to create a match rule with Rule Name: 'Base 2', Input rule: 'Dictionary', Font size of rule 13 and the following sub-rules

Match	Repl.	Dest.
かえる		{Yodan Base 2}
はいる		{Yodan Base 2}
[えいけげきぎへべぺひびぴせぜしじねにてでちめみりれ]る$		{Ichidan Base 2}
.		{Yodan Base 2}