Gregory Martin Pfeil This chapter describes the context-free grammars used in this specification to define the lexical and syntactic structure of a program.

A context-free grammar consists of a number of productions. Each production has an abstract symbol called a nonterminal as its left-hand side, and a sequence of one or more nonterminal symbols as its right-hand side. For each grammar, the terminal symbols are drawn from a specified alphabet.

A lexical grammar for the Reykjavík programming language is given in (§3). This grammar has as its terminal symbols the characters of the Unicode character set. It defines a set of productions, starting from the goal symbol Input (§3.5), that describe how sequences of Unicode characters (§3.1) are translated into a sequence of input elements (§3.5). These input elements, with white space (§3.6) and comments (§3.7) discarded, form the terminal symbols for the syntactic grammar for the Reykjavík programming language and are called tokens (§3.5). These tokens are the identifiers (§3.8), keywords (§3.9), literals (§3.10), separators (§3.11), and operators (§3.12) of the Reykjavík programming language.

The syntactic grammar for the Reykjavík programming language is given in Chapters 4, 6-10, 14, and 15. This grammar has tokens defined by the lexical grammar as its terminal symbols. It defines a set of productions, starting from the goal symbol CompilationUnit (§7.3), that describe how sequences of tokens can form syntactically correct programs.

Terminal symbols are shown quoted in fixed width font in the productions of the lexical and syntactic grammars, and throughout this specification whenever the text is directly referring to such a terminal symbol. These are to appear in a program exactly as written. Nonterminal symbols are shown in italic type. The definition of a nonterminal is introduced by the name of the nonterminal being defined followed by a quadrathorpe. The right-hand side for the nonterminal then follows. For example, the syntactic definition: states that the nonterminal IfThenStatement represents the token if, followed by a colon token, followed by an Expression, followed by a end-of-line token, followed by Statements. As another example, the syntactic definition: states that a Throws may represent either a single Exception to allow or an Exception followed by any number of the group comma-Exception. The right-hand side of a lexical production may specify that certain expansions are not permitted by using the phrase “but not” and then indicating the expansions to be excluded, as in the productions for InputCharacter (§3.4) and Identifier (§3.8): InputCharacter UnicodeInputCharacter - (CR | LF) Identifier IdentifierName - (Keyword | BooleanLiteral | NullLiteral)

This chapter specifies the lexical structure of the Reykjavík programming language. Programs are written in Unicode (§3.1), but lexical translations are provided (§3.2) so that Unicode escapes (§3.3) can be used to include any Unicode character using only ASCII characters. Line terminators are defined (§3.4) to support the different conventions of existing host systems while maintaining consistent line numbers. The Unicode characters resulting from the lexical translations are reduced to a sequence of input elements (§3.5), which are white space (§3.6), comments (§3.7), and tokens. The tokens are the identifiers (§3.8), keywords (§3.9), literals (§3.10), separators (§3.11), and operators (§3.12) of the syntactic grammar.

Programs are written using the Unicode character set. Information about this encoding may be found at http://www.unicode.org/. All versions of the Reykjavík programming language use Unicode version 2.1. The Reykjavík platform will track the Unicode specification as it evolves. The precise version of Unicode used by a given release is specified in the documentation of the class Character. Except for comments (§3.7), identifiers, and the contents of character and string literals (§3.10.4, §3.10.5), all input elements (§3.5) in a program are formed only from ASCII characters (or Unicode escapes (§3.3) which result in ASCII characters). ASCII (ANSI X3.4) is the American Standard Code for Information Interchange. The first 128 characters of the Unicode character encoding are the ASCII characters.

A raw Unicode character stream is translated into a sequence of tokens, using the following three lexical translation steps, which are applied in turn: A translation of Unicode escapes (§3.3) in the raw stream of Unicode characters to the corresponding Unicode character. A Unicode escape of the form \uxxxx, where xxxx is a hexadecimal value, represents the Unicode character whose encoding is xxxx. This translation step allows any program to be expressed using only ASCII characters. A translation of the Unicode stream resulting from step 1 into a stream of input characters and line terminators (§3.4). A translation of the stream of input characters and line terminators resulting from step 2 into a sequence of input elements (§3.5) which, after white space (§3.6) and comments (§3.7) are discarded, comprise the tokens (§3.5) that are the terminal symbols of the syntactic grammar (§2.3). The longest possible translation is used at each step, even if the result does not ultimately make a correct program while another lexical translation would. Thus the input characters a--b are tokenized (§3.5) as a, --, b, which is not part of any grammatically correct program, even though the tokenization a, -, -, b could be part of a grammatically correct program.

