Developers

Num-Num^TM Developer's Page

Greetings

Either you've arrived here by accident or else your morbid curiosity for the Number Spelling Language has brought you here. If you got here by accident, click here to leave and find out what the fuss is all about. Otherwise, read on.

The Development Process

If you're interested in developing and submitting rules for a language that's not on the list of already submitted languages, or else you would like to correct a bug in one of these rules, then you'll need to learn the development process. This development process consists of:

learning how to create rules
downloading a development kit which allows you to create, refine and test your rules
submitting your rules back to me

These topics are covered in the following sections.

Note: The licensing terms of this program do not require you to submit new and modified rules back to me, but you'll get listed on the website if you do and will also get a mental pat on the back from me. What's more, your rules will automatically run on all supported platforms and you can put what you want in the Notes field.

The Rules Language

Some Terminology

First, some terminology. For a given input number n and format f, let's call the result of applying the rules to n using f spell(n,f). Keep in mind that:

-999999999999 <= n <= 999999999999.

Here are some examples:

`n`	`f`	`spell(n,f)`
`38`	`Cardinal`	`thirty eight`
`38`	`Year`	`thirty eight`
`38`	`Currency`	`thirty eight dollars`
`1967`	`Cardinal`	`one thousand nine hundred sixty seven`
`1967`	`Year`	`nineteen sixty seven`
`1967`	`Currency`	`one thousand nine hundred sixty seven dollars`
`5.1`	`Cardinal`	`five point one`
`5.1`	`Currency`	`five dollars and ten cents`

Rules File Syntax

Here is a guide to deciphering the rules. Consult the English rules as you read this.

Note: The rules file is limited to a maximum of 4000 characters.

The first six lines contain the following descriptive information:

/@-CheckMate:language name
negative number indicator
singular currency unit/plural currency unit
singular currency hundredths unit/plural currency hundredths unit
translation for "and"
translation for "point"
notes

If the fourth or fifth lines (pertaining to currency) are left blank, then the indicator is suppressed in the output number (cf. italiano.yn).

The notes line may contain linefeed escape sequences ("\n") which are translated to implementation-dependent newline characters. Use this field to describe yourself and any particularities of the rules. Limit the text to 290 characters.

The remaining lines contain the transformation rules, one per line.

Fractional Numbers

Values with decimal places are split into pieces depending on the format f, and the number evaluator is applied to each piece. Let's take the number 19.52, for example. Here is how the number is split depending on the format:

`f`	`Procedure`
`Cardinal`	`spell(19,f) translation for "point" spell(5,f) spell(2,f) (i.e. "nineteen point five two"`
`Money`	`spell(19,f) plural currency unit translation for "and" spell(52,f) plural currency hundredths unit (i.e. "nineteen dollars and fifty two cents")`

Each transformation rule line has the following form.

conditions:expressions

The lines are evaluated from top to bottom. For values of n and f, if conditions(n,f) holds true, then spell(n,f) is expressions(n,f).

conditions(n,f)

Conditions may be strung together in the form:

c1&c2&c3... This means "if c1 and c2 and c3". Let's call each unitary condition a condition(n,f). Here are the possible syntaxes for condition(n,f) and their associated meanings:

`Syntax`	`Meaning`	`Example(s)`
`<k>`	`if n=k k is a numeric constant`	`<20>`
`{k1-k2}`	`if k1<=n<=k2 k1 and k2 are numeric constants`	`{0-19}`
`[p1 p2]`	`if any of the digits in places p1 through p2 are not 0. Places are numbered from right to left starting at 1`	`[12-10] meaning: "if this number has a billions, 10 billions or 100 billions digit"`
`\|p1 p2\|`	`if all of the digits in places p1 through p2 are 0. Places are numbered from right to left starting at 1.`	`\|2 1\| meaning: "if this number is an even multiple of 100"`
`=(place_expr,k)`	`if place_expr(n)=k k is a numeric constant`	`=([1 1],1) meaning: if the ones digit is 1 (true for n=21, false for n=22) =((6 6),1) meaning: if the hundred thousands digit is 1 (true for n=3145339, false for n=1312039)`
`+letter`	`if register letter is set (letter is A to Z)`	`+P`
`~letter`	`if register letter is not set (letter is A to Z)`	`~P`
`N`	`if f is Cardinal`	`N`
`D`	`if f is Year`	`D`
`M`	`if f is Currency`	`M`
`O`	`if f is Ordinal`	`O`
`L`	`if we are currently evaluating the left of the decimal point`	`L`
`R`	`if we are currently evaluating the left of the decimal point`	`R`

place_expr(n)

a place_expr is of the form [p1 p2] or (p1 p2). place_expr(n) evaluates to a number m which must be in the range 0 <= m <= 999, otherwise the expression will evaluate to -1.

