<commit_before><chapter id="introduction">
    <title>Introduction</title>
    
    <para>This document defines the syntax and semantics of the Ceylon language.
    The intended audience includes compiler implementors, interested parties
    who wish to contribute to the evolution of the language, and experienced 
    developers seeking a precise definition of language constructs. However, in
    light of the newness of the language, we will begin with an overview of the
    main features of the language and SDK. A brief introduction to programming 
    in the language may be found at the following address:</para>
    
    <programlisting>http://ceylon-lang.org/documentation/tour/</programlisting>
    
    <section id="languageoverview">
        <title>Language overview</title>
    
    <para>
    Ceylon is a general-purpose, imperative, statically-typed, block-structured, 
    object-oriented, higher-order language featuring a syntax similar to Java and 
    C#. By <emphasis>statically-typed</emphasis>, we mean that the compiler
    performs type checking, with the help of type annotations that appear in the 
    code. By <emphasis>object-oriented</emphasis>, we mean that the language 
    features a nominative type system where a type is a set of named attributes 
    and operations, and that it supports inheritance and subtype polymorphism. By 
    <emphasis>higher-order</emphasis>, we mean that every named program element
    (every attribute, every operation, and every type) is a value. By 
    <emphasis>block-structured</emphasis>, we mean to say that the language features
    lexical scoping and an extremely regular recursive syntax for declarations and
    statements.
    </para>
    
    <para>
    Ceylon programs execute in any standard Java Virtual Machine and, like Java, 
    take advantage of the memory management and concurrency features of that 
    environment. The Ceylon compiler is able to compile Ceylon code that calls 
    Java classes or interfaces, and Java code that calls Ceylon classes or 
    interfaces. 
    </para>
    
    <para>
    Ceylon improves upon the Java language and type system to reduce verbosity 
    and increase typesafety compared to Java and C#. Ceylon encourages a more 
    functional style of programming, resulting in code which is easier to reason 
    about, and easier to refactor. Moreover, Ceylon provides its own native SDK 
    as a replacement for the Java platform class libraries.
    </para>
    
    <section id="thetypesystem">
    <title>The type system</title>
    
    <para>
    Ceylon, like Java, features a hybrid type system with both subtype polymorphism 
    and parameteric polymorphism. A type is either a stateless <emphasis>interface</emphasis>, 
    a stateful <emphasis>class</emphasis>, a <emphasis>type parameter</emphasis>, or 
    a <emphasis>union</emphasis> or <emphasis>intersection</emphasis> of other types.
    A class, interface, or type parameter may be defined as a subtype of another type.
    A class or interface may declare type parameters, which abstract the definition 
    of the class or interface over all types which may be substituted for the type 
    parameters.
    </para>
    
    <para>
    There are no primitive types or arrays in Ceylon&mdash;every Ceylon type can 
    be represented within the language itself. So all values are instances of the 
    type hierarchy root <literal>Void</literal>, which is a class. However, the 
    Ceylon compiler is permitted to optimize certain code to take advantage of the 
    optimized performance of primitive types on the JVM.
    </para>
    
    </section>
    
    <section id="mixininheritance">
    <title>Mixin inheritance</title>
    
    <para>
    Ceylon supports a restricted form of multiple inheritance, often called 
    <emphasis>mixin inheritance</emphasis>. A class must extend exactly one other 
    class. But a class or interface may satisfy (extend or implement) an arbitrary 
    number of interfaces.
    </para>
    
    <para>
    Classes hold state and logic to initialize that state when the class is 
    instantiated. A concrete class is a class that contains only concrete member 
    definitions. Concrete classes may be directly instantiated.  An abstract class 
    may contain abstract member declarations. Abstract classes may not be 
    instantiated.
    </para>
    
    <para>
    Interfaces may define concrete members, but may not hold state (references to 
    other objects) or initialization logic. This restriction helps eliminate the 
    problems traditionally associated with multiple inheritance. Ceylon never 
    performs any kind of "linearization" of the supertypes of a type. Interfaces 
    may not be directly instantiated.
    </para>
    
    </section>
    
    <section id="algrebraictypesselftypes">
    <title>Algebraic types, self types, and type families</title>
    
    <para>
    Ceylon does not feature enumerated types as a first-class construct. Instead,
    any abstract type may specify its <emphasis>cases</emphasis>&mdash;an enumerated 
    list of instances or subtypes. This facility is used to simulate both enumerated 
    types and functional-style algebraic types. 
    </para>
    
    <programlisting>interface Identity of Person | Organization { ... }</programlisting>
    
    <para>
    A closely related feature is support for <emphasis>self types</emphasis> and 
    <emphasis>type families</emphasis>. A self type is a type parameter of an 
    abstract type (like <literal>Comparable</literal>) which represents the type of 
    a concrete instantiation (like <literal>String</literal>) of the abstract type,
    within the definition of the abstract type itself. In a type family, the self 
    type of a type is declared not by the type itself, but by a containing type which 
    groups together a set of related types.
    </para>
    
    </section>
    
    <section id="simplifiedgenerics">
    <title>Simplified generics and fully-reified types</title>
    
    <para>
    Ceylon does not support Java-style wildcard type parameters, raw types, or
    any other kind of existential type. And the Ceylon compiler never even uses 
    any kind of "non-denotable" type to reason about the type system. And there's 
    no implicit constraints on type arguments. So generics-related error messages 
    are understandable to humans.
    </para>
    
    <para>
    Instead of wildcard types, Ceylon features <emphasis>declaration-site variance</emphasis>. 
    A type parameter may be marked as covariant or contravariant by the class or 
    interface that declares the parameter.
    </para>
    
    <!--parameterization of type parameters (a form of higher-order polymorphism), and--> 
    
    <para>
    Ceylon has a more expressive system of generic type constraints with a much 
    cleaner, more regular syntax. The syntax for declaring type constraints on 
    a type parameter looks very similar to a class or interface declaration. 
    Along with upper bound type constraints, there are lower bounds, enumerated 
    bounds, and parameter bounds.
    </para>
    
    <programlisting>interface Producer&lt;in Input, out Value&gt; 
        given Value(Input input) satisfies Object { ... }</programlisting>
    
    <para>
    Ceylon's type system is fully reified. In particular, generic type arguments 
    are reified, eliminating many problems that result from type erasure in Java.
    </para>
        
    </section>
    
    <section id="unionandintersectiontypes">
    <title>Union and intersection types</title>

    <para>
    A <emphasis>union type</emphasis>, for example <literal>String|Number</literal>, 
    or <emphasis>intersection type</emphasis>, for example <literal>String&amp;Number</literal>,
    may be formed from two or more types defined elsewhere. 
    </para>
    
    <para>
    Union types make it possible to write code that operates polymorphically 
    over types defined in disparate branches of the type heirarchy without the 
    need for intermediate adaptor classes. Intersection types make it possible 
    to operate polymorphically over all subtypes of a list of types.
    </para>
        
    <para>
    Union and intersection types play a central role in generic type argument 
    inference.
    </para>
    
    </section>
    
    <section id="typealiases">   
    <title>Type aliases and type inference</title>
    
    <para>    
    Type aliases and type inference help reduce the verbosity of code which 
    uses generic types, eliminating the need to repeatedly specify generic
    type arguments.
    </para>

    <para>
    <emphasis>A type alias</emphasis> is similar to a C-style <literal>typedef</literal>.
    </para>
    
    <programlisting>interface Strings = Sequence&lt;String&gt;;</programlisting>
    
    <para>
    The type of a block-local attribute or method may be inferred from its 
    definition. The keyword <literal>value</literal> or <literal>function</literal> 
    must appear in place of the type declaration.
    </para>
    
    <programlisting>value name = person.name;</programlisting>
    <programlisting>function sqrt(Float x) { return x**0.5; }</programlisting>
    
    <para>
    The type of a control-structure variable also may be inferred.
    </para>
    
    <programlisting>for (n in 0..max) { ... }</programlisting>
    <programlisting>try (tx = Transaction()) { ... }</programlisting>
    
    <para>
    By limiting type inference to local declarations, Ceylon ensures that all 
    types may be inferred by the compiler in a single pass of the source code. 
    Type inference works in the "forward" and "outward" directions. The compiler 
    is able to determine the type of an expression without considering the rest 
    of the statement or declaration in which it appears.
    </para>
    
    </section>
    
    <!-- section id="lexicalmixin">
    <title>Introductions</title>
    
    <para>
    Ceylon doesn't have open classes or any kind of implicit type conversion.
    Instead, Ceylon features lexically-scoped <emphasis>introduction</emphasis>
    of interfaces&mdash;a much more powerful cousin of the notion of extension 
    methods.
    </para>
    
    <para>
    Usually, the interfaces inherited by a type are specified as part of the 
    type definition. But a special kind of interface, called an 
    <emphasis>adapter</emphasis> may be <emphasis>introduced</emphasis> 
    ("mixed in") to a pre-existing type at the point of use. 
    </para>
    
    <programlisting>interface StringCharacters
        adapts String
        satisfies List&lt;Character&gt; { ... }</programlisting>
    
    <para>
    Introduction does not in any way affect the internal behavior of any instance 
    of the type to which the interface is introduced, but does allows the type 
    to be treated as a subtype of the introduced interface within the lexical 
    scope of the introduction.
    </para>
    
    <programlisting>List&lt;Character&gt; chars = "Hello, World!";</programlisting>
    
    </section-->
    
    <section id="initializationandinstantiation">
    <title>Class initialization and instantiation</title>
    
    <para>
    Ceylon does not feature any Java-like constructor declaration and so each 
    Ceylon class has a parameter list, and exactly one 
    <emphasis>initializer</emphasis>&mdash;the body of the class. This helps
    reduce verbosity and results in a more regular block structure.
    </para>
    
    <programlisting>class Point(Float x, Float y) { ... }</programlisting>
    
    <para>The Ceylon compiler guarantees that the value of any attribute of
    a class is initialized before it is used in an expression.</para>
    
    <para>A class may be a member of an outer class. A member class may be 
    refined (overridden) by a subclass of the outer class. Instantiation is 
    therefore a polymorphic operation in Ceylon, eliminating the need for 
    factory methods.
    </para>
    
    <para>
    Ceylon provides a streamlined syntax for defining an anonymous class which 
    is only instantiated in exactly the place it is defined. Among other uses,
    the <literal>object</literal> declaration is useful for creating singleton 
    objects or method-local interface implementations. 
    </para>
    
    <programlisting>object origin extends Point(0.0, 0.0) {}</programlisting>
    
    </section>
    
   <section id="methodsandattributes">
    <title>Methods and attributes</title>
    
    <para>
    Ceylon types have members: <emphasis>methods</emphasis> and 
    <emphasis>attributes</emphasis>. Ceylon methods are similar to Java methods. 
    However, Ceylon classes do not contain fields, at least not in the 
    traditional sense. Instead, Ceylon supports only a higher-level construct: 
    polymorphic attributes, which are similar to C# properties. Attributes 
    abstract the internal representation of the state of an object. An attribute 
    of a class may be refined (overridden) by a subclass of the class.
    </para>
    
    <programlisting>String name {
    return firstName + " " + lastName;
}</programlisting>
    
    <para>The Ceylon compiler guarantees that the value of any local declared in 
    the body of a method or attribute is initialized before it is used in an 
    expression.</para>
    
    <para>
    By default, an attribute or local may not be assigned a new value after
    its initial value has been specified. Mutable attributes and variable 
    locals must be explicitly declared using the <literal>variable</literal> 
    annotation.
    </para>
    
    <para>
    There are no <literal>static</literal> members. Instead, 
    <emphasis>toplevel</emphasis> methods and attributes are declared as direct 
    members of a package. This, along with certain other features, gives the 
    language a more regular block structure.
    </para>
    
    <para>
    Ceylon does not support method overloading. Each method of a type has a 
    distinct name.
    </para>
    
    </section>
    
    <section id="defaultparameters">
    <title>Defaulted parameters and sequenced parameters</title>
    
    <para>
    Instead of method and constructor overloading, Ceylon supports parameters 
    with default values and <emphasis>sequenced</emphasis> ("varargs") 
    parameters.
    </para>
    
    <programlisting>void addItem(Product product, Integer quantity=1) { ... }</programlisting>
    
    <programlisting>String join(String... strings) { ... }</programlisting>
    
    <para>
    Furthermore, a generic method may be used to emulate parameter
    type overloading.
    </para>
    
    <programlisting>Number sum&lt;Number&gt;(Number... numbers)
        given Number of Integer | Float { ... }</programlisting>
    
    <para>Therefore, a single method in Ceylon may emulate the signatures of 
    several overloaded methods in Java.</para>
    
    </section>
    
    <section id="compilerenforcednamingconventions">
    <title>Naming conventions, annotations, and inline documentation</title>
    
    <para>
    The Ceylon compiler enforces the traditional Smalltalk naming convention:
    type names begin with an initial uppercase letter&mdash;for example, 
    <literal>Liberty</literal> or <literal>RedWine</literal>&mdash;member names 
    and local names with an initial lowercase letter or underscore&mdash;for
    example, <literal>blonde</literal>, <literal>immanentize()</literal> or 
    <literal>boldlyGo()</literal>.
    </para> 
    
    <para>
    This restrictions allows a much cleaner syntax for program element annotations 
    than the syntax found in either Java or C#. Declaration "modifiers" like
    <literal>shared</literal>, <literal>abstract</literal>, and <literal>variable</literal>
    aren't keywords in Ceylon, they're ordinary annotations. The documentation
    compiler reads inline documentation specified using the <literal>doc</literal> 
    annotation.
    </para>
    
    <programlisting>doc "Base type for higher-order abstract stuff."