Implementations first recognize Unicode escapes in their input, translating the ASCII characters \u followed by four hexadecimal digits to the Unicode character with the indicated hexadecimal value, and passing all other characters unchanged. This translation step results in a sequence of Unicode input characters: UnicodeInputCharacter UnicodeEscape | RawInputCharacter UnicodeEscape "\", UnicodeMarker, 4 * HexDigit UnicodeMarker "u" RawInputCharacter any Unicode character HexDigit OctalDigit | "8" | "9" | "a" | "b" | "c" | "d" | "e" | "f" | "A" | "B" | "C" | "D" | "E" | "F" In addition to the processing implied by the grammar, for each raw input character that is a backslash \, input processing must consider how many other \ characters contiguously precede it, separating it from a non-\ character or the start of the input stream. If this number is even, then the \ is eligible to begin a Unicode escape; if the number is odd, then the \ is not eligible to begin a Unicode escape. For example, the raw input \\u2297=\u2297 results in the eleven characters \u2297=⊗ (\u2297 is the Unicode encoding of the character ⊗). If an eligible \ is not followed by u, then it is treated as a RawInputCharacter and remains part of the escaped Unicode stream. If an eligible \ is followed by u, or more than one u, and the last u is not followed by four hexadecimal digits, then a compile-time error occurs. The character produced by a Unicode escape does not participate in further Unicode escapes. For example, the raw input \u005cu005a results in the six characters \ u 0 0 5 a, because 005c is the Unicode value for \. It does not result in the character Z, which is Unicode character 005a, because the \ that resulted from the \u005c is not interpreted as the start of a further Unicode escape. Implementations should use the \uxxxx notation as an output format to display Unicode characters when a suitable font is not available.

Implementations next divide the sequence of Unicode input characters into lines by recognizing line terminators. This definition of lines determines the line numbers produced by a Reykjavík compiler or other system component. It also specifies the termination of the // form of a comment (§3.7). LineTerminator LF | CR | (CR, LF) Lines are terminated by the ASCII characters CR, or LF, or CR LF. The two characters CR immediately followed by LF are counted as one line terminator, not two. The result is a sequence of line terminators and input characters, which are the terminal symbols for the third step in the tokenization process.

The input characters and line terminators that result from escape processing (§3.3) and then input line recognition (§3.4) are reduced to a sequence of input elements. Those input elements that are not white space (§3.6) or comments (§3.7) are tokens. The tokens are the terminal symbols of the syntactic grammar (§2.3). This process is specified by the following productions: Input {InputElement} [Sub] InputElement WhiteSpace | Comment | Token Token Identifier | Keyword | Literal | Separator | Operator Sub SUB White space (§3.6) and comments (§3.7) can serve to separate tokens that, if adjacent, might be tokenized in another manner. For example, the ASCII characters - and = in the input can form the operator token -= (§3.12) only if there is no intervening white space or comment. As a special concession for compatibility with certain operating systems, the ASCII SUB character (\u001a, or control-Z) is ignored if it is the last character in the escaped input stream. Consider two tokens x and y in the resulting input stream. If x precedes y, then we say that x is to the left of y and that y is to the right of x. For example, in this simple piece of code: class Empty end class we say that the “end” token is to the right of the “Empty” token, even though it appears, in this two-dimensional representation on paper, downward and to the left of the “Empty” token. This convention about the use of the words left and right allows us to speak, for example, of the right-hand operand of a binary operator or of the left-hand side of an assignment.

White space is defined as the ASCII space, horizontal tab, and form feed characters, as well as line terminators (§3.4).

There is only one kind of comment. Reykjavík has no concept of multi-line, traditional, comments. Most uses of such comments involve putting a column of stars down the left-hand side to maintain continuity. This is a good practice, but makes multi-line comments redundant. Another use is mid-line or mid-statement comments, which are evil, plain and simple. The only remaining use is commenting out blocks of code. It is reasonable to expect editors to be able to comment out blocks, and IDEs to be able to dynamically disable blocks. # This is a comment this is not # this is another comment There are also documentation-style comments. To generate documentation from your comments, follow the # with a *, then all the comments up to the first non-comment is documentation. # no documentation here # #* now we’re documenting # still documenting # # yep, even here # no more documenting These comments are formally specified by the following productions: The lexical grammar implies that comments do not occur within character literals (§3.10.4) or string literals (§3.10.5).

An identifier is an unlimited-length sequence of letters and digits, the first of which must be a letter. An identifier cannot have the same spelling (Unicode character sequence) as a keyword (§3.9), boolean literal (§3.10.3), or the null literal (§3.10.7). IdentifierName Letter, {Letter | Digit} Letter Any character identified by the Unicode standard as a letter Digit Any character identified by the Unicode standard as a digit Letters and digits may be drawn from the entire Unicode character set, which supports most writing scripts in use in the world today, including the large sets for Chinese, Japanese, and Korean. This allows programmers to use identifiers in their programs that are written in their native languages. A Reykjavík letter is a character for which the method Character.isIdentifierStart returns true. A Reykjavík letter-or-digit is a character for which the method Character.isIdentifierPart returns true. The Reykjavík letters include uppercase and lowercase ASCII Latin letters A–Z (\u0041–\u005a), and a–z (\u0061–\u007a), and, for historical reasons, the ASCII underscore (_, or \u005f) and dollar sign ($, or \u0024). The $ character should be used only in mechanically generated source code or, rarely, to access preexisting names on legacy systems. The Reykjavík digits include the ASCII digits 0-9 (\u0030–\u0039). Two identifiers are the same only if they are identical, that is, have the same Unicode character for each letter or digit. Identifiers that have the same external appearance may yet be different. For example, the identifiers consisting of the single letters LATIN CAPITAL LETTER A (A, \u0041), LATIN SMALL LETTER A (a, \u0061), GREEK CAPITAL LETTER ALPHA (A, \u0391), and CYRILLIC SMALL LETTER A (a, \u0430) are all different. Unicode composite characters are different from the decomposed characters. For example, a LATIN CAPITAL LETTER A ACUTE (Á, \u00c1) could be considered to be the same as a LATIN CAPITAL LETTER A (A, \u0041) immediately followed by a NON-SPACING ACUTE (´, \u0301) when sorting, but these are different in identifiers. See The Unicode Standard, Volume 1, pages 412ff for details about decomposition, and see pages 626–627 of that work for details about sorting. Examples of identifiers are: String i3 areth MAX_VALUE isLetterOrDigit

