LmuPHP

General information

Outlines

Requirements

Purpose

Basic workflow

Requirements elicitation

UML diagram

Scope and limits

Syntax expected in the input files (.lmu)

root                     ::= ( class | association | comment )+

class                    ::= "$" class_name ( ":" class_parentclass )? "{"
    	                             ( "+" public_attribute | "#" protected_attribute | "-" private_attribute  )*
    	                             ( "+" public_method | "#" protected_method | "-" private_method  )*
                             "}"

class_name               ::= string

class_parentclass        ::= string

public_attribute         ::= attribute

protected_attribute      ::= attribute

private_attribute        ::= attribute

attribute                ::= attribute_name ( ":" attribute_type )?

attribute_name           ::= string

attribute_type           ::= possible_types

public_method            ::= method

protected_method         ::= method

private_method           ::= method

method                   ::= "@" method_name "(" ( method_parameters )? ")" ( ":" method_return_type )?

method_name              ::= string

method_parameters        ::= method_parameter ( "," method_parameter )*

method_parameter         ::= parameter_name ( ":" method_parameter_type )?

parameter_name           ::= string

method_parameter_type    ::= possible_types

method_return_type       ::= possible_types

association              ::= "& {" class_name1 ( "(" | ")" )? "-" class_name2 
                                   ( "#" cardinality ){0, 2} ( "~" association_name )? 
                             "}"

class_name1              ::= string

class_name2              ::= string

association_name         ::= string

comment                  ::= "/*" string "*/"

string                   ::= [ a-zA-Z0-9_ ]+

possible_types           ::= ( "int" | "string" | ... )+

cardinality              ::= ( "0..1" | "0..*" | "1" | "1..*" )+ 

