updated readme

README.md

@@ -1,12 +1,170 @@
 rough
 ================================================================================
-Command line tool for PHP.
+Compiles embedded macros into PHP code.
+Add a comment into your code, run the macro command and rough generates code.
 
-Rough provides a IDE independent way to autmate repetive tasks.
+The macro markup is not removed so if update the macro the generated code is
+ipdated as well.
+
+Currently there are macros to:
+ - generate get methods
+ - generate set methods
+ - emulate traits in PHP 5.3
+
+Macro Syntax
+--------------------------------------------------------------------------------
+We will be using the get macro as an example.
+
+###basic syntax
+The basic syntax for a macro:
+
+    protected $name;
+    #@get name#
+    #@#
+
+Since The macro starts with a '#' it is a line comment.
+The first line starts the macro and the second marks the end of the macro.
+All code generated by the macro will go between those two lines. Any manual
+changes to the generated code will be overriden when the macro is executed.
+
+###shorthand notation
+When you first define a macro you can use a shorthand notation:
+
+    protected $name;
+    #@get name@#
+
+###arguments
+arguments are seperated by Whitesoace:
+
+    #@get name string@#
+
+The simplest form of argument is a *single word* in the example above the 'get'
+macro will be called with the two arguments 'name' and 'string'.
+
+If a argument contains a whitespaces surround it with double quotes to mark it
+as a *litteral*:
+
+    @get "invalid property name" string@#
+
+In the example above the 'get' macro will be called with the two arguments 
+'invalid property name' and 'string'.
+
+Some macros support passing a *array* as an arument:
+
+    protected
+        $name,
+        $email;
+
+    #@get [name email] string@#
+
+In the example above the 'get' macro will be called with the two arguments 
+array('name','email') and 'string'.
+The members of the array are seperated the same way normal arguments are so you 
+can place an literal in an array:
+
+    protected
+        $name,
+        $email;
+        
+    #@get [name email "invalid property name"] string@#
+
+Nested arrays are *not* supported.
 
 Macros
 --------------------------------------------------------------------------------
-Rough Macros use formated comments to generate code.
-If you use a macro parser on 
+###Get
+
+###Set
+
+###access
+
+###import and trait
+Traits are a great PHP 5.4 feature. In PHP 5.3 you can use rough to emulate some
+(but not all) features of traits.
+
+The import macros simply copies the body of one class into another.
+
+The advantageS over a manual copy and paste: 
+ - If your trait  implementation changes, the import macro will copy the new 
+   source code.
+ - If you build your project in PHP >=5.4.0 the macros will create proper traits
+
+Since this sollution does *not* support inheritance or namespaces you should
+only import classes which are designed to be use this way (pseudo traits).
+
+ - Pseudo traits are final.
+ - Psudo must always use fully qualified class names.
+
+Define a pseudo trait:
+
+    namespace vendor\product;
+    #@trait Unique@#
+    {
+        protected $uniqueId;
+        
+        public function getUniqueId(){...}
+        public function setUniqueId(\vendor\product\UniqueId $value){...}
+    }
+
+Use the pseudo trait:
+
+    namespace vendor\product;
+    class User:
+    {
+        #@import vendor\product\Unique@#
+    }
+
+####Results:
+
+#####PHP < 5.4.0
+
+The trait:
+
+    namespace vendor\product;
+    #@trait#
+    final class Unique
+    #@#
+    {
+        protected $uniqueId;
+        
+        public function getUniqueId(){...}
+        public function setUniqueId(\vendor\product\UniqueId $value){...}
+    }
+
+The using class:
+
+    namespace vendor\product;
+    class User:
+    {
+        #@import vendor\product\Unique@#
+        protected $uniqueId;
+        public function getUniqueId(){...}
+        public function setUniqueId(\vendor\product\UniqueId $value){...}
+        #@#
+    }
 
-    #@get public foo#
+
+#####PHP >= 5.4.0
+
+The trait:
+
+    namespace vendor\product;
+    #@trait#
+    trait Unique
+    #@#
+    {
+        protected $uniqueId;
+        
+        public function getUniqueId(){...}
+        public function setUniqueId(\vendor\product\UniqueId $value){...}
+    }
+
+The using class:
+
+    namespace vendor\product;
+    class User:
+    {
+        #@import vendor\product\Unique@#
+        use \vendor\product\Unique;
+        #@#
+    }