The following character sequences, formed from ASCII letters, are reserved for use as keywords and cannot be used as identifiers (§3.8): Keyword "abstract" | "accessor" | "attribute" | "case" | "catch" | "class" | "constructor" | "default" | "destructor" | "else" | "end" | "exclusive" | "finally" | "generic" | "if" | "internal" | "loop" | "method" | "our" | "readonly" | "return" | "self" | "super" | "switch" | "throw" | "throws" | "variable" | "writeonly" While true and false might appear to be keywords, they are technically Boolean literals (§3.10.3). Similarly, while null might appear to be a keyword, it is technically the null literal (§3.10.7).

A literal is the source code representation of a value of type Integer, Real, Boolean, Character (§4.2), String (§4.3.3), or Null (§4.1): Literal IntegerLiteral | RealLiteral | BooleanLiteral | CharacterLiteral | StringLiteral | NullLiteral

See §4.2.1 for a general discussion of the integer types and values. An integer literal may be expressed in decimal (base 10), hexadecimal (base 16), or octal (base 8): IntegerLiteral LocalIntegerLiteral | HexIntegerLiteral | OctalIntegerLiteral A local integer literal consists of any number of related Unicode digits. For example, in the decimal Arabic system, a numeral consists of one or more ASCII digits from 0 to 9, representing a positive integer: LocalIntegerLiteral Any number of related Unicode digits A hexadecimal numeral consists of the leading ASCII characters 0x or 0X followed by one or more ASCII hexadecimal digits and can represent a positive, zero, or negative integer. Hexadecimal digits with values 10 through 15 are represented by the ASCII letters a through f or A through F, respectively; each letter used as a hexadecimal digit may be uppercase or lowercase. HexIntegerLiteral "0", "x" | "X", {HexDigit}- An octal numeral consists of the leading ASCII characters 0o or 0O followed by one or more of the ASCII digits 0 through 7 and can represent a positive, zero, or negative integer. OctalIntegerLiteral "0", "o" | "O", {OctalDigit}- OctalDigit "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7"

See §4.2.3 for a general discussion of the real types and values. A real literal has the following parts: a whole-number part, a decimal point (represented by an ASCII period character), a fractional part, and an exponent. The exponent, if present, is indicated by the ASCII letter e or E followed by an optionally signed integer (real?). At least one digit, in either the whole number or the fraction part, and either a decimal point, or an exponent are required. All other parts are optional. RealLiteral ({Digit}-, ".", {Digit}, [Exponent]) | (".", {Digit}-, [Exponent]) | ({Digit}-, Exponent) Exponent ExponentIndicator, SignedInteger ExponentIndicator "e" | "E" SignedInteger [Sign], LocalIntegerLiteral Sign "+" | "-" The details of proper input conversion from a Unicode string representation of a real number to the internal IEEE 754 binary floating-point representation are described for the constructor reykjavik.Real.from:(String). Examples of real literals: 1e1 2. .3 3.14 6.022137e+23

The Boolean type has two values, represented by the literals true and false, formed from ASCII letters. A boolean literal is always of type Boolean. BooleanLiteral "true" | "false"

Object does not provide the Convertible{String} interface (which would be comparable to Java’s toString method), the Convertible{String} interface should only be implemented by classes that have a valid string representation. There is a kind of toString method provided by Object, and that is the dump method. This method creates a string holding a hierarchical tree of the data in the instance. Here is an example of the output: (Uri) homepage (String) scheme = “http” (String) schemeSpecificPart = null (String) fragment = “foo” (String) authority = null (String) path = “/pfeilgm/Projects/Reykjavik” (String) query = null (String) userinfo = “test:pass” (String) host = “technomadic.org” (PositiveInteger) port = 8080 All of the “magic” types (Integer, String, Reference, Boolean, File, etc.) display a “= ‹value›”, rather than further hierarchical data, which would begin to get ugly and address-looking.