• Pink elements (ex: (...)+) are elements to understand as if in a classic regular expression (+ is 1..*; * is 0..*; ? is 0..1; etc.).
• Elements in-between double quotes (ex: "&") are real text expected to be entered.
• Spaces and line breaks correspond here to the concatenation of two successive elements.
• Real spaces are not taken into consideration in the syntax. It will follow that if an association is for instance named with several words separated by spaces (ex: "consists of"), those words will eventually be concatenated (ex: "consistsof").
• In an association, the first cardinality corresponds to the direction class_name1-->class_name2
(to one instance of class_name1 corresponds X instances of class_name2); the possible second cardinality to the direction class_name2-->class_name1.
• In the declaration of an association, class1 )- class2 symbolizes that class1 HAS class 2 (aggregation relationship), while class1 (- class2 stands for class1 IS MADE OF class2 (composition relationship).

Examples:

  $ myClass:myAncestor {
    + myPublicAttribute1
    + myPublicAttribute2: int
    -@ myPrivateMethod1 (myParam1: string, myParam2): string
  }
	
  & { 
    myClassCompany - myClassPerson #0..* #1 ~ employs
  }	

Environment

Analysis & Design

• .lmu file parsing using the following class prototype:
  
  

  Parser

  + extractAll(&string originalText): aUMLDiagram /1 - extractAssociations(&string textToParse) /1 - extractClasses(&string textToParse) /1 - extractComments(&string textToParse) /1 - extractClassNameAndParent(&string textToParse, &aClass) /2 - extractAttributes(&string textToParse, &aClass) /2 - extractPublicAttribute(string attributeInfo, &aClass) /2 - extractProtectedAttribute(string attributeInfo, &aClass) /2 - extractPrivateAttribute(string attributeInfo, &aClass) /2 - extractMethods(&string textToParse, &aClass) /2 - extractPublicMethod(string methodInfo, &aClass) /2 - extractProtectedMethod(string methodInfo, &aClass) /2 - extractPrivateMethod(string methodInfo, &aClass) /2

  
  
  - This class is used to parse the .lmu input file, that is, creating a class aClass for each class found in that file, and a class anAssociation for each association found. The sets of classes and associations extracted are stored in an instance of class aUMLDiagram defined below.
  - The only input point is the extractAll public method. It outputs a reference on an instance of aUMLDiagram representing the content of the .lmu input file.
  - a & in front of a parameter type stands for a reference. It means that the parameter received might be modified by the function: for instance, &aClass will be a reference on an object aClass that will be needed to modify that object within the function (for example to add a new attribute to the object).
  - If a parent class is defined for the class that is currently extracted, then an association of kind "generalization" must ALSO be created between the two family classes.
  
  
• Extraction and storage of classes in PHP classes, instances of the prototype defined below:
  
  

  aClass

  - className: string - parentClassName: string - setOfPublicAttributes: array - setOfProtectedAttributes: array - setOfPrivateAttributes: array - setOfPublicMethods: array - setOfProtectedMethods: array - setOfPrivateMethods: array

  + setClassName(string) /1 + getClassName(): string /0 + setParentClassName(string) /1 + getParentClassName(): string /0 + addPublicAttribute(string attributeName, string attributeType) /2 + getPublicAttributes(): array /0 + addProtectedAttribute(string attributeName, string attributeType) /2 + getProtectedAttributes(): array /0 + addPrivateAttribute(string attributeName, string attributeType) /2 + getPrivateAttributes(): array /0 + addPublicMethod(string methodName, string methodType, array methodParams) /3 + getPublicMethods(): array /0 + addProtectedMethod(string methodName, string methodType, array methodParams) /3 + getProtectedMethods(): array /0 + addPrivateMethod(string methodName, string methodType, array methodParams) /3 + getPrivateMethods(): array /0 + exportToDot(): string /0 - exportAttributesToDot(string attributeType): string /0 - exportMethodsToDot(string methodType): string /0

  
  
  - As you can see, everything relies on encapsulation.
  - The parameters of addXXXAttribute(...) are respectively attribute name and attribute type.
  - getXXXAttributes() returns the set of XXX attributes sorted by alphabetical order.
  - The parameters of addXXXMethod(...) are respectively method name, method return type and an array containing an association parameter name - parameter type.
  - getXXXMethods() returns the set of XXX methods sorted by alphabetical order.
  - When generating the final UML diagram, exportToDot() defines the dot properties for the node corresponding to the current class: what will contain the node?
  - the methods exportAttributesToDot() and exportMethodsToDot() might be useful to avoid the repetition of the same kind of code within exportToDot(); attributeType and methodType can take values among "public", "protected" and "private".
  
  
• Extraction and storage of associations in PHP classes, instances of the prototype defined below:
  
  

  anAssociation

  - className1: string - className2: string - cardinality12: string - cardinality21: string - associationType: string - associationName: string

  + setClassName1(string) + getClassName1(): string + setClassName2(string) + getClassName2(): string + setCardinality12(string) + getCardinality12(): string + setCardinality21(string) + getCardinality21(): string + setAssociationType(string) + getAssociationType(): string + setAssociationName(string) + getAssociationName(): string + exportToDot(): string /1 /0 /1 /0 /1 /0 /1 /0 /1 /0 /1 /0 /0

  
  
  - Once more, everything relies on encapsulation.
  - The notation used for cardinalities is the following: to 1 instance of class 1 corresponds cardinality12 instances of class 2.
  - The parameter of setCardinalityXX and the attributes cardinalityXX belong to the set {"0..1", "0..*", "1", "1..*"} and is "0..*" by default.
  - The parameter of setAssociationType and the attributes associationType belong to the set {"classic", "generalization", "composition", "aggregation"} and is "classic" by default: for instance, "generalization" is set when class1 inherits from class2 (parent class); "composition" si set when class1 is made of class2; "aggregation" is set when class1 has class2.
  - When generating the final UML diagram, exportToDot() defines the dot properties for the edge corresponding to the current association: what kind of edge is it?
  
  
• UML diagram storage using the following class prototype:
  
  

  aUMLDiagram

  - setOfClasses: array of aClass - setOfAssociations: array of anAssociation

  + addClass(&aClass) /1 + getSetOfClasses(): array /0 + addAssociation(&anAssociation) /1 + getSetOfAssociations(): array /0 + exportToDot(): string /0

  
  
  - encapsulation is the master keyword here :)
  - setOfClasses is a set of instances of aClass (see above).
  - setOfAssociations is a set of instances of anAssociation (see above).
  - a & in front of a parameter type stands for a reference. It means that the parameter received might be modified by the function: for instance, &aClass will be a reference on an object aClass that will be needed to modify that object within the function (for example to add a new attribute to the object).
  - When generating the final UML diagram, exportToDot() defines the dot properties for the whole UML diagram (for all nodes and edges making it).
  
  