`Syntax`	`Meaning`	`Example(s)`
`[p1 p2]`	`n with all digits set to 0 but the ones from p1 to p2. Digits are numbered from right to left starting at 1.`	`[3 1] applied to 3897492 evaluates to 492`
`(p1 p2)`	`n with all digits set to 0 but the ones from p1 to p2, with the resultant number shifted right p2-1 places. Digits are numbered from right to left starting at 1.`	`(6 4) applied to 3897492 evaluates to 897`

expressions(n,f)

As mentioned above, if condition(n,f) holds true, then the expressions portion of the transformation rule is invoked. expressions(n,f) evaluates to a string.

Expressions are strung together in the form e1e2e3. Let's call each unitary expression an expression(n,f). Here are the possible syntaxes for expression(n,f) and their associated meanings:

`Syntax`	`Meaning`	`Example(s)`
`place_expr`	`spell(place_expr(n),f)`	`(4 3) applied to 432571 evaluates to spell(25,f)`
`-(place_expr,k)`	`spell(place_expr(n) minus k,f) k is a numeric constant`	`-([2 1],60)` `applied to 432571 evaluates to spell(11,f)`
`"literal"`	`evaluates to the literal string literal`	`"twenty"`
`{literal₁,literal₂,...literal_n}`	`evaluates to the n+1th string. only allowable for conditions of the form{k1-k2}`	`{zéro,un,deux,trois} applied to 2 evaluates to "deux"`
`+letter`	`set register letter (letter is A to Z)`	`+P`
`~letter`	`reset register letter (letter is A to Z)`	`~P`

Registers

The number evaluator uses twenty-six boolean registers named A to Z. These are initially reset (i.e. set to false) at the onset of the evaluation of each number piece. You can set/reset a register in the expression portion of a rule and test a register in the condition portion of a rule.

Getting and Using The Development Kit

To use the the development kit, you must have a Java Runtime Environment that supports the JDK 1.1 or greater. Both Sun's JDK 1.1 and Java 2 environments as well as Microsoft's Virtual Machine for Java satisfy this requirement. You can also give IBM's implementation a try, though I haven't tested it.

If you're running on a Win32 (Win9x, WinNT4, Win2000) system and are using Microsoft Internet Explorer, there's a good chance you already have Microsoft's Virtual Machine installed. To verify this, drop to a command prompt and type jview. If you get output, then you have it installed. You might want to double-check at Microsoft's site to ensure that you have the latest version, as older versions have bugs. Alternatively, connect to the internet, fire up Internet Explorer and choose Help/Product Updates and see if a newer version of the virtual machine is available.

Once you have a virtual machine, download the development kit. This consists of a single .jar file. It the same .jar file used for the applet on the previous page. Right-click on this link and choose Save Target As... (IE) or Save Link As... (NS) from the popup menu:

Right-click here to download YourNumber.jar

This .jar file has two main classes. Once is a console application and the other is a GUI application. The console application submits your rules to an automated battery of tests and lets you consult these test results in a text file. The GUI application is similar to the applet on the previous page, but has additional [Load] and [Save] buttons in the Rules dialog box which allow loading and saving your rules. As such, the development process consists of the following steps:

develop your rules and save them to a text file
run the console application and verify that your rules are correct
run the GUI application and do some further tests

Running the Console Application

To run the console application, first ensure that you have saved your rules to a text file. Then drop to a command prompt, change to the directory of YourNumber.jar and type this for Sun's VM:

java -classpath YourNumber.jar ConsoleTest <rules file path> <output file> [JDK 1.2.x]

java -classpath <full path to classes.zip>;YourNumber.jar ConsoleTest <rules file path> <output file> [JDK 1.1.x]

or this for Microsoft's VM:

jview /cp YourNumber.jar ConsoleTest <rules file path> <output file>

Running the GUI Application

To run the GUI application, you can double-click on the .jar file from a file explorer (Sun's JDK 1.2 or greater on Win32 or Solaris only) or else type the following at the command prompt:

Sun's VM:

javaw -jar YourNumber.jar [JDK 1.2.x]

javaw -classpath <full path to classes.zip>;YourNumber.jar YourNumber [JDK 1.1.x]

Microsoft's VM:

wjview /cp YourNumber.jar YourNumber

(Note that we are typing javaw/wjview instead of java/jview.)

Submitting Your Rules to Me

If you feel like submitting any new or modified rules back to me, send a text file attachment to info@thisiscool.com and provide the following pieces of information. (I cannot accept any information which doesn't include this information.)

your full name, mailing address and email address (these will not be published, divulged or used - they will only be kept on file in case legal issues concerning your rules arise)
the language these rules are for
an indication of whether you want your name published on the website
a URL you would like me to link to for your author's name, if any
the following affirmation: I (your name) affirm that I am the original author of these rules or else that I am authorized to submit these rules because they are derived from <xxx>. I allow unrestricted reproduction, distribution and modification of these rules.

Important note: I will only publish rules which pass ConsoleTest without throwing any exceptions.