All classes can be versioned. Every public class should be versioned. A version has three parts a major number, a minor number, and a revision. In Reykjavík, the numbers are called compatibility, equivalency, and identity. This is to make their purpose more clear. If two classes have the same compatibility number, they are compatible; if they have the same compatibility and equivalency numbers, they are equivalent; and if they have the same compatibility, equivalency, and identity numbers, they are identical. Each number may be incremented according to certain rules. Any change that does not affect the public interface at all should increment the revision. Any change that adds methods, weakens a pre condition, strengthens a post condition, or deprecates methods should increment the minor number and reset the revision to zero. Any change that removes methods, strengthens a pre condition, or weakens a post condition should increment the major number and reset both the minor number and the revision to zero. Classes can be imported by version, or the library they are a part of should be indicated by version. When importing, only the major and minor numbers are used. The major number of the imported class must exactly match the major number in the import statement. The minor number of the imported class must be greater than or equal to the minor number in the import statement. Any library has its version incremented identically to the most-significantly-changed class. If the most significant change was an identity change, then the library's identity number is incremented. If the most significant change to a class was a compatibility change, than the compatibility number is incremented. This ensures that library versions change only as significantly as required. Of course, automatic versioning can only handle changes to the class interface. Changes to your database schemas or file formats or anything else must be handled manually. It’s possible to manually increment the class version, and this should definitely be done before making a versioned library, so the library’s version is incremented correctly.

A class declaration may include class modifiers.

An abstract class is a class that is incomplete, or to be considered incomplete. Only abstract classes may have abstract methods (§8.4.3.1, §9.4), that is, methods that are declared, but not yet implemented. If a class that is not abstract contains an abstract method, then a compile-time error occurs. A class C has abstract methods if any of the following is true: C explicitly contains a declaration of an abstract method (§8.4.3). Any of C’s superclasses declares an abstract method that has not been implemented (§8.4.6.1) in C or any of its superclasses. In the example: abstract class Point Integer x = 1 Integer y = 1 public method move,RightBy: (Integer) x UpBy: (Integer) y self.x += x self.y += y self.alert end method public abstract method alert end class abstract class ColoredPoint implements Point Integer color end class class SimplePoint implements Point public method alert end method end class a class Point is declared that must be declared abstract, because it contains a declaration of an abstract method named alert. The subclass of Point named ColoredPoint inherits the abstract method alert, so it must also be declared abstract. On the other hand, the subclass of Point named SimplePoint provides an implementation of alert, so it need not be abstract. A compile-time error occurs if an attempt is made to create an instance of an abstract class using a class instance creation expression (15.9). Thus, continuing the example just shown, the statement: Point p = Point.create would result in a compile-time error; the class Point can not be instantiated because it is abstract. However, a Point variable could correctly be initialized with a reference to any subclass of Point, and the class SimplePoint is not abstract, so the statement: Point p = SimplePoint.create would be correct. A subclass of an abstract class that is not itself abstract may be instantiated, resulting in the execution of a constructor for the abstract class and, therefore, the execution of the field initializers for instance variables of that class. Thus, in the example just given, instantiation of a SimplePoint causes the default constructor and field initializers for x and y of Point to be executed.

Reykjavík does not have the concept of a “final” class. Any class can be extended.

This is like inheritance, but not quite. It’s the C++ “explicit” keyword done correctly. Convertible{} allows implicit conversions between types that, while they may be conceptually related, have different storage mechanisms. In C++ this feature was automatically on for any constructor with a single argument unless the “explicit” keyword was used. To make this a bit safer, Reykjavík turns it off by default, and you must implement Convertible{} to allow an implicit conversion. Since inheritance is otherwise handled by the subclass (containing information on which classes are superclasses), it seemed natural that this should be handled at the “subclass” level as well, unlike the C++ style of handling it in the “superclass’” constructor. This also helps to make a few other aspects a bit clearer. The convertTo{} method, provided by Convertible{} does not throw any exceptions. It should only be implemented when a conversion is true and complete. True means that there is a relationship between the classes, not just because you can. For instance, it’s common to implement Convertible{String}, but it should be implemented for a string representation, like in the Uri class, not in order to dump the structure of the class (which should use the Object.dump method). Complete means that every possible instance must cleanly convert to an object of the Convertible specialization type. It can not return null, and it can not throw any exceptions. These restrictions work to help make this an effective additional type of inheritance.

Methods look like this: [public|private] [variable|exclusive] [class] method ([variable|copy]) name,formalparameters throws exception requires booleanstatements ensures booleanstatements body statements catch: (type) e statements end method

Formal parameters have the following syntax: label: (type) name [= default]

Since we have labeled parameters and they are allowed to be re-ordered, the signature will have them stored in Unicode order. The signature consists of the method name, plus the list of parameter labels and types.

The default visibility is identical to C++’s protected visibility.

This is identical to C++’s public visibility.

This is identical to C++’s private visibility.

This is identical to the abstract modifier in Java.

This is identical to the static modifier in Java.

The default mutability is identical to C++’s const methods. By providing modifiers to handle mutability, we get a lot of free code, and even some nifty features that you couldn’t code without multiple inheritance. Here is an example of a standard single-inheritance OO hierarchy that tries to provide immutable, mutable, and thread-safe versions of a class and one of its subclasses: You can see how, without multiple inheritance, the implementation falls short. However, with the modifiers presented herein, the following implementation: provides us with a flexible structure, mimicked by the following hierarchy:

If a method writes to data members or calls other variable methods, it must be declared variable. If such a method is not declared variable, the compiler will throw an error. This allows mutable access to objects, which is the default way objects are returned from methods. Methods that are not required to be variable, should not be variable.