shared abstract class AbstractMetaThingy() { ... }</programlisting>
    
    </section>
    
    <section id="firstclassfunctions">
    <title>First-class functions and higher-order programming</title>
    
    <para>
    Ceylon supports first-class function types and higher-order functions, 
    with minimal extensions to the traditional C syntax. A method declaration 
    may specify a <emphasis>callable parameter</emphasis> that accepts 
    references to other methods with a certain signature. 
    </para>
    
    <programlisting>String find(Boolean where(String string), String... strings) { ... }</programlisting>
    
    <para>
    The argument of such a callable parameter may be either a reference to a 
    named method declared elsewhere, or a new method defined inline as part of 
    the method invocation. A method may even return an invocable reference to 
    another method.</para>
    
    <!-- 
    <para>
    Finally, nested method declarations receive a closure of 
    immutable references defined in the surrounding scope.
    </para>
    -->
    </section>
    
    <!--
    <section id="lazyevaluationpassbyreference">
    <title>Lazy evaluation and pass by reference</title>
    
    <para>
    Using a "trick" in the Ceylon type system, it's possible to take advantage 
    of lazy evaluation of expressions and pass by reference for attributes.
    </para>
    
    </section>
    -->
    
    <section id="compiletimesafety">
    <title>Compile-time safety for optional values and type narrowing</title>
    
    <para>
    There is no primitive null in Ceylon. The null value is an instance of 
    the class <literal>Nothing</literal> that is not assignable to user-defined 
    class or interface types. An <emphasis>optional type</emphasis> is a 
    union type like <literal>Nothing|String</literal>, which may be abbreviated
    to <literal>String?</literal>. An optional type is not assignable to a 
    non-optional type except via use of the special-purpose 
    <literal>if (exists ... )</literal> construct. Thus, the Ceylon compiler 
    is able to detect illegal use of a null value at compile time. Therefore, 
    there is no equivalent to Java's <literal>NullPointerException</literal> 
    in Ceylon.
    </para>
    
    <para>
    Similarly, there are no C-style typecasts in Ceylon. Instead, the 
    <literal>if (is ... )</literal> and <literal>case (is ... )</literal> 
    constructs may be used to narrow the type of an object reference without 
    risk of a <literal>ClassCastException</literal>. The combination of
    <literal>case (is ... )</literal> with algebraic types amounts to a kind
    of language-level support for the visitor pattern.
    </para>
    
    </section>
    
    <section id="sequences">
    <title>Sequences</title>
    
    <para>Sequences are Ceylon's version of arrays. However, the
    <literal>Sequence</literal> interface does not provide operations for
    mutating the elements of the sequence.</para>
    
    <para>Ceylon distinguishes between empty and nonempty sequences. An 
    instance of <literal>Sequence</literal> is has at least one element. An 
    empty sequence is an instance of the type <literal>Empty</literal>.
    It's very common to work with a <emphasis>sequence type</emphasis> like
    <literal>Empty|Sequence&lt;String&gt;</literal>,
    which may be abbreviated <literal>String[]</literal>. The special-purpose
    <literal>if (nonempty ... )</literal> construct narrows a sequence type
    to an instance of <literal>Sequence</literal>.</para>
    
    <para>Sequences may be instantiated using a streamlined syntax.</para>
    
    <programlisting>String[] languages = { "Java", "Python", "Ceylon", "Smalltalk", "ML" };</programlisting>
    
    </section>
    
    <section id="controlflow">
    <title>Control flow</title>
    
    <para>
    Ceylon's built in control flow structures are very similar to the 
    traditional constructs found in C, C# and Java. However, inline methods 
    can be used together with a special Smalltalk-style method invocation 
    protocol to achieve more specialized flow control and other 
    functional-style constructs such as comprehensions.
    </para>
    
    <para>
    Ceylon features an exceptions model inspired by Java and C#. Checked 
    exceptions are not supported.
    </para>
    
    </section>
    
    <section id="operatorsandoperatorpolymorphism">
    <title>Operators and operator polymorphism</title>
    
    <para>
    Ceylon features a rich set of operators, including most of the operators 
    supported by C and Java. True operator overloading is not supported. 
    However, each operator is defined to act upon a certain class or interface 
    type, allowing application of the operator to any class which extends or 
    satisfies that type. This approach is called <emphasis>operator 
    polymorphism</emphasis>.
    </para>
    
    </section>
    
    <section id="numerictypes">
    <title>Numeric types</title>
    
    <para>Ceylon's numeric type system is much simpler than C, C# or Java, with
    exactly two built-in numeric types (compared to six in Java and eleven in 
    C#). The built-in types are classes representing integers and floating point 
    numbers. <literal>Integer</literal> and <literal>Float</literal> values are 
    64 bit by default, and may be optimized for 32 bit architectures via use of 
    the <literal>small</literal> annotation.</para>
    
    <para>The module <literal>ceylon.math</literal> provides two additonal
    numeric types representing arbitrary precision integers and arbitrary 
    precision decimals.</para>
    
    </section>
    
    <!-- 
    <section id="dimensioned types">
    <title>Dimensioned types</title>
    
    <para>Ceylon supports <emphasis>dimensional type parameters</emphasis>,
    allowing types with fixed dimensions such as vectors or matrices to be
    represented within the type system, and enabling compile-time bounds 
    checking of indexing operations.</para>
    
    </section>
    -->
    
    <section id="structureddata">
    <title>User interfaces and structured data</title>
    
    <para>
    Ceylon introduces a set of syntax extensions that support the definition 
    of domain-specific languages and expression of structured data. These 
    extensions include specialized syntax for initializing objects and 
    collections and expressing literal values of user-defined types. The goal 
    of this facility is to replace the use of XML for expressing hierarchical 
    structures such as documents, user interfaces, configuration and serialized 
    data. An especially important application of this facility is Ceylon's 
    built-in support for program element annotations.
    </para>
    
    <programlisting>Html page {
    Head head { 
        title="Hello"; 
    }
    Body body { 
        P {
            css = "greeting"; 
            "Hello, World!" 
        } 
    }
}</programlisting>
    
    </section>
    
    <section id="metaprogramming">
    <title>Metaprogramming</title>
    
    <para>
    Ceylon provides sophisticated support for meta-programming, including a 
    typesafe <emphasis>metamodel</emphasis> and <emphasis>events</emphasis>. 
    Generic code may invoke members reflectively and intercept member invocations. 
    This facility is more powerful, and much more typesafe, than reflection in 
    Java.
    </para>
    
    <!--  
    <para>
    An even more powerful feature is <emphasis>metatypes</emphasis>&mdash;a
    type definition may introduce a user-defined interface to its metamodel,
    allowing a form of generic programing with polymorphic abstraction at the 
    meta level. This facility is an object-oriented flavor of the notion of 
    "type classes" in Haskell.
    </para>
    -->
    </section>
    
    <section id="modularity">
    <title>Modularity</title>
    
    <para>
    Ceylon features language-level <emphasis>package</emphasis> and 
    <emphasis>module</emphasis> constructs, along with language-level access 
    control via the <literal>shared</literal> annotation which can be used to 
    express block-local, package-private, module-private, and public visibility 
    for program elements. There's no equivalent to Java's <literal>protected</literal>.
    </para>
    
    </section>
    
    </section>
    
    <!-- 
    <section id="sdkmodules">
        <title>Modules included in the SDK</title>
    
    <para>The Ceylon SDK includes the following important modules:</para>
    
    <itemizedlist>
        <listitem>
            <para><literal>ceylon.language</literal> - basic types provided to support
            built-in language features</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.module</literal> - the module runtime (based on
            JBoss Modules)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.collection</literal> - the collections framework
            (with the underlying implementation provided by the Java collections
            framework)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.datetime</literal> - support for representing
            dates and times (based on JSR-310)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.security</literal> - the security API</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.io</literal> - the I/O facility (based on 
            <literal>java.io</literal>)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.concurrent</literal> - the concurrency API (based
            on JSR-166)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.http</literal> - the HTTP client and server (based 
            on JBoss Netty)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.transaction</literal> - the transaction server (based 
            on JBoss Transactions)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.rdbc</literal> - relational database connectivity 
            (based on JDBC)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.message</literal> - the message server (based 
            on JBoss HornetQ)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.xml</literal> - the XML parser</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.html</literal> - the HTML construction kit</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.compiler</literal> - a compiler for Ceylon source
            code</para>
        </listitem>
    </itemizedlist>
    </section>
    -->
    
    <section id="parsingceylon">
        <title>Parsing and compiling the Ceylon language</title>
        
        <para>The Ceylon language has been shown to be lexable and parseable using 
        a context-free ANTRL grammar with no hand-coded special cases.</para>
        
        <para>Ceylon is a language for the Java Virtual Machine, therefore Ceylon
        programs compile to a set of platform-independent <literal>.class</literal> 
        files that comply with the published specification for the Java class file 
        format.</para>
        
        <para>The Ceylon compiler consists of:</para>
        
        <itemizedlist>
            <listitem>
                <para>a generated parser and syntax tree,</para>
            </listitem>
            <listitem>
                <para>a handwritten type analyzer and type checker, and</para>
            </listitem>
            <listitem>
                <para>a backend that integrates the type analyzer with <literal>javac</literal>
                by transforming the Ceylon syntax tree to a Java syntax tree.</para>
            </listitem>
        </itemizedlist>
        
        <para>The type analyzer and backend are developed completely independently,
        and the parser, syntax tree, and type analyzer may be reused separately.</para>
        
    </section>
    
    <commit_msg>refresh intro<commit_after><chapter id="introduction">
    <title>Introduction</title>
    
    <para>This document defines the syntax and semantics of the Ceylon language.
    The intended audience includes compiler implementors, interested parties
    who wish to contribute to the evolution of the language, and experienced 
    developers seeking a precise definition of language constructs. However, in
    light of the newness of the language, we will begin with an overview of the
    main features of the language and SDK. A brief introduction to programming 
    in the language may be found at the following address:</para>
    
    <programlisting>http://ceylon-lang.org/documentation/tour/</programlisting>
    
    <section id="languageoverview">
        <title>Language overview</title>
    
    <para>
    Ceylon is a general-purpose, imperative, statically-typed, block-structured, 
    object-oriented, higher-order language featuring a syntax similar to Java and 
    C#. By <emphasis>statically-typed</emphasis>, we mean that the compiler
    performs type checking, with the help of type annotations that appear in the 
    code. By <emphasis>object-oriented</emphasis>, we mean that the language 
    features a nominative type system where a type is a set of named attributes 
    and operations, and that it supports inheritance and subtype polymorphism. By 
    <emphasis>higher-order</emphasis>, we mean that every named program element
    (every attribute, every operation, and every type) is a value. By 
    <emphasis>block-structured</emphasis>, we mean to say that the language features
    lexical scoping and an extremely regular recursive syntax for declarations and
    statements.
    </para>
    
    <para>
    Ceylon programs execute in any standard Java Virtual Machine and, like Java, 
    take advantage of the memory management and concurrency features of that 
    environment. The Ceylon compiler is able to compile Ceylon code that calls 
    Java classes or interfaces, and Java code that calls Ceylon classes or 
    interfaces. 
    </para>
    
    <para>
    Ceylon improves upon the Java language and type system to reduce verbosity 
    and increase typesafety compared to Java and C#. Ceylon encourages a more 
    functional style of programming, resulting in code which is easier to reason 
    about, and easier to refactor. Moreover, Ceylon provides its own native SDK 
    as a replacement for the Java platform class libraries.
    </para>
    
    <section id="thetypesystem">
    <title>The type system</title>
    
    <para>
    Ceylon, like Java, features a hybrid type system with both subtype polymorphism 
    and parameteric polymorphism. A type is either a stateless <emphasis>interface</emphasis>, 
    a stateful <emphasis>class</emphasis>, a <emphasis>type parameter</emphasis>, or 
    a <emphasis>union</emphasis> or <emphasis>intersection</emphasis> of other types.
    A class, interface, or type parameter may be defined as a subtype of another type.
    A class or interface may declare type parameters, which abstract the definition 
    of the class or interface over all types which may be substituted for the type 
    parameters.
    </para>
    
    <para>
    There are no primitive types or arrays in Ceylon&mdash;every Ceylon type can 
    be represented within the language itself. So all values are instances of the 
    type hierarchy root <literal>Void</literal>, which is a class. However, the 
    Ceylon compiler is permitted to optimize certain code to take advantage of the 
    optimized performance of primitive types on the JVM.
    </para>
    
    <para>
    The type system is based upon computation of <emphasis>principal types</emphasis>.
    Within the language, there is no way to produce an expression which does not
    have a unique principal type expressible within the language itself. The 
    principal type is a subtype of all other types to which the expression could
    be assigned.
    </para>
    
    </section>
    
    <section id="mixininheritance">
    <title>Mixin inheritance</title>
    
    <para>
    Ceylon supports a restricted form of multiple inheritance, often called 
    <emphasis>mixin inheritance</emphasis>. A class must extend exactly one other 
    class. But a class or interface may satisfy (extend or implement) an arbitrary 
    number of interfaces.
    </para>
    
    <para>
    Classes hold state and logic to initialize that state when the class is 
    instantiated. A concrete class is a class that contains only concrete member 
    definitions. Concrete classes may be directly instantiated.  An abstract class 
    may contain abstract member declarations. Abstract classes may not be 
    instantiated.
    </para>
    
    <para>
    Interfaces may define concrete members, but may not hold state (references to 
    other objects) or initialization logic. This restriction helps eliminate the 
    problems traditionally associated with multiple inheritance. Ceylon never 
    performs any kind of "linearization" of the supertypes of a type. Interfaces 
    may not be directly instantiated.
    </para>
    
    </section>
    
    <section id="algrebraictypesselftypes">
    <title>Algebraic types, self types, and type families</title>
    
    <para>
    Ceylon does not feature Java-style enumerated types as a first-class construct. 
    Instead, any abstract type may specify its <emphasis>cases</emphasis>&mdash;an
    enumerated list of instances or subtypes. This facility is used to simulate both 
    enumerated types and functional-style algebraic types. 
    </para>
    
    <programlisting>interface Identity of Person | Organization { ... }</programlisting>
    
    <para>
    A closely related feature is support for <emphasis>self types</emphasis> and 
    <emphasis>type families</emphasis>. A self type is a type parameter of an 
    abstract type (like <literal>Comparable</literal>) which represents the type of 
    a concrete instantiation (like <literal>String</literal>) of the abstract type,
    within the definition of the abstract type itself. In a type family, the self 
    type of a type is declared not by the type itself, but by a containing type which 
    groups together a set of related types.
    </para>
    
    </section>
    
    <section id="simplifiedgenerics">
    <title>Simplified generics and fully-reified types</title>
    
    <para>
    Ceylon does not support Java-style wildcard type parameters, raw types, or
    any other kind of existential type. And the Ceylon compiler never even uses 
    any kind of "non-denotable" type to reason about the type system. And there's 
    no implicit constraints on type arguments. So generics-related error messages 
    are understandable to humans.
    </para>
    
    <para>
    Instead of wildcard types, Ceylon features <emphasis>declaration-site variance</emphasis>. 
    A type parameter may be marked as covariant or contravariant by the class or 
    interface that declares the parameter.
    </para>
    
    <!--parameterization of type parameters (a form of higher-order polymorphism), and--> 
    
    <para>
    Ceylon has a more expressive system of generic type constraints with a much 
    cleaner, more regular syntax. The syntax for declaring type constraints on 
    a type parameter looks very similar to a class or interface declaration. 
    Along with upper bound type constraints, there are lower bounds, enumerated 
    bounds, and parameter bounds.
    </para>
    
    <programlisting>interface Producer&lt;in Input, out Value&gt; 
        given Value(Input input) satisfies Object { ... }</programlisting>
    
    <para>
    Ceylon's type system is fully reified. In particular, generic type arguments 
    are reified, eliminating many problems that result from type erasure in Java.
    </para>
        
    </section>
    
    <section id="unionandintersectiontypes">
    <title>Union and intersection types</title>

    <para>
    A <emphasis>union type</emphasis>, for example <literal>String|Number</literal>, 
    or <emphasis>intersection type</emphasis>, for example <literal>String&amp;Number</literal>,
    may be formed from two or more types defined elsewhere. 
    </para>
    
    <para>
    Union types make it possible to write code that operates polymorphically 
    over types defined in disparate branches of the type heirarchy without the 
    need for intermediate adaptor classes. Intersection types make it possible 
    to operate polymorphically over all subtypes of a list of types.
    </para>
        
    <para>
    Union and intersection types play a central role in generic type argument 
    inference and therefore underly the whole system of principal typing.
    </para>
    
    </section>
    
    <section id="typealiases">   
    <title>Type aliases and type inference</title>
    
    <para>    
    Type aliases and type inference help reduce the verbosity of code which 
    uses generic types, eliminating the need to repeatedly specify generic
    type arguments.
    </para>

    <para>
    A <emphasis>type alias</emphasis> is similar to a C-style <literal>typedef</literal>.
    </para>
    
    <programlisting>interface Strings = Sequence&lt;String&gt;;</programlisting>
    
    <para>
    The type of a block-local attribute or method may be inferred from its 
    definition. The keyword <literal>value</literal> or <literal>function</literal> 
    must appear in place of the type declaration.
    </para>
    
    <programlisting>value name = person.name;</programlisting>
    <programlisting>function sqrt(Float x) { return x**0.5; }</programlisting>
    
    <para>
    The type of a control-structure variable also may be inferred.
    </para>
    
    <programlisting>for (n in 0..max) { ... }</programlisting>
    <programlisting>try (tx = Transaction()) { ... }</programlisting>
    
    <para>
    By limiting type inference to local declarations, Ceylon ensures that all 
    types may be inferred by the compiler in a single pass of the source code. 
    Type inference works in the "forward" and "outward" directions. The compiler 
    is able to determine the type of an expression without considering the rest 
    of the statement or declaration in which it appears.
    </para>
    
    </section>
    
    <!-- section id="lexicalmixin">
    <title>Introductions</title>
    
    <para>
    Ceylon doesn't have open classes or any kind of implicit type conversion.
    Instead, Ceylon features lexically-scoped <emphasis>introduction</emphasis>
    of interfaces&mdash;a much more powerful cousin of the notion of extension 
    methods.
    </para>
    
    <para>
    Usually, the interfaces inherited by a type are specified as part of the 
    type definition. But a special kind of interface, called an 
    <emphasis>adapter</emphasis> may be <emphasis>introduced</emphasis> 
    ("mixed in") to a pre-existing type at the point of use. 
    </para>
    
    <programlisting>interface StringCharacters
        adapts String
        satisfies List&lt;Character&gt; { ... }</programlisting>
    
    <para>
    Introduction does not in any way affect the internal behavior of any instance 
    of the type to which the interface is introduced, but does allows the type 
    to be treated as a subtype of the introduced interface within the lexical 
    scope of the introduction.
    </para>
    
    <programlisting>List&lt;Character&gt; chars = "Hello, World!";</programlisting>
    
    </section-->
    
    <section id="initializationandinstantiation">
    <title>Class initialization and instantiation</title>
    
    <para>
    Ceylon does not feature any Java-like constructor declaration and so each 
    Ceylon class has a parameter list, and exactly one 
    <emphasis>initializer</emphasis>&mdash;the body of the class. This helps
    reduce verbosity and results in a more regular block structure.
    </para>
    
    <programlisting>class Point(Float x, Float y) { ... }</programlisting>
    
    <para>The Ceylon compiler guarantees that the value of any attribute of
    a class is initialized before it is used in an expression.</para>
    
    <para>A class may be a member of an outer class. A member class may be 
    refined (overridden) by a subclass of the outer class. Instantiation is 
    therefore a polymorphic operation in Ceylon, eliminating the need for 
    factory methods.
    </para>
    
    <para>
    Ceylon provides a streamlined syntax for defining an anonymous class which 
    is only instantiated in exactly the place it is defined. Among other uses,
    the <literal>object</literal> declaration is useful for creating singleton 
    objects or method-local interface implementations. 
    </para>
    
    <programlisting>object origin extends Point(0.0, 0.0) {}</programlisting>
    
    </section>
    
   <section id="methodsandattributes">
    <title>Methods and attributes</title>
    
    <para>
    Ceylon types have members: <emphasis>methods</emphasis> and 
    <emphasis>attributes</emphasis>. Ceylon methods are similar to Java methods. 
    However, Ceylon classes do not contain fields, at least not in the 
    traditional sense. Instead, Ceylon supports only a higher-level construct: 
    polymorphic attributes, which are similar to C# properties. Attributes 
    abstract the internal representation of the state of an object. An attribute 
    of a class may be refined (overridden) by a subclass of the class.
    </para>
    
    <programlisting>String name {
    return firstName + " " + lastName;
}</programlisting>
    
    <para>The Ceylon compiler guarantees that the value of any local declared in 
    the body of a method or attribute is initialized before it is used in an 
    expression.</para>
    
    <para>
    By default, an attribute or local may not be assigned a new value after
    its initial value has been specified. Mutable attributes and variable 
    locals must be explicitly declared using the <literal>variable</literal> 
    annotation.
    </para>
    
    <para>
    There are no <literal>static</literal> members. Instead, 
    <emphasis>toplevel</emphasis> methods and attributes are declared as direct 
    members of a package. This, along with certain other features, gives the 
    language a more regular block structure.
    </para>
    
    <para>
    Ceylon does not support method overloading. Each method of a type has a 
    distinct name.
    </para>
    
    </section>
    
    <section id="defaultparameters">
    <title>Defaulted parameters and sequenced parameters</title>
    
    <para>
    Instead of method and constructor overloading, Ceylon supports parameters 
    with default values and <emphasis>sequenced</emphasis> ("varargs") 
    parameters.
    </para>
    
    <programlisting>void addItem(Product product, Integer quantity=1) { ... }</programlisting>
    
    <programlisting>String join(String... strings) { ... }</programlisting>
    
    <para>
    Furthermore, a generic method may be used to emulate parameter
    type overloading.
    </para>
    
    <programlisting>Number sum&lt;Number&gt;(Number... numbers)
        given Number of Integer | Float { ... }</programlisting>
    
    <para>Therefore, a single method in Ceylon may emulate the signatures of 
    several overloaded methods in Java.</para>
    
    </section>
    
    <section id="compilerenforcednamingconventions">
    <title>Naming conventions, annotations, and inline documentation</title>
    
    <para>
    The Ceylon compiler enforces the traditional Smalltalk naming convention:
    type names begin with an initial uppercase letter&mdash;for example, 
    <literal>Liberty</literal> or <literal>RedWine</literal>&mdash;member names 
    and local names with an initial lowercase letter or underscore&mdash;for
    example, <literal>blonde</literal>, <literal>immanentize()</literal> or 
    <literal>boldlyGo()</literal>.
    </para> 
    
    <para>
    This restrictions allows a much cleaner syntax for program element annotations 
    than the syntax found in either Java or C#. Declaration "modifiers" like
    <literal>shared</literal>, <literal>abstract</literal>, and <literal>variable</literal>
    aren't keywords in Ceylon, they're ordinary annotations. The documentation
    compiler reads inline documentation specified using the <literal>doc</literal> 
    annotation.
    </para>
    
    <programlisting>doc "Base type for higher-order abstract stuff."
shared abstract class AbstractMetaThingy() { ... }</programlisting>
    
    </section>
    
    <section id="compiletimesafety">
    <title>Compile-time safety for optional values and type narrowing</title>
    
    <para>
    There is no primitive null in Ceylon. The null value is an instance of 
    the class <literal>Nothing</literal> that is not assignable to user-defined 
    class or interface types. An <emphasis>optional type</emphasis> is a 
    union type like <literal>Nothing|String</literal>, which may be abbreviated
    to <literal>String?</literal>. An optional type is not assignable to a 
    non-optional type except via use of the special-purpose 
    <literal>if (exists ... )</literal> construct. Thus, the Ceylon compiler 
    is able to detect illegal use of a null value at compile time. Therefore, 
    there is no equivalent to Java's <literal>NullPointerException</literal> 
    in Ceylon.
    </para>
    
    <para>
    Similarly, there are no C-style typecasts in Ceylon. Instead, the 
    <literal>if (is ... )</literal> and <literal>case (is ... )</literal> 
    constructs may be used to narrow the type of an object reference without 
    risk of a <literal>ClassCastException</literal>. The combination of
    <literal>case (is ... )</literal> with algebraic types amounts to a kind
    of language-level support for the visitor pattern.
    </para>
    
    </section>
    
    <section id="firstclassfunctions">
    <title>First-class functions and higher-order programming</title>
    
    <para>
    Ceylon supports first-class function types and higher-order functions, 
    with minimal extensions to the traditional C syntax. A method declaration 
    may specify a <emphasis>callable parameter</emphasis> that accepts 
    references to other methods with a certain signature. 
    </para>
    
    <programlisting>String find(Boolean where(String string), String... strings) { ... }</programlisting>
    
    <para>
    The argument of such a callable parameter may be either a reference to a 
    named method declared elsewhere, or a new method defined inline as part of 
    the method invocation. A method may even return an invocable reference to 
    another method.</para>
    
    <programlisting>value matches = find((String s) !s.empty, "", "hello", "world");</programlisting>
    
    <!-- 
    <para>
    Finally, nested method declarations receive a closure of 
    immutable references defined in the surrounding scope.
    </para>
    -->
    </section>
    
    <!--
    <section id="lazyevaluationpassbyreference">
    <title>Lazy evaluation and pass by reference</title>
    
    <para>
    Using a "trick" in the Ceylon type system, it's possible to take advantage 
    of lazy evaluation of expressions and pass by reference for attributes.
    </para>
    
    </section>
    -->
    
    <section id="sequences">
    <title>Sequences and comprehensions</title>
    
    <para><emphasis>Sequences</emphasis> are Ceylon's version of arrays. 
    However, the <literal>Sequence</literal> interface does not provide 
    operations for mutating the elements of the sequence.</para>
    
    <para>Ceylon distinguishes between empty and nonempty sequences. An 
    instance of <literal>Sequence</literal> is has at least one element. An 
    empty sequence is an instance of the type <literal>Empty</literal>. It's 
    very common to work with a <emphasis>sequence type</emphasis> like
    <literal>Empty|Sequence&lt;String&gt;</literal>, which may be abbreviated
    <literal>String[]</literal>. The special-purpose 
    <literal>if (nonempty ... )</literal> construct narrows a sequence type
    to an instance of <literal>Sequence</literal>.</para>
    
    <para>Sequences may be instantiated using a streamlined syntax.</para>
    
    <programlisting>String[] languages = { "Java", "Python", "Ceylon", "Smalltalk", "ML" };</programlisting>
    
    <para><emphasis>Comprehensions</emphasis> are an expressive syntax for
    filtering and transforming streams of values. For example, they may be 
    used when instantiating a sequence or collection:</para>
    
    <programlisting>value adults = { for (p in people) if (p.age>18) p.name };</programlisting>
    <programlisting>value peopleByName = HashMap { for (p in people) p.name->p };</programlisting>
        
    </section>
    
    <section id="controlflow">
    <title>Control flow and exceptions</title>
    
    <para>
    Ceylon's built in control flow structures look very similar to the 
    traditional constructs found in C, C# and Java. However, there are
    some differences. There is no <literal>do/while</literal> loop, or 
    C-style <literal>for</literal> loop. Furthermore, the syntax and 
    semantics of Ceylon's <literal>switch</literal> is quite different.
    </para>
    
    <para>
    Ceylon features an exceptions model inspired by Java and C#. Checked 
    exceptions are not supported.
    </para>
    
    </section>
    
    <section id="operatorsandoperatorpolymorphism">
    <title>Operators and operator polymorphism</title>
    
    <para>
    Ceylon features a rich set of operators, including most of the operators 
    supported by C and Java. True operator overloading is not supported. 
    However, each operator is defined to act upon a certain class or interface 
    type, allowing application of the operator to any class which extends or 
    satisfies that type. For example, the <literal>+</literal> operater may be
    applied to any class that satisfies <literal>Summable</literal> interface. 
    This approach is called <emphasis>operator polymorphism</emphasis>.
    </para>
    
    </section>
    
    <section id="numerictypes">
    <title>Numeric types</title>
    
    <para>Ceylon's numeric type system is much simpler than C, C# or Java, with
    exactly two built-in numeric types (compared to six in Java and eleven in 
    C#). The built-in types are classes representing integers and floating point 
    numbers. <literal>Integer</literal> and <literal>Float</literal> values are 
    64 bit by default, and may be optimized for 32 bit architectures via use of 
    the <literal>small</literal> annotation.</para>
    
    <para>The module <literal>ceylon.math</literal> provides two additonal
    numeric types representing arbitrary precision integers and arbitrary 
    precision decimals.</para>
    
    </section>
    
    <!-- 
    <section id="dimensioned types">
    <title>Dimensioned types</title>
    
    <para>Ceylon supports <emphasis>dimensional type parameters</emphasis>,
    allowing types with fixed dimensions such as vectors or matrices to be
    represented within the type system, and enabling compile-time bounds 
    checking of indexing operations.</para>
    
    </section>
    -->
    
    <section id="structureddata">
    <title>User interfaces and structured data</title>
    
    <para>
    Ceylon introduces a set of syntax extensions that support the definition 
    of domain-specific languages and expression of structured data. These 
    extensions include specialized syntax for initializing objects and 
    collections and expressing literal values of user-defined types. The goal 
    of this facility is to replace the use of XML for expressing hierarchical 
    structures such as documents, user interfaces, configuration and serialized 
    data.
    </para>
    
    <programlisting>Html page {
    Head head { 
        title="Hello"; 
    }
    Body body { 
        P {
            css = "greeting"; 
            "Hello, World!" 
        } 
    }
}</programlisting>
    
    <para>
    An especially important application of this facility is Ceylon's 
    built-in support for program element annotations.
    </para>
    
    </section>
    
    <section id="metaprogramming">
    <title>Metaprogramming</title>
    
    <para>
    Ceylon provides sophisticated support for meta-programming, including a 
    typesafe <emphasis>metamodel</emphasis> and <emphasis>events</emphasis>. 
    Generic code may invoke members reflectively and intercept member invocations. 
    This facility is more powerful, and much more typesafe, than reflection in 
    Java.
    </para>
    
    <!--  
    <para>
    An even more powerful feature is <emphasis>metatypes</emphasis>&mdash;a
    type definition may introduce a user-defined interface to its metamodel,
    allowing a form of generic programing with polymorphic abstraction at the 
    meta level. This facility is an object-oriented flavor of the notion of 
    "type classes" in Haskell.
    </para>
    -->
    </section>
    
    <section id="modularity">
    <title>Modularity</title>
    
    <para>
    Ceylon features language-level <emphasis>package</emphasis> and 
    <emphasis>module</emphasis> constructs, along with language-level access 
    control via the <literal>shared</literal> annotation which can be used to 
    express block-local, package-private, module-private, and public visibility 
    for program elements. There's no equivalent to Java's <literal>protected</literal>.
    </para>
    
    </section>
    
    </section>
    
    <!-- 
    <section id="sdkmodules">
        <title>Modules included in the SDK</title>
    
    <para>The Ceylon SDK includes the following important modules:</para>
    
    <itemizedlist>
        <listitem>
            <para><literal>ceylon.language</literal> - basic types provided to support
            built-in language features</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.module</literal> - the module runtime (based on
            JBoss Modules)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.collection</literal> - the collections framework
            (with the underlying implementation provided by the Java collections
            framework)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.datetime</literal> - support for representing
            dates and times (based on JSR-310)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.security</literal> - the security API</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.io</literal> - the I/O facility (based on 
            <literal>java.io</literal>)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.concurrent</literal> - the concurrency API (based
            on JSR-166)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.http</literal> - the HTTP client and server (based 
            on JBoss Netty)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.transaction</literal> - the transaction server (based 
            on JBoss Transactions)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.rdbc</literal> - relational database connectivity 
            (based on JDBC)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.message</literal> - the message server (based 
            on JBoss HornetQ)</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.xml</literal> - the XML parser</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.html</literal> - the HTML construction kit</para>
        </listitem>
        <listitem>
            <para><literal>ceylon.compiler</literal> - a compiler for Ceylon source
            code</para>
        </listitem>
    </itemizedlist>
    </section>
    -->
    
    <!--
    <section id="parsingceylon">
        <title>Parsing and compiling the Ceylon language</title>
        
        <para>The Ceylon language has been shown to be lexable and parseable using 
        a context-free ANTRL grammar with no hand-coded special cases.</para>
        
        <para>Ceylon is a language for the Java Virtual Machine, therefore Ceylon
        programs compile to a set of platform-independent <literal>.class</literal> 
        files that comply with the published specification for the Java class file 
        format.</para>
        
        <para>The Ceylon compiler consists of:</para>
        
        <itemizedlist>
            <listitem>
                <para>a generated parser and syntax tree,</para>
            </listitem>
            <listitem>
                <para>a handwritten type analyzer and type checker, and</para>
            </listitem>
            <listitem>
                <para>a backend that integrates the type analyzer with <literal>javac</literal>
                by transforming the Ceylon syntax tree to a Java syntax tree.</para>
            </listitem>
        </itemizedlist>
        
        <para>The type analyzer and backend are developed completely independently,
        and the parser, syntax tree, and type analyzer may be reused separately.</para>
        
    </section>
    -->
    
{'fraction_non_alphanumeric': 0.07683123085708353, 'fraction_numerical': 0.0006575645884164806, 'mean_word_length': 2.883736559139785, 'pattern_counts': {'":': 0, '<': 1106, '<?xml version=': 0, '>': 1108, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '92391', 'n_tokens_mistral': 15509, 'n_tokens_neox': 14323, 'n_words': 6161}