<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.1" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xila="http://www.w3.org/2001/XInclude/local-attributes"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:trans="http://docbook.org/ns/transclusion"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:m="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <title>Transcend</title>

  <para>Transcend is a compilation phase and process of reasoning about
  program in order to influence compilation.</para>

  <para>First, compiler extracts <emphasis>annotations</emphasis> from source
  code and other facts from number of sources to form a complete
  <emphasis>logic program</emphasis>. Then, solver processes logic program and
  outputs decisions that affect and control compilation process in a number of
  ways.</para>

  <section>
    <title>Annotations' Syntax</title>

    <para>Xreate's annotations comprise optional supplementary information
    that is processed by compiler along with a source code proper and able to
    affect compilation process. Annotations have form of expressions that
    consist of following elements:</para>

    <informaltable>
      <tgroup cols="2">
        <colspec colwidth="183*"/>

        <colspec colwidth="817*"/>

        <tbody>
          <row>
            <entry>Literals</entry>

            <entry>Strings, numbers. Example:
            <code>5, "success"</code></entry>
          </row>

          <row>
            <entry>Predicates</entry>

            <entry>Predicates have zero or more arguments. Example:
            <code>final, status(broken), version("12.0.3", unstable)</code></entry>
          </row>

          <row>
            <entry>Negation</entry>

            <entry>Example: <code>-i12n, -access(allowed)</code></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>Various Xreate's entities can be annotated. At the time following
    entities are supported:</para>

    <informaltable>
      <tgroup cols="4">
        <tbody>
          <row>
            <entry><link xlink:href="#expression-and-identifiers">Expressions
            and Identifiers</link></entry>

            <entry><link xlink:href="#code-blocks-and-context">Code blocks and
            context</link></entry>

            <entry><link xlink:href="/w/syntax#functions">Functions</link> and
            <link xlink:href="/w/syntax#function-guards">Function
            Guards</link></entry>

            <entry><link
            xlink:href="/w/syntax/modules#module-annotations">Modules</link></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <section>
      <title>Expression and Identifiers</title>

      <synopsis>SYNTAX:
//expression// **::** //type//**;** //annotation-list//.</synopsis>

      <itemizedlist>
        <listitem>
          <para><emphasis>type</emphasis> expression's type</para>
        </listitem>

        <listitem>
          <para><emphasis>annotation-list</emphasis> one or more annotation
          attached to the expression. Annotations are delimited by
          semicolon</para>
        </listitem>
      </itemizedlist>

      <para>Example:</para>

      <programlisting xml:id="Expressions1">test = function:: int 
{
  x = 5:: int; arithmetic(fast).                           //annotation applied to an identifier
  y = (x - 8:: int; arithm_optimization(off)) * 2:: float. //annotation applied to a nested expression
  
  x+y
}</programlisting>

      <note>
        <para>For readability sake compound statements(e.g. <link
        xlink:href="/w/syntax#loop-statements">loops</link>) have different
        syntax for an annotations. See particular statement's <link
        xlink:href="/w/syntax">syntax</link> for details</para>
      </note>
    </section>

    <section>
      <title>Code Blocks and Context</title>

      <synopsis>SYNTAX:
**context** :: //annotations-list//.</synopsis>

      <itemizedlist>
        <listitem>
          <para><emphasis>annotations-list</emphasis> List of annotation
          delimited by semicolon</para>
        </listitem>
      </itemizedlist>

      <para>Code block annotations called <emphasis>context</emphasis>.
      Keyword <code>context</code> used to declare annotation within enclosing
      code block.</para>

      <para>Example:</para>

      <programlisting xml:id="Codeblocks1">test = function:: int
{
  context:: arithm_optimization(off).

  x = 10 :: int.
  2 * x - 16
}</programlisting>
    </section>

    <section>
      <title>Special Annotations</title>

      <para>There are some annotations in Xreate that have special
      meaning</para>

      <informaltable>
        <tgroup cols="2">
          <colspec colwidth="201*"/>

          <colspec colwidth="799*"/>

          <tbody>
            <row>
              <entry><code>entry</code></entry>

              <entry>Specifies entry point of a program. See <link
              xlink:href="/w/syntax#functions">Function Syntax</link></entry>
            </row>

            <row>
              <entry><code>final</code></entry>

              <entry>Specifies fixed point of loop statements. See <link
              xlink:href="/w/syntax#loop-statement">Loop
              Statement</link></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </section>
  </section>

  <section>
    <title>Annotations and Reasoning</title>

    <para>Annotations is a mechanism to express an additional pieces of
    information and can occur in source code or accompanying files. They are
    of declarative nature in a sense that they express specific properties of
    and relations between different entities, such as: identifiers,
    statements, code blocks, functions, modules or even a whole
    program.</para>

    <para>Annotations are <emphasis>facts</emphasis> about source code
    provided by developer in explicit form. Beside annotations there are other
    sources of information, e.g. implicit facts that are automatically
    inferred by various analysis phases to express useful insights regarding
    analysed code. Such pieces aren't exposed directly to a developer but
    accessed and used internally at reasoning phase along with annotations.
    All types of input are summed up below:</para>

    <informaltable>
      <tgroup cols="2">
        <colspec colwidth="287*"/>

        <colspec colwidth="713*"/>

        <tbody>
          <row>
            <entry>Explicit annotations in source files</entry>

            <entry>Annotations provided by developer in order to explicitly
            affect compilation</entry>
          </row>

          <row>
            <entry>Code Analysis</entry>

            <entry>Different code analyses during compilation provide
            information implicitly inferred from source code</entry>
          </row>

          <row>
            <entry>Supervision</entry>

            <entry>External facts that reflect requirements, describe hardware
            and/or environment where compilation takes place or program is
            supposed to work. There are many supervision layers possible, from
            custom compiler's mode, to OS- or computer- or even network-wide
            level. On other words, supervision covers local or client supplied
            annotations</entry>
          </row>

          <row>
            <entry>Audit</entry>

            <entry>Third party supplied external information that reflect
            additional software properties, e.g. results of security
            audit</entry>
          </row>

          <row>
            <entry>Reasoning rules</entry>

            <entry>Reasoning infers additional facts from pool of previously
            gathered information. It is done by using <emphasis>resoning
            rules</emphasis> that govern reasoning process</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>

  <section>
    <title>Why Annotations Matter</title>

    <para>This section goes through differences that annotations have over
    traditional statements.</para>

    <section>
      <title>Extensible</title>

      <para>Annotations are not a part of language syntax and there is no
      predefined set of allowed annotations. Developer is free to define and
      use custom annotations to express desired properties without prior
      changes to compiler.</para>

      <note>
        <para>Yet there are several reserved annotations that have specific
        meaning in Xreate. See <link xlink:href="#special-annotations">special
        annotations</link> for details.</para>
      </note>
    </section>

    <section>
      <title>Indicative Nature</title>

      <para>Unlike language statements that have well defined compilation
      output, annotation do not. They are rather of suggestive nature and
      actual impact depends on many factors. Annotations comprise an input for
      a reasoning procedure that ultimately determines how exactly influence
      compilation.</para>
    </section>

    <section>
      <title>Cooperation</title>

      <para>Annotations are gathered from different sources and this enables
      annotations to complement themselves. Compiler blends in annotations
      originated from various sources seamlessly and this allows to improve
      decisions quality.</para>
    </section>

    <section>
      <title>External Sources and Adaptability</title>

      <para>Annotations able to express not only properties of program itself
      but also properties of local environment(OS, computer, local network)
      where program is supposed to run. Thus compiler operates information
      inaccessible during software development and can't be reflected in the
      code otherwise. Compilation can be adjusted to a particular environment
      and functioning mode.</para>
    </section>

    <section>
      <title>Feedback</title>

      <para>Traditionally software has a rigid strictly defined hierarchical
      structure and interaction between components. More precisely, let's look
      at client-service code model. Service is done independently in order to
      work well with as wide as possible set of different clients. Thus
      service is unaware of exact characteristics of particular client code it
      works with. All burden of complying with interaction specification lies
      on a client.</para>

      <para>However client may use only small subset of service functionality
      or use it in specific and predictable order. Generally speaking, service
      by having additional information on particular client able to serve
      requests more efficiently in many cases.</para>

      <para>It can be conceptualized as a <emphasis>feedback</emphasis> from a
      client. Annotations is good candidate to express feedback to improve
      interaction quality.</para>
    </section>

    <section>
      <title>Resiliency</title>

      <para>As code grows and goes through multiple reworks and rewrites many
      initial assumptions about the code and relation between different parts
      change accordingly. Some implementation details and approaches became
      outdated and code quality deteriorates.</para>

      <para>DIfferent picture in case if code uses annotations to express
      important properties. Any changes in underlying code lead to a restart
      of reasoning procedure which adjust implementation decisions to be still
      optimal in changed environment.</para>
    </section>
  </section>
</chapter>
