Namespace and using clause

[smedilol]

See #995

namespace and using clause :

• Type and procedure can now be qualified with a namespace
• Search of types and procedure without namespace qualification must use using clauses

Syntax rules

• The namespace is declared in the program id statement after the name of the program and clause recursive | common | initial| and before authoring properties (author | installation | date-written | date-compiled | security).

  • Syntax is NAMESPACE namespace_value followed by an optional .

• namespace is NOT a keyword. It's a contextual keywords in program id statement.

  • It means a program cannot be named namespace

• operator :: is used to separate part of a namespace. All characters allowed in variable name are allowed in a namespace part.

  • com::ei.::anking::currentaccount
  • In this example, there are 4 parts in the namespace

• There is no limit to a namespace length.

• using clause is new statement. It must be in identification division after the name of the program, recursive | common | initial|, namespace and authoring properties (author | installation | date-written | date-compiled | security).

  • Syntax is using namespace_value. Character . is mandatory here.
  • you can add multiples using clause.

• When you reference a type or a procedure you can prefix it with the full namespace and its main enclosing program

  • Only the type/procedure name
  • The type/procedure name prefixed with its main enclosing program
    • if it's the current program or if this is a program in a namespace referenced by an using clause.
    • Nested and stacked program are not used. Another issue will be about visibility of type inside a program : a type name must be unique in a source file.
  • The full namespace, its main enclosing program and the type/procedure name

• We consider that a program is always public, which means you can always reference it from another program.

• Syntax ::namespace, ::namespace::Type, ::namespace::Procedure if there is an ambiguity in a namespace, type or procedure reference (todo : detail how it works)

Rules:

• TCNS_ONLY_MAIN_CAN_DECLARE_NS You can declare only 1 namespace in a program. The namespace apply to all programs in the source file.
  • nested and stacked programs inherits the namespace of the main program
• TCNS_ALL_PGMS_CAN_USE_USING All programs in a source file can use using clause
• a referenced namespace must exists
• TCNS_USING_SAME_NS warning : if multiples using clause reference the same namespace
• TCNS_USING_CURRENT_NS warning : if you reference the namespace of the current program
• TCNS_AMBIGUITY_RESOLVED_BY_PREFIX If there is ambiguity in a type or procedure name, you must qualify it to remove the ambiguity
• TCNS_AMBIGUITY_RESOLVED_BY_USING You can add using clause to avoid to use the full namespace when referencing type or procedure.
  • Again, if there is ambiguity, you must add a qualifier (main enclosing program)
• Visibility are resolved at compilation time

Euro Information Rules

Custom rules for our company:

• TCNS_EI_SHOULD_STARTS_WITH_COMEI A namespace must start with com::ei. Raise a warning otherwise
  • Not an error, because we can retrieve code from other company
• TCNS_EI_MUST_HAVE_4_PARTS if the namespace starts with com::ei, then there must be at least 4 parts after it
  • com::ei::banking::currentaccount is invalid
  • com::ei::part1::part2::part3::part4 is OK
  • com::ei::part1::part2::part3::part4::part5 is OK

Example

       id division.
       program-id. PgmA.
       namespace banking::currentaccount.
       data division.
       working-storage section.
       01 MyType typedef strict public pic X .  
       
       end program PgmA.

       id division.
       program-id. PgmB.
       namespace banking::currentaccount::bill.
       data division.
       working-storage section.

      *KO because there is no using and no program prefix
       01 var1 type MyType. 
      *KO, because PgmA is not referenced by an using clause
       01 var2 type PgmA::MyType.
      * full namespace Ok
       01 var3 type banking::currentaccount::PgmA::MyType
       
       end program PgmB.

       id division.
       program-id. PgmC.
       namespace banking::currentaccount::bill.
      *Using clause = allow to access all type in this namespace without namespace or program prefix
       using banking::currentaccount.
       data division.
       working-storage section.

      * Ko, because we need at least the program name PgmA to find the type
       01 var1 type MyType. 
      * Ok, because we can find PgmA with the using clause
       01 var2 type PgmA::MyType. 
      * full namespace Ok
       01 var3 type banking::currentaccount::PgmA::MyType 
       
       end program PgmC.

Code generation in Cobol 85

• TCNS_CGEN_COMMENT_NS_USING Codegen must comment all namespace and using clauses
• TCNS_CGEN_COMMENT_FULLY_QUALIFIED The fully qualified name of type/procedure must be kept in comment. Otherwise there is no change for type and procedure.

Documentation

Update pages: https://github.com/TypeCobolTeam/TypeCobol/wiki/Namespaces which explain the concept of namespace https://github.com/TypeCobolTeam/TypeCobol/wiki/SyntaxRefNamespaces which list all syntax and semantic rules https://github.com/TypeCobolTeam/TypeCobol/wiki/CodegenNamespaces which explain rules about code generation