Changes between Initial Version and Version 1 of Program

Timestamp:

02/15/10 00:46:01 (15 years ago)

Author:

hopscc

Comment:

first stab at describibg cobra program

Program

@@ +1 @@
+= 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 ==
+{{{
+"""
+Example DocString for this module
+"""
+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]