= Program Structure = 

(This page needs expansion/completion)

A cobra program is composed of a series of source modules - These modules can be either
cobra or source code for the back end compiler (C# currently, eventually a range of other 
backend compilers (java, objective-C) is expected to be supported).

Backend source modules are passed to the backend compiler without change. 
Cobra modules are validated and translated to backend source code and also passed to the 
backend compiler for compilation. 
The result is assembled into an executable, library or other binary file for execution or use with an executable.

== Cobra Modules ==

Within a cobra source module the code is a sequence of clauses or directives 
optionally enclosed in a namespace definition. 
Within these clauses are subparts specific to the type of clause 
and within that cobra code and expressions. 

A cobra module can start with an optional !DocString and/or a comment block prior to 
any code clauses.

Generally comments are like whitespace - they can be placed anywhere in a source module.
!DocStrings are more specific, being recognised only in a few natural positions within the
code(Top of file, first lines of  class/struct/interface/enum decls, 
after method/var decls, ...)

Each major clause is defined by subsequent code at an increased indentation level 
except for 'use' and 'sig' which consume tokens to the end of the current line.

Clauses are:
    * use       - specify a namespace and its contents to be used by this module.
    * namespace - specify the namespace the enclosed code resides in.
    * class     - specify a custom (reference) type grouping together variables of other types, methods and events.
    * struct    - specify a (lightweight) custom value type (similar though more limited than a class).  
    * interface - provide an interface definition that other classes and structs must conform to.
    * mixin     - specify a definition for a piece of capability that can be injected (mixed-in) to classes across any class hierarchy. 
    * enum      - specify an enumerated type that other items can reference.
    * extend    - specify an extension to an existing type.
    * sig (signature) - describe a type for a method signature (C# calls these delegates).

A namespace may contain any of the above clauses (except namespace). If a namespace is
not provided the module code is built as if it had been specified in the global namespace.

In addition there are two keys 
    * assembly - specify Attributes for this assembly 
    * '%%' ( deprecated) or '@' - specify a directive to the cobra compiler.
      See [wiki:CompilerDirectives compiler directives]

== Grammar ==
{{{
use NAMESPACE_NAME

namespace NAMESPACE_NAME
    NAMESPACE_BLOCK
    
class CLASS_NAME 
    [inherits CLASS_NAME] 
    [implements INTERFACE_NAME]
    [adds MIXIN_NAME]
    [is ISNAMES_LIST]
    CLASS_BLOCK
        
struct STRUCT_NAME
    [inherits CLASS_NAME] 
    [implements INTERFACE_NAME]
    [adds MIXIN_NAME]
    [is ISNAMES_LIST]
    CLASS_BLOCK

interface INTERFACE_NAME
    CLASS_BLOCK
    
mixin MIXIN_NAME
    CLASS_BLOCK

enum ENUM_NAME [of TYPE]
    ENUM_VALUE [ = IntValue] [, ENUM_VALUE [= IntValue]... ]
    
extend CLASS_NAME
    [ is ISNAMES_LIST]
    [ has ATTRIBUTESLIST]
    [ where GENERICCONSTRAINTS]
    [ inherits CLASS_NAME]
    [ implements INTERFACE_NAME]
    CLASS_EXTENSION_BLOCK

event NAME as TYPE 
    [ is ISNAMES_LIST]
    [ has ATTRIBUTES]

sig TYPENAME(ARGS)
sig TYPENAME as RETURNTYPE    
sig TYPENAME(ARGS) as RETURNTYPE    

assembly has ATTRIBUTE_NAME {has ATTRIBUTE_NAME}...

@COMPILER_DIRECTIVE_ID {DIRECTIVE_ARGS}
%%COMPILER_DIRECTIVE_ID {DIRECTIVE_ARGS}
}}}

== Platform ==

Currently the translation is only to C# and therefore only C# code is the non cobra source
supported.

This is available for Windows platforms supporting C# using the Microsoft csharp compiler
and on other platforms supported by [http://www.go-mono.org mono]  and the mono compiler.

== Examples ==
{{{
#!cobra
"""
Example DocString for a module.

This program doesnt do anything useful or realistic beyond being an example of
a cobra program and showing some of the language constructs.
"""

#Assembly attributes
assembly has SharedAttribute

use System.Text.RegularExpressions

%%number decimal

namespace Hops
    class Example
        var counter = 0
        
        def incCount(i as int)
            .counter += i
        
        def main is shared
            e = Example()
            e.incCount(10)
            assert e.counter == 10
            
    class AnotherExample
        pass
        
    struct Point
        var x = 0
        var y = 0
    
    enum ColorPart
        """What is the color of magic"""
        Red
        Green
        Blue
        Octarine
   
    sig VoidDelegate   # method taking no args and having no return type
    sig NullStringDelegate(s as String) as String? # method taking String and returning String or null

    extend String
        def fmt(args as vari Object) as String
            """
            Returns the string with any given args applied to it via String.Format
            """
            test
                s = '{0}is{1}'
                assert s.fmt('0', '1') =='0is1'
                assert s.fmt(2, 1) == '2is1'
                assert s.fmt('One', 'NotTwo') == 'OneisNotTwo'
                assert s.fmt(nil, nil) == 'is'
            body
                return String.format(this, args) to !
}}}            

== Notes ==

See subsequent expansion pages for each of the above clauses/directives.

[wiki:LanguageTopics Back to Language Topics]