implement namespace & use nodes (fix glayzzle#35)

Author: ichiriac

docs/AST.md

@@ -2,6 +2,44 @@
 
 # AST
 
+The AST builder class
+
+**Parameters**
+
+-   `withPositions`  
+-   `withSource`  
+
+**Properties**
+
+-   `withPositions` **[Boolean](#boolean)** Should locate any node (by default false)
+-   `withSource` **[Boolean](#boolean)** Should extract the node original code (by default false)
+
+## position
+
+Create a position node from specified parser
+including it's lexer current state
+
+**Parameters**
+
+-   `Parser`  
+-   `parser`  
+
+Returns **[Position](#position)** 
+
+## prepare
+
+Prepares an AST node
+
+**Parameters**
+
+-   `kind` **([String](#string) | null)** Defines the node type
+    (if null, the kind must be passed at the function call)
+-   `parser` **Parser** The parser instance (use for extracting locations)
+
+Returns **[Function](#function)** 
+
+# AST
+
 ## Class hierarchy
 
 -   [Location](#location)
@@ -21,6 +59,7 @@
         -   [Variable](#variable)
         -   [ConstRef](#constref)
         -   [Operation](#operation)
+            -   [Coalesce](#coalesce)
             -   [Post](#post)
         -   [Literal](#literal)
             -   [Boolean](#boolean)
@@ -33,7 +72,6 @@
         -   [Eval](#eval)
         -   [Exit](#exit)
         -   [Clone](#clone)
-        -   [Coalesce](#coalesce)
         -   [Include](#include)
         -   [Assign](#assign)
         -   [If](#if)
@@ -46,6 +84,8 @@
         -   [Try](#try)
         -   [Catch](#catch)
         -   [Call](#call)
+        -   [UseGroup](#usegroup)
+        -   [UseItem](#useitem)
         -   [Block](#block)
             -   [Program](#program)
             -   [Namespace](#namespace)
@@ -74,31 +114,17 @@
 -   `withPositions`  
 -   `withSource`  
 
-## prepare
+## position
 
-Prepares an AST node
+Create a position node from specified parser
+including it's lexer current state
 
 **Parameters**
 
--   `kind` **([String](#string) | null)** Defines the node type
-    (if null, the kind must be passed at the function call)
--   `parser` **Parser** The parser instance (use for extracting locations)
-
-Returns **[Function](#function)** 
+-   `Parser`  
+-   `parser`  
 
-# AST
-
-The AST builder class
-
-**Parameters**
-
--   `withPositions`  
--   `withSource`  
-
-**Properties**
-
--   `withPositions` **[Boolean](#boolean)** Should locate any node (by default false)
--   `withSource` **[Boolean](#boolean)** Should extract the node original code (by default false)
+Returns **[Position](#position)** 
 
 ## prepare
 
@@ -240,7 +266,7 @@ Defines a clone call
 
 # Coalesce
 
-**Extends Statement**
+**Extends Operation**
 
 Verify is the test property is defined and is not null, and returns
 is, otherwise returns the ifnull expression.
@@ -441,7 +467,33 @@ Defines an identifier node
 **Properties**
 
 -   `name` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** 
--   `fqn` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** 
+-   `resolution` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** 
+
+## UNQUALIFIED_NAME
+
+This is an identifier without a namespace separator, such as Foo
+
+Type: [String](#string)
+
+## QUALIFIED_NAME
+
+This is an identifier with a namespace separator, such as Foo\\Bar
+
+Type: [String](#string)
+
+## FULL_QUALIFIED_NAME
+
+This is an identifier with a namespace separator that begins with
+a namespace separator, such as \\Foo\\Bar. The namespace \\Foo is also
+a fully qualified name.
+
+Type: [String](#string)
+
+## RELATIVE_NAME
+
+This is an identifier starting with namespace, such as namespace\\Foo\\Bar.
+
+Type: [String](#string)
 
 # If
 
@@ -776,6 +828,42 @@ Defines a trait usage
 
 Deletes references to a list of variables
 
+# UseGroup
+
+**Extends Statement**
+
+Defines a use statement (with a list of use items)
+
+**Properties**
+
+-   `name` **([Identifier](#identifier) | null)** 
+-   `type` **([String](#string) | null)** Possible value : function, const
+-   `item` **[Array](#array)<[UseItem](#useitem)>** 
+
+# UseItem
+
+**Extends Statement**
+
+Defines a use statement (from namespace)
+
+**Properties**
+
+-   `name` **[Identifier](#identifier)** 
+-   `type` **([String](#string) | null)** Possible value : function, const
+-   `alias` **([String](#string) | null)** 
+
+## TYPE_CONST
+
+Importing a constant
+
+Type: [String](#string)
+
+## TYPE_FUNC
+
+Importing a function
+
+Type: [String](#string)
+
 # Variable
 
 **Extends Expression**

docs/parser.md

@@ -443,51 +443,81 @@ start ::= (namespace | top_statement)*
 
 # read_namespace
 
+Reads a namespace declaration block
+
 ```ebnf
 namespace ::= T_NAMESPACE namespace_name? '{'
    top_statements
 '}'
 | T_NAMESPACE namespace_name ';' top_statements
 ```
 
+Returns **Namespace** 
+
 # read_namespace_name
 
-reading a namespace name
+Reads a namespace name
 
 ```ebnf
  namespace_name ::= T_NS_SEPARATOR? (T_STRING T_NS_SEPARATOR)* T_STRING
 ```
 
-# read_use_statements
+Returns **Identifier** 
+
+# read_use_statement
+
+Reads a use statement
 
 ```ebnf
-use_statements ::=
-     use_statements ',' use_statement
-     | use_statement
+use_statement ::= T_USE
+  use_type? use_declarations |
+  use_type use_statement '{' use_declarations '}' |
+  use_statement '{' use_declarations(=>typed) '}'
+';'
 ```
 
-# read_inline_use_declaration
+Returns **UseGroup** 
+
+# read_use_declaration
+
+Reads a use declaration
 
 ```ebnf
- inline_use_declaration ::= ...
+use_declaration ::= use_type? namespace_name use_alias
 ```
 
-# read_use_statement_mixed
+Returns **UseItem** 
+
+# read_use_declarations
+
+Reads a list of use declarations
 
 ```ebnf
-  use_statement_mixed ::=
-      use_statement  (T_AS T_STRING | '{' read_inline_use_declaration '}' )
-      (',' read_use_statement)*
+use_declarations ::= use_declaration (',' use_declaration)*
 ```
 
-# read_use_statement
+Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<UseItem>** 
+
+# read_use_alias
+
+Reads a use statement
 
 ```ebnf
-use_statement ::= (
- (T_FUNCTION | T_CONST)? namespace_name
- )
+use_alias ::= (T_AS T_STRING)?
+```
+
+Returns **([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) | null)** 
+
+# read_use_type
+
+Reads the namespace type declaration
+
+```ebnf
+use_type ::= (T_FUNCTION | T_CONST)?
 ```
 
+Returns **([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) | null)** Possible values : function, const
+
 # resolve_special_chars
 
 Unescape special chars

src/ast.js

@@ -27,6 +27,7 @@ var Position = require('./ast/position');
  *     - [Variable](#variable)
  *     - [ConstRef](#constref)
  *     - [Operation](#operation)
+ *       - [Coalesce](#coalesce)
  *       - [Post](#post)
  *     - [Literal](#literal)
  *       - [Boolean](#boolean)
@@ -39,7 +40,6 @@ var Position = require('./ast/position');
  *     - [Eval](#eval)
  *     - [Exit](#exit)
  *     - [Clone](#clone)
- *     - [Coalesce](#coalesce)
  *     - [Include](#include)
  *     - [Assign](#assign)
  *     - [If](#if)
@@ -52,6 +52,8 @@ var Position = require('./ast/position');
  *     - [Try](#try)
  *     - [Catch](#catch)
  *     - [Call](#call)
+ *     - [UseGroup](#usegroup)
+ *     - [UseItem](#useitem)
  *     - [Block](#block)
  *       - [Program](#program)
  *       - [Namespace](#namespace)
@@ -86,6 +88,20 @@ var AST = function(withPositions, withSource) {
   this.withSource = withSource;
 };
 
+/**
+ * Create a position node from specified parser
+ * including it's lexer current state
+ * @param {Parser}
+ * @return {Position}
+ */
+AST.prototype.position = function(parser) {
+  return new Position(
+    parser.lexer.yylloc.first_line,
+    parser.lexer.yylloc.first_column,
+    parser.lexer.yylloc.first_offset
+  );
+};
+
 /**
  * Prepares an AST node
  * @param {String|null} kind - Defines the node type
@@ -96,11 +112,7 @@ var AST = function(withPositions, withSource) {
 AST.prototype.prepare = function(kind, parser) {
   var start = null;
   if (this.withPositions || this.withSource) {
-    start = new Position(
-      parser.lexer.yylloc.first_line,
-      parser.lexer.yylloc.first_column,
-      parser.lexer.yylloc.first_offset
-    );
+    start = this.position(parser);
   }
   var self = this;
   // returns the node
@@ -199,6 +211,8 @@ AST.prototype.prepare = function(kind, parser) {
   require('./ast/traituse'),
   require('./ast/try'),
   require('./ast/unset'),
+  require('./ast/usegroup'),
+  require('./ast/useitem'),
   require('./ast/variable'),
   require('./ast/while')
 ].forEach(function (ctor) {

src/ast/coalesce.js

@@ -4,20 +4,20 @@
  * @url http://glayzzle.com
  */
 
-var Statement = require('./statement');
+var Operation = require('./operation');
 var KIND = 'coalesce';
 
 /**
  * Verify is the test property is defined and is not null, and returns
  * is, otherwise returns the ifnull expression.
  * @constructor Coalesce
- * @extends {Statement}
+ * @extends {Operation}
  * @property {Expression} test - The expression to be testes
  * @property {Expression} ifnull - The returned expression if test is null
  * @see https://wiki.php.net/rfc/isset_ternary
  */
-var Coalesce = Statement.extends(function Coalesce(test, ifnull, location) {
-  Statement.apply(this, [KIND, location]);
+var Coalesce = Operation.extends(function Coalesce(test, ifnull, location) {
+  Operation.apply(this, [KIND, location]);
   this.test = test;
   this.ifnull = ifnull;
 });