DEVELOPMENT NOTES ----------------- This file contains random development notes. You should have read or at least skimmed it when you intend to customize, port, extend or translate this Application. NB: This document is now out of date, but it is a starting point and should be updated soon. CONTENTS -------- - ALWAYS RTFM - ADDING FUNCTIONALITY - WHY I DID IT THIS WAY - HOW IT WORKS (probably the interesting bit) - HOW TO ADD A HANDLER (even more interesting) - BENCHMARKS - BUGS ALWAYS RTFM BEFORE YOU DO ANYTHING. ----------------------------------- The POD is there for all perl modules - use it. If its not in the POD or if the POD is unclear, check the mailing list archives, if you still have no luck ask on the mailing list and hopefully I or somebody who knows better will be able to help. ADDING FUNCTIONALITY -------------------- Did I say RTFM, well again, read the documentation before you do anything. Functionality should be added through extending the current model and/or adding abstraction, maintaining or increasing the componentisation. I have spent a long time ironing out the hacks and bugs and won't put any back in in a hurry. If you wish to add functionality then email me a patch, the source and an explaination, if you wish to request a feature also email me. I can be reached at ajt@droogs.org . WHY I DID IT THIS WAY --------------------- I did it this way as a cruel joke on other programmers. No not really, even if it does seem that way. I started doing this project as an afternoons hack but I got interested in it, and I wanted to make it more elegant, in the end it became a full on project and I had to rewrite from scratch using OO, modules and plenty of abstraction. There is still a long way to go in this regard to make it totally componentised so that it can be integrated into a perl script and handle different types of input and output. HOW IT WORKS ------------ - The autodial.pl script gets a list of files to analyse from the user, uses File::Find or globbing to generate a list based on the langauge. - The autodial.pl script creates an empty Diagram object (using Diagram.pm) - The autodial.pl script loads the appropriate handler and passes it the filehandle of each file. - The handler parses each file in the list and creates a new Class object for each class or in perl package/script, or in c program/library. (using DiagramClass.pm), this Class is added to the Diagram object which holds all the objects and provides methods for accessing them. - As the file is parsed the handler populates the Class object from any subs, attributes, and relationships it finds. These are added to the Class and in the case of superclasses and packages the Diagram object. (using DiagramSuperclass, DiagramComponent, etc) - After the files have been parsed redundancies are removed and the positions for each diagram entity (ie class, relationship, superclass) are calculated. - The template is created and passed the Diagram object, the output file and the template file. - The template then makes calls to the Diagram Object it was passed, which provide lists of diagram entities which it uses to populate the template. HOW TO ADD A HANDLER -------------------- To add a handler to AutoDia - open Autodia.pm and add the language name and handler name into the %handlers hash in the getHandlers function. - add patterns and regex's for finding appropriate files if not already present in the getPattern function. - examples and documentation in Autodia.pm - create a class that inherits from Handler or HandlerLanguage. You will need to have a method called _parse that is passed the filehandle and does all the diagram and class population. you can add any subroutines you need to make _parse work. - the Handler superclass does most of the work along with the diagram classes. see the HandlerPerl parser for example code as it is heavily commented and clearly laid out. - Examples and documentation in HandlerPerl.pm and Handler.pm BENCHMARKS --------- Some quick and dirty tests to give you an idea of how long stuff could take. On a K2 450, running Linux 2.2.12. AutoDial analysed itself 10 times, Autodial pre 0.05 contains about 2000 lines of code in 7 files. AutoDia 0.05 and higher contains about 2500 to 3000 lines in 11 files version 1.0: (intel Celeron Mendocino 466mhz running linux 2.4.6) 10 loops of autodial.pl took 9 wallclock secs ( 8.87 usr + 0.02 sys = 8.89 CPU) @ 1.12/s (n=10) version 0.09: 10 loops of autodial.pl took 10 wallclock secs ( 9.20 usr + 0.24 sys = 9.44 CPU) version 0.08: 10 loops of autodial.pl took 10 wallclock secs ( 9.00 usr + 0.21 sys = 9.21 CPU) version 0.06: 10 loops of autodial.pl took 10 wallclock secs ( 9.32 usr + 0.23 sys = 9.55 CPU) version 0.05: 10 loops of autodial.pl took 11 wallclock secs ( 9.68 usr + 0.27 sys = 9.95 CPU) version 0.04: 10 loops of autodial.pl took 9 wallclock secs ( 8.36 usr + 0.08 sys = 8.44 CPU) version 0.02: 10 loops of autodial.pl took 8 wallclock secs ( 7.09 usr + 0.13 sys = 7.22 CPU) version 0.01: 10 loops of autodial.pl took 6 wallclock secs ( 5.94 usr + 0.09 sys = 6.03 CPU ) BUGS ---- Please submit bug reports to the mailing list or ajt@droogs.org , see http://droogs.org/autodia/ for details