This acts as a flag that is triggered whenever a thread-safe version of a class is requested. By default, this flag does nothing, but if a thread-safe instance is requested, all the methods with the exclusive flag are given exclusive access. This prevents the Vector/ArrayList dichotomy that afflicts Java and obviates the NSArray/NSMutableArray structure in Objective-C. A single class can be either thread-safe or non-thread-safe, depending on whether it is expected to be shared across threads. Stating that it is exclusive implies that it is variable. There are really three levels here, default, non-altering, methods that don't change the object and are therefore automatically exclusive, exclusive methods that change the object but restrict access to a single thread at a time, and variable methods that change the object and do not restrict access. When you instantiate a class with the variable keyword, all exclusive methods are treated as variable methods. When you instantiate a class with the exclusive keyword, all variable methods are treated as variable, and all exclusive methods are treated as exclusive. By default all instantiations are immutable. If you want to be able to call non-immutable methods on the object, you must declare it to be variable, if you want to be able to call non-immutable methods and share it between threads, you must declare it exclusive. If the thread is only going to call non-altering methods on it, it doesn’t have to be declared exclusive, but all threaded methods will require an object that is either default or exclusive. The simple way to make sure you are making threadsafe objects is to declare all altering methods as exclusive. Making some of them variable can be an optimization to deal with later. default variable exclusive threadsafe yes no yes mutable no yes yes

Methods contain two blocks that are part of design by contract; preconditions and postconditions. These are indicated with the require and ensure blocks. A method can have one of each with the syntax: method Foo requires // Boolean statements ensures // Boolean statements body // statements end method The require block is checked before method execution, and the ensure block after. If any of the statements is false, an Error will be thrown. Their use is determined by the compiler. They can be turned on or off. The recommended use for ensure is for internal debug builds, to make sure the method can not possibly return a bad value. Any distributed binaries should have ensure turned off. The recommended use for require is distributed debug builds. The users of the API should be told if they are giving a method bad data. Any binaries from production systems should have require turned off. Every statement in a contract must return Boolean. Also, any methods called in the contract must either act on objects created within the scope of the contract, or they must not be variable. Also, any objects passed as parameters to a method must either have been created in the scope, or not passed as a variable ref. As a compiler implementation detail, the simplest way to accomplish this is probably to treat the contract as a method like so: variable method (Real) move,xBy: (variable Integer) xDelta yBy: (variable Integer) yDelta requires // assertions body // statements end method would be expanded to the following require method. Note that the require method is basically a copy of the original method, but it is not variable, its parameters are not variable, and it has no return value: variable method (Real) move,xBy: (variable Integer) xDelta yBy: (variable Integer) yDelta self.moveXby: xDelta yBy: yDelta requires // statements end method method move,xBy: (Integer) xDelta yBy: (Integer) yDelta requires // assertions end method Normally, when a precondition fails, it throws a PreconditionFailedError. However, when the code is compiled with preconditions off, no such error is thrown. Also, if a parameter is passed to a method that passes the parameter unchanged to another method (I.E., if no assignment or pass-by-variable-ref occurs), a warning is issued if the containing method does not have all of the preconditions involving that parameter that are in the contained method. This may cause problems, because the check may be done later (E.G., as an if, with the alternative being passed to some other method or something, but if we see it in the same basic block, then we’re probably safe.

Overriding methods can return or throw subclasses of the overridden method’s respective classes. Overriding methods can be more visible and less (variable, abstract) than the overridden method and both must have the same scope (class or instance) and return style (ref, variable ref, or copy). Whether or not they are exclusive doesn’t matter. default-visibility variable method (SuperClass) set,X: ExactClass throws SuperException end method can be overridden by public default-mutability method (SubClass) set,X: ExactClass throws SubException end method As far as design-by-contract goes, overriding methods can weaken the precondition and strengthen the postcondition. It makes contractual sense to allow the parameters of an overriding method to be superclasses of the original parameters, since it only widens the acceptable data. However, since parameters are part of the method signature, it is almost impossible to make this work in practice. Therefore, any parameters must be exactly the same as the original. The subclass can still effectively widen the method by writing another, non-overriding, version of the method with the signature changed only by the parameter types: abstract class SuperClass abstract public method set,X: (ExactClass) x Y: (ExactClass) y end class abstract class SubClass implements SuperClass public method set,X: (ExactClass) x Y: (ExactClass) y self.setX: (ExactSuperClass) x Y: y end method abstract public method set,X: (ExactSuperClass) x Y: (ExactClass) y abstract public method set,X: (ExactClass) x Y: (ExactSuperClass) y end class This allows you to explicitly state which of the widened methods you should call in cases such as the one above, where two widened methods are possible, and neither one being clearly correct.

Invariants are statements that must always be true. This is part of design-by-contract. A class may have a block with the syntax: invariant // Boolean statements end invariant If any of these statements ever become false, an Error will be thrown. Their use is determined by the compiler. They can be turned on or off. Their recommended use is for internal debug builds, to make sure the class can not possibly be held in an inconsistent state. Any distributed binaries should have these turned off.

Largely the same as templates in C++. The syntax is a little different, though: generic class Pair{Object first, Object second} public attribute (first.class) first public attribute (second.class) second public constructor .with,First: (first.class) first Second: (second.class) second self.first = first self.second = second end constructor end class generic class Pair{Orderable{first.class} first, Orderable{second.class} second} implements Orderable{Pair{first.class, second.class}} public constructor .with,First: (first.class) first Second: (second.class) second self.first = first self.second = second end constructor public operator (Boolean) < (Pair{first.class, second.class}) other return = self.first < other.first \ || (self.first == other.first && self.second < other.second) end operator end class These classes are slightly more free-form than other ones. As parameters and return values can have the types ‹genericparameterlabel›.class, as in the above example. The second class in the example shows an explicit specialization, which is a method of subclassing for generic classes. The class has only tightened the restrictions on the generic parameters, allowing additional functionality to be added. Enumerations can be written in the Java style as a class of public static final data members, and in some cases must, but Reykjavík provides a shorthand syntax that covers the most common uses in order to prevent the misuse of un-enumerated constants that seems to have crept into Java. [ordered] enumeration [(type)] name FIRST [= value] SECOND [= value] THIRD [= value] end enumeration First, we’ll cover the full standard syntax. An enumeration should always extend Enumeration{} or one of its subclasses. Most handwritten enumerations will probably extend Enumeration{} itself. Here’s an example that must be written out with the full syntax: public class HttpCode extends Enumeration{HttpCode} implements Convertible{Integer}, Convertible{String} // Success (2xx) public class attribute OK = HttpCode.withValue: 200 andString: "OK" public class attribute CREATED = HttpCode.withValue: 201 andString: "Created" public class attribute ACCEPTED = HttpCode.withValue: 202 andString: "Accepted" public class attribute PARTIAL_INFORMATION = HttpCode.withValue: 203 andString: "Partial Information" public class attribute NO_RESPONSE = HttpCode.withValue: 204 andString: "No Response" // Redirection (3xx) public class attribute MOVED = HttpCode.withValue: 301 andString: "Moved" public class attribute FOUND = HttpCode.withValue: 301 andString: "Found" public class attribute METHOD = HttpCode.withValue: 301 andString: "Method" public class attribute NOT_MODIFIED = HttpCode.withValue: 301 andString: "Not Modified" // Client error (4xx) public class attribute BAD_REQUEST = HttpCode.withValue: 400 andString: "Bad Request" public class attribute UNAUTHORIZED = HttpCode.withValue: 401 andString: "Unauthorized" public class attribute PAYMENT_REQUIRED = HttpCode.withValue: 402 andString: "Payment Required" public class attribute FORBIDDEN = HttpCode.withValue: 403 andString: "Forbidden" public class attribute NOT_FOUND = HttpCode.withValue: 404 andString: "Not Found" // Server error (5xx) public class attribute INTERNAL_ERROR = HttpCode.withValue: 500 andString: "Internal Error" public class attribute NOT_IMPLEMENTED = HttpCode.withValue: 501 andString: "Not Implemented" public class attribute SERVICE_TEMPORARILY_OVERLOADED = HttpCode.withValue: 502 andString: "Service Temporarily Overloaded" public class attribute GATEWAY_TIMEOUT = HttpCode.withValue: 503 andString: "Gateway Timeout" attribute (Integer) value attribute (String) string constructor .withValue: (Integer) value andString: (String) string self.value = value self.string = string end constructor public method (HttpStatusCode) .from: (Integer) value // Use reflection to get all the enum members, then walk through // looking for one with the correct value require value != null end method public method (HttpStatusCode) .from: (String) string // Use reflection to get all the enum members, then walk through // looking for one with the correct value require string != null end method public method (Integer) .convertTo{Integer} return self.value end method public method (String) .convertTo{String} return self.string end method end class There are four types of enumerations that can be created using this syntax. The simplest merely codifies a list of internal values, that never have to be converted into any real-world value. There is also an ordered enumeration of the same variety. An ordered enumeration implements Orderable{type} (which gets you a slew of operators) based on the order of the elements in the declaration. These versions are generally used for purely internal flags and such. Things that never need to be written to a file or anything. Here's a simple example: enumeration UnicodeCharacterClass CONTROL DRAWING LETTER NUMBER SYMBOL end enumeration There is then the slightly more complex variety that uses the “(type)” and “= value” bits of the syntax. This version implements Convertible{type} and a retrieveWithValue method, which allows the enum to be exported to, or imported from, the specified type. This is useful when there is some outside format, like a text file, that may need to be read from or written to, in which case typing as a String or Integer would be very likely. The fourth variety is an orderable version of the convertible enumeration. The ordering rules work the same as with the simple variety. Here’s a simplified version of the HttpStatusCode example to show how a ConvertibleEnumeration{} works: enumeration (Integer) HttpStatusCode OK = 200 CREATED = 201 ACCEPTED = 202 … GATEWAY_TIMEOUT = 503 end enumeration That code is identical to the first example above, except that none of the string operations exist. The convenient syntax of the last two examples should make enumeration usage more prevalent. Java, in moving to type-safe, flexible enumerations failed to provide a syntax that was nearly as usable as that in C++. In so doing, they caused all the lazy programmers to abandon enums in favor of lists of public static final ints. It may even be possible to handle more complex enums with the shorthand if we use a syntax like this: enumeration (Integer, String) HttpStatusCode OK = 200, “OK” CREATED = 201, “Created” ACCEPTED = 202, “Accepted” … GATEWAY_TIMEOUT = 503, “Gateway Timeout” end enumeration Should probably avoid this topic in the spec, but … as enumerations are a quite literal shorthand, it makes sense to expand them into a full class syntax before handing them to the compiler, so the compiler doesn’t have to do any special handling for them. This is our pre-processor. While the pre-processor is useful to handle certain shorthand features of the language, it’s probably unwise to encourage people to write their own extensions or shorthands – remember how that got C in trouble. As a feature for editors, it would be useful to have a single-click way to expand an enumeration to a full-fledged class. Exception handling doesn’t require a special try block. A catch/finally clause can be tacked on the end of any block, including a method. If there is no block existing at the scope you want to cover for an exception, the anonymous block block can be used. As in the following example: method Bar if: foo == true // do something else if: foo == null // something else // do something else catch: (Exception) e // handle it end if // do something that can throw Exception catch: (Exception) e // handle this exception finally // any generic cleanup end method Exceptions should be extremely rare. Argument exceptions are replaced with assertions. There will still be a few cases where exceptions need to be handled, but most of the ones I can think of can be replaced by returning null. Not sure which is preferred there. After some thinking, I believe that throwing an exception is preferred to returning null. Returning null is pretty damn similar to old-school error code shit. We should avoid it, unless null is a valid value for some situation. Exceptions let you know that you have to handle them, null doesn’t.

This should look like the following: if: foo == bar // statements else if: foo == baz // statements else // statements end if

This should look like the following: switch: foo case: bar // statements case: baz // statements default // statements end switch The inner blocks have implicit endings because they can only occur directly inside the switch, and the switch can not contain any other statements. It is therefore cleaner (and safe) to eliminate the endings. However, this does not imply any fall-through, and the blocks do not require a break statement to exit the switch. Fall-throughs are handled by making another method and having any case that needs that functionality call that method. There is the possibility of the compiler inlining it like a C-style fall-through.

All of the looping constructs you’re used to are gone. There is only loop. This is how it works: loop // statements end loop Now, you can mimic a while/until loop: loop break if: !foo.hasNext // statements end loop a do-while/until loop: loop // statements break if: !foo.hasNext end loop or even a for loop (although God only knows why): Integer i = 0 loop break if: i > foo.length // statements ++i end loop But the two coolest features of this are the ability to have pure infinite loops (for embedded systems and event loops) as shown above, and to eliminate the loop and a half that’s so common in while-based languages: loop // statements that would normally be in the while loop break if: !foo.hasNext // statements that would normally be both in the loop, and before the loop end loop Actually, I’d like to eliminate the break statement all together. Don’t like the goto-ness of it. However, even by reintroducing the while, until, and for loops, there’s still one case I'm not happy with. The last one above – the loop and a half. I can’t figure out how to solve that problem without some kind of break.

I’m not sure about this one. It works like the synchronized statement in Java, but turns on or off, depending on if you instantiate an exclusive instance of the object or not. I wanted this to be a modifier to the block statement, but since it needs an expression, that might not work: exclusive: someObject // statements end exclusive

This statement allows a locally scoped block to use a given object as the default, to reduce repetitive typing: with: someUri .setSchemeTo: “http” .setFragmentTo: “spec14.18” .resolve end with is a convenient shorthand for: someUri.setSchemeTo: “http” someUri.setFragmentTo: “spec14.18” someUri.resolve This will probably be handled by the pre-processing system, too (although that topic should be covered in the docs for the GCC front-end). The with statement is also useful for creating temporaries with a fixed scope: with: new URI .setSchemeTo: “http” .setFragmentTo: “spec14.18” write: . to.System.out end with and for simplifying repeated casting (but, of course, casting will be very rare): Object foo = “/don’t like leading slashes” with: foo as String if: .startsWith: “/” .substringFrom: 1 To: .length end if return . end with

Unreachable statements are not errors as in Java, only warnings.

Operator overloading is very important to the language. There are two forms of overloading – interfaced overloading, and low-level overloading. Interfaced overloading involves implementing operators that defined by one of the following interfaces that you must be implementing: Comparable: provides the equality and inequality operators Orderable: implements Comparable, and adds the <, <=, >, >=, <=> operators Calculable: provides the +, -, /, *, **, % binary operators RandomlyAccessible: provides the [] operator Stringable: provides the concatenation operator Bitable: provides <<, >>, &, |, ^ Interfaced overloading has certain requirements that low-level overloading doesn’t. For example, it assumes that the implementation of the == operator is commutative. Which means that even though String doesn’t implement == with a URI, you can still order the arguments as String == URI, and not just URI == String. There is a possibility to have “reverse” operators for non-commutative operators, like -. These would allow reversing the order of arguments, just like commutative operators. It might look like this: class PseudoInteger implements Calculable{Integer} public operator -: (Integer) other return self.int - other end operator public operator -: (Integer) other reversed return other - self.int end operator end class Low-level overloading doesn’t have these restrictions. However, low-level overloading should be avoided. If the operator acts as expected, then implement the proper interface. If it doesn’t, then overloading the operator would probably be confusing to a user. Overloading an operator implictly overloads any corresponding assignment operator. For example, overloading + also overloads +=. This is because foo += bar can be rewritten foo = foo + bar, which then calls the operator you overloaded.

We don’t got no prefix or postfix operators. Java makes a point of saying postfix _aren’t_ operators, and prefix was the only operator besides the assignment operators that could change an object. So it just seemed like a level of confusion that should be removed.

The combined assignment operators (like +=) that are a nice short hand, are exactly that – a shorthand. We expand them before the compiler sees it, so overloading the + operator overloads the += operator for you as well. Yay! Free code!

This chapter presents a grammar for the Reykjavík programming language. The grammar presented piecemail in the preceding chapters is much better for exposition, but it is not ideally suited as a basis for a parser. The grammar presented in this chapter is the basis for the reference implementation. The grammar below follows the EBNF specification as described in ISO/IEC 14977:1996. Just for clarity, non-terminals are displayed in an italic font. File Namespace, {Include}, {ClassDefinition} Namespace [WhiteSpace], "namespace", WhiteSpace, Identifier, EndLine Include [WhiteSpace], "include", WhiteSpace, Identifier, EndLine ClassDefinition Alias | Class | Enumeration Alias [WhiteSpace], "alias", WhiteSpace, Identifier, WhiteSpace, "as", WhiteSpace, Identifier, EndLine Class [WhiteSpace] ClassModifiers, "class", WhiteSpace, Identifier, EndLine, [[WhiteSpace], "extends", WhiteSpace, Type, EndLine], [[WhiteSpace], "implements", WhiteSpace, Type, {[WhiteSpace], ",", [WhiteSpace], Type}, EndLine], {Attribute | MethodBlock}, [WhiteSpace], "end class", EndLine ClassModifiers ["abstract", WhiteSpace], ["generic", WhiteSpace] Enumeration ConvertibleEnumeration | NonConvertibleEnumeration ConvertibleEnumeration [WhiteSpace] ["ordered", WhiteSpace], "enumeration", WhiteSpace, Type, WhiteSpace, Identifier, EndLine, {[WhiteSpace], Identifier, [WhiteSpace], "=", [WhiteSpace], Expression, EndLine}-, [WhiteSpace], "end enumeration", EndLine NonConvertibleEnumeration [WhiteSpace] ["ordered", WhiteSpace], "enumeration", WhiteSpace, Identifier, EndLine, {[WhiteSpace], Identifier, EndLine}-, [WhiteSpace], "end enumeration", EndLine Attribute [WhiteSpace], AttributeModifiers, "attribute", WhiteSpace, Type, WhiteSpace, Identifier, [[WhiteSpace], "=", [WhiteSpace], Expression], EndLine MethodBlock Constructor | Destructor | Accessor | Method | Operator Method MethodModifiers, "method", ParameterList, EndLine, MethodBody, [WhiteSpace], "end method", EndLine Throws [WhiteSpace], "throws", WhiteSpace, Exception, {[WhiteSpace], ",", [WhiteSpace], Exception}, EndLine BlockBody {Statement}, [Catch] Block [WhiteSpace], "block", EndLine, BlockBody, [WhiteSpace], "end block", EndLine MethodBody [Throws], [Require], BlockBody, [Ensure] Parameter "(", [WhiteSpace], ["copy", WhiteSpace], ["variable" | "exclusive"], WhiteSpace], Type, [WhiteSpace], ")", [WhiteSpace], Identifier ParameterWithDefault Parameter, [[WhiteSpace], "=", [WhiteSpace], Expression] SingleParameterList MethodName, ":", Parameter ParameterList MethodName, [",", {ParameterLabel, ":", ParameterWithDefault}-, [MethodTail]] Constructor ["public" | "private"], ["constructor"], ParameterList, MethodBody, "end constructor" Operator Modifiers, "operator", SingleParameterList, MethodBody, "end operator" Destructor "destructor", MethodBody, "end destructor" CommonModifiers ["public" | "private"], ["class"] AccessorModifiers ["variable"], CommonModifiers MethodModifiers ["abstract" | ["exclusive" | "variable"]], CommonModifiers Accessor Getter | Setter Getter MethodModifiers, "accessor", MethodName, MethodBody, "end accessor" Setter MethodModifiers, "accessor", SingleParameterList, MethodBody, "end accessor" If "if:", BooleanStatement, {Statement}, {"else if:", BooleanStatement, {Statement}}, ["else", {Statement}], [Catch], "end if" Loop "loop", BlockBody, "end loop" Switch "switch:", Expression, {Case}-, [Default], [Catch], "end switch" Case "case:", Expression, BlockBody Default "default", BlockBody Catch {"catch:", Parameter, BlockBody}-, ["finally", BlockBody] Require "require", {BooleanStatement}, "end require" Ensure "ensure", {BooleanStatement}, "end ensure" Break "break", [Identifier], [TrailingIf] EndLine {Comment | ({WhiteSpace}, LineTerminator)}- Comment "//", {InputCharacter}, LineTerminator WhiteSpace Unicode{Z} - Unicode{Zl} | ("\", Unicode{Zl})