• Classes and associations validation
  
  A couple of things must be checked before launching the generation of the UML diagram: there should not be any inconsistency in the data provided in the .lmu file. The following conditions must therefore be fulfilled:
  
  Parsing validation:
  - of course, the .lmu input file should follow the expected syntax as defined above. In particular, there should not be anything else than comments or definition of classes or associations in the .lmu file. If there is still something in the input file after the parsing, then an error should occur,
  
  Classes validation:
  - all the classes used in a .lmu file must be defined in it: for instance, all the parentClasses must be defined, even if they are empty (= without any attributes nor methods),
  - a same .lmu file can not have several classes using the same names,
  - a class can not have itself as parent class (className != parentClassName),
  - a same class can not have several attributes called the same, no matter what their type is (public, protected or private),
  - a same class can FOR THE MOMENT not have several methods having the same name even if they have the same number of parameters,
  
  Associations validation:
  - a same .lmu file CAN have several associations linking the same classes (although it would be easier with only one association between 2 distinct classes),
  - an association has to link two existing classes, that is, two classes that have been declared in the .lmu file,
  - an association of type classic, composition or aggregation CAN link a class to itself,
  - an association of type else than generalization should not link a class with one of its ancestors,
  - the final semantics of the associations will not be checked.
  
  To help checking all the conditions above, one will have to use the following prototype:
  
  

  validator

  + checkNoRemainingFileContent(string remainingFileContent): bool /1 + checkClassNames(): bool /0 + checkHierarchicalClassNames(): bool /0 + checkParentClassNames(): bool /0 + checkAssociationClassNames(): bool /0

  
  
• Creation of the UML diagram.
  
  This will undoubtedly be the most difficult part of the program.
  
  The UML diagram can either be a .svg, a .jpg, a .gif or a .png file.
  
  I have been thinking of using GraphViz and especially dot to draw the UML diagrams more easily.
  To interface the program with dot, an extra class is needed; it looks like:
  
  

  aGraphViz

  - nodes: array - edges: array

  + addNode(string nodeName, array nodeProperties, string nodeGroup) /3 + addEdge(string startNodeName, string endNodeName, array edgeProperties) /3 + generateGraph(string fileType) /1 - generateGraphCommands(): string /0

  
  
  - In our case, a node will correspond to a full class; an edge to any kind of association (classic, generalization, aggregation, composition).
  
  
• PHP class generation with the right comments.
  
  For the moment, each class parsed in the .lmu file will be generated in one .class.php file. For instance, if both class1 and class2 are defined in the .lmu file, then 2 files class1.class.php and class2.class.php will be generated.
  
  Moreover, all the .class.php files created during a generation will be stored in a unique directory, which will be named by the current time of the generation (readable format): For instance if the generation is launched on 2003-07-21 at 10:00, then all the .class.php files will be created in a directory named 2003_07_21_10_00.
  
  The distinction public/protected/private will still be taken into consideration, even if the latest stable version of PHP does not support it.
  
  Example:

  <?php   /*******************************************************************     *     * @project        Project name    *                   Project description    * @project_author Florent Delgoulet (floodil@yahoo.com)    * @copyright 2003 Florent Delgouler    *     *******************************************************************    *     * @file        myClass.class.php    * @author      Florent Delgoulet (floodil@yahoo.com)    * @since       2003/07/24       * @last_update 2003/07/24    * @version     1.0    *     * Just an example on how a PHP class should be commented.    *    */       /**    * INCLUDES    */          // myParentClass handler   include_once("path/to/myParentClass.class.php");             class myClass extends myParentClass {     /**      * CLASS ATTRIBUTES      */          /** public attributes      */           /**      * @access public          * @var string - description       */     var $myPublicAttribute1;                       /** private attributes      */           /**      * @access private          * @var int - description      */          var $myPrivateAttribute1;                                /**      * CLASS METHODS      */          /** public methods      */          /**      * Function myMethod1      * @access public      * @param int - ...      * @param string - ...      * @return string      * @desc ...           */     function myMethod1 ($myParam1, $myParam2) {     } // end of function myMethod1                       /** protected methods      */          /**      * Function myMethod2      * @access protected      * @param int - ...      * @return int      * @desc ...           */     function myMethod2 ($myParam1) {     } // end of function myMethod2        } // end of class myClass ?>

Program architecture

Planned enhancements

• Design of a HTML interface to input the LMU data to be parsed
• Generation of class codes in another language than PHP (C, java, ...)
• Customization properties (what to comment, colors for the UML diagram, etc.)
• Customization of the expected syntax in the .lmu file :)

Examples - version 1.0

$ myClass { + myAttr: string } $ myClass1: myClass { # myAttr1: int - myAttr2 } $ myClass2: myClass { +@ myMethod1(myParam1: string, myParam2) -@ myMethod2(): string } $ myClass3 { + myAttr: string #@ myMethod3() } $ myClass4 { - myAttr4 -@ myMethod4() } $ myClass5 { - myAttr5: array } & { myClass3 (- myClass2 #0..* #0..1 ~isMadeOf } & { myClass3 - myClass3 #0..* #0..1 ~uses } & { myClass2 )- myClass4 #0..* #0..1 ~has }