ucommandparameters.pas

DelphiDoc is a program for automatic generation of documentation on a Delphi-Project. At the momen

{  JADD - Just Another DelphiDoc: Documentation from Delphi Source Code

Copyright (C) 2003-2008   Gerold Veith

This file is part of JADD - Just Another DelphiDoc.

DelphiDoc is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3 as
published by the Free Software Foundation.

DelphiDoc is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
}


unit UCommandParameters;

{Contains some types and functions to handle parameters of both programs (GUI
 and commandline version) of DelphiDoc. This includes also the definitions of
 the file types, that are to be associated with DelphiDoc, thus becoming
 parameters. Additional also two procedures to show the project page and the
 documentation are defined.
}

interface

uses SysUtils, Classes;


      //the default extension of files (in the ini format) defining what files
      //to parse and how
const DDPDefaultExtension = 'ddp';
      //the default extension of files of parsed data
      DDDDefaultExtension = 'ddd';
      //the default extension of files of diagram layouts
      DDDLDefaultExtension = 'dddl';
      //the default extension of files (in the ini format) defining what
      //log files of a GUI to read and what to write in the main index when
      //generating a help about them
      DDGHDefaultExtension = 'ddgh';
      //name of default ini file of the program
      DefaultINIFile = 'DelphiDoc.ini';


type





   { * * *  ***  * * *  ***   TParameterOptions   ***  * * *  ***  * * *  }

   //Will be thrown when there is an error in the parameters of the program.
   EParameterException = class(Exception)
   end;


   //the parameters of the program
   //~todo "--select=NUM" to re-select kept data?
   TParameter = (
                 //an error occurred while parsing the parameters
                 pError,
                 //output the simple help
                 pHelp,
                 //load a project file with the list of Pascal files to be
                 //parsed
                 pSourceProject,
                 //load or create a new project based on its executable file
                 pExecutable,
                 //load previously parsed data from a file
                 pLoadParsedData,
                 //keep the data and generate documentation again about it
//                   pReuseData,

                 //select the generator to generate the documentation
                 pGenerator,
                 //set the directory to generate the documentation to
                 pDocumentationPath,
                 //the the name of the file to generate the documentation into,
                 //same as ~[link pGenerationOption] with "FileName=Value", not
                 //all generators support this option, in that case it will be
                 //ignored
                 pDocumentationFileName,

                 //sets an option of a generator, the parameter consists of
                 //a "Name=Value" pair with "Name" being the name of the option
                 //to be set and "Value" its new value
                 pGenerationOption,
                 //sets the localized version of a text to be used in the
                 //documentation, the parameter consists of a "Name=Value" pair
                 //with "Name" being the name of the text to be localized and
                 //"Value" its new value
                 pLocalize,
                 //loads the localized versions of the texts to be used in the
                 //documentation from a file
                 pLoadLocalization,
                 //(re-)set the localized versions of the texts to be used in
                 //the documentation to the value of a language whose values
                 //are pre-defined in the program (currently only English and
                 //German)
                 pUseLanguage,
                 //adds a file with (additional) user documentation to the
                 //internal list so it can be included in the documentation
                 //being generated
                 pUserDocumentation,
                 //clears the list of files with (additional) user
                 //documentation so no user documentation in included unless
                 //new files are added afterwards
                 pClearUserDocumentation,
                 //changes a part of the filter for the messages of the
                 //generator when generating the documentation, only the not
                 //filtered messages are written in the command line version
                 pGeneratorFilter,
                 //clears the filter so all messages of the generator when
                 //generating the documentation will be written in the command
                 //line version, unless the filter is changed afterwards
                 pClearGeneratorFilter,
                 //sets the kind of messages and information to output in the
                 //command line version
                 pVerboseModes,
                 //sets the kind of messages and information not to output in
                 //the command line version
                 pNonVerboseModes,
                 //sets whether the progress while parsing or generating should
                 //be shown in the command line version
                 pShowProgress,
                 //sets that the progress while parsing or generating should
                 //not be shown in the command line version
                 pHideProgress,
                 //sets that the documentation should automatically be
                 //generated in the GUI version
//                   pAutomaticGeneration,

                 //adds a log file of a GUI to the internal list so
                 //documentation as a help on it can be generated
                 pGUILogFile,
                 //clears the list of logs files about GUIs so it can be filled
                 //anew
                 pClearGUILogFiles,
                 //loads a project file of documentation to be generated as a
                 //help on a GUI, this means the list of log files of GUIs and
                 //the content of the main index
                 pLoadGUIHelpProject,

                 //generates the documentation with the currently set values,
                 //in the command line version automatically implied as last
                 //parameter, the kind of the documentation can be selected
                 //with an optional parameter, if it is not specified the
                 //most recently used kind will be used (default is
                 //documentation about source code), if the generator does not
                 //support the selected kind the program will exit with an
                 //error message
                 pGenerate
                 );



(*
  {Will be called for each parsed parameter of the program.
  ~param Parameter  the kind of the parameter
  ~param SingleChar the single character used for the option, if the long
                    option has be used it will be #0
  ~param Value      the value of the parameter of the parameter, '' if none
                    specified
  ~param HasValue   whether a parameter has been specified for the option
  ~result whether the function should be called for the next parameter
  ~exception EParameterException when the parameter or its value is invalid }
  THandleParameterFunc = function (Parameter: TParameter;
                                   SingleChar: Char;
                                   const Value: String;
                                   HasValue: Boolean): Boolean of object;

*)



  {Parse command line parameters. This is an abstract base class, while it uses
   the type ~[link TParameter] and the constant array ~[link ParameterEntries]
   to extract parameters, it is not really specific to this program. It is
   extended by the sub-class ~[link UParametersToState.TJADDParameterOptions]
   to really parse and handle the parameters of this program and set its values
   to the ~[link UJADDState.TJADDState state object]. But that class is also
   abstract and is extended separatedly for the GUI and command line version of
   the program to do the actual parsing and generating, etc.. }
  TParameterOptions = class
  private
    //list of all parameters of the program
    FParameters: TStringList;
    //the short parameter characters currently being parsed
    FShortParameters: String;


  protected
    {Will be called for each parsed parameter of the program.
    ~param Parameter  the kind of the parameter
    ~param SingleChar the single character used for the option, if the long
                      option has be used it will be #0
    ~param Value      the value of the parameter of the parameter, '' if none
                      specified
    ~param HasValue   whether a parameter has been specified for the option
    ~result whether the function should be called for the next parameter or
            parsing them should be aborted
    ~exception EParameterException when the parameter or its value is invalid }
    function ParamFunc(Parameter: TParameter;SingleChar: Char;
                       const Value: String;
                       HasValue: Boolean): Boolean; virtual; abstract;

  public
    //Create the object to process the command line parameters.
    constructor Create;
    //Frees the object.
    destructor Destroy; override;


    //Shows a help text about the available program options.
    class procedure ShowParametersHelp(Error: String);


    //Handles all parameters by calling ~[link ParamFunc].
    function ReadParameters: Boolean;



    property Parameters: TStringList read FParameters;
  end;

















      //characters prefixing command line options
const OptionPrefixCharacters =
{$IFDEF LINUX}
                               ['-'];      //don't use '/' in unix!
{$ELSE}
                               ['/', '-']; //use '-' and also DOS' '/'
{$ENDIF}

type
  //options for the entries of the parameters
  TParameterEntryOption = (
                           //the parameter has a "parameter", a value
                           peoHasParameter,
                           //the parameter value is optional, it can only be
                           //optional when its longer version is used
                           peoParameterOptional,
                           //the parameter is only used for the long version,
                           //~[link peoParameterOptional] also has to be set
                           peoParameterOnlyForLongOption,
                           //the parameter consists of a Name=Value pair
                           peoParameterNameValue,
                           //the parameter is ignored in the command line
                           //version
                           peoNotAtCommandLineVersion,
                           //the parameter is ignored in the GUI version
                           peoNotInGUIVersion);

  //An entry for a possible parameter of this program.
  TParameterEntry = record
     //the possible short parameter characters for the option, may be empty ''
     //if only the long parameter is available, may also contain more than one
     //character if several are possible (mainly for the help, -h and -?)
     ShortChars: String;
     //the name of the long parameter for the option, may be empty '' if only
     //a short parameter is supported, but this should only be the case, when
     //there are more than one short options for one long option
     LongName: String;
     //options for the parameter
     Options: set of TParameterEntryOption;
   end;


      //Contains the definition of the parameters of this program.
const ParameterEntries: array[Succ(Low(TParameter))..
                              High(TParameter)] of TParameterEntry =
      (
//       pHelp,
       (ShortChars: 'h?'; LongName: 'help'; Options: []),
//       pSourceProject,
       (ShortChars: 'p'; LongName: 'sourceproject';
        Options: [peoHasParameter]),
//       pExecutable,
       (ShortChars: 'e'; LongName: 'executable'; Options: [peoHasParameter]),
//       pLoadParsedData,
       (ShortChars: 'P'; LongName: 'loadparseddata';
        Options: [peoHasParameter]),
////       pReuseData,
//       (ShortChars: 'k'; LongName: 'reusedata'; Options: []),

//       pGenerator,
       (ShortChars: 'g'; LongName: 'generator'; Options: [peoHasParameter]),
//       pDocumentationPath,
       (ShortChars: 'd'; LongName: 'docpath'; Options: [peoHasParameter]),
//       pDocumentationFileName,
       (ShortChars: ''; LongName: 'docfilename'; Options: [peoHasParameter]),
//       pGenerationOption,
       (ShortChars: 'o'; LongName: 'genoption';
        Options: [peoHasParameter, peoParameterNameValue]),
//       pLocalize,
       (ShortChars: 'l'; LongName: 'localize';
        Options: [peoHasParameter, peoParameterNameValue]),
//       pLoadLocalization,
       (ShortChars: 'L'; LongName: 'loadlocalization';
        Options: [peoHasParameter]),
//       pUseLanguage,
       (ShortChars: ''; LongName: 'uselanguage'; Options: [peoHasParameter]),
//       pUserDocumentation,
       (ShortChars: 'u'; LongName: 'userdoc'; Options: [peoHasParameter]),
//       pClearUserDocumentation,
       (ShortChars: 'U'; LongName: 'clearuserdocumentation'; Options: []),
//       pGeneratorFilter,
       (ShortChars: 'f'; LongName: 'messagefilter';
        Options: [peoHasParameter, peoNotInGUIVersion]),
//       pClearGeneratorFilter,
       (ShortChars: 'F'; LongName: 'clearmessagefilter';
        Options: [peoNotInGUIVersion]),
//       pVerboseModes,
       (ShortChars: 'v'; LongName: 'verbose';
        Options: [peoHasParameter, peoNotInGUIVersion]),
//       pNonVerboseModes,
       (ShortChars: 'V'; LongName: 'quiet';
        Options: [peoHasParameter, peoParameterOptional, peoNotInGUIVersion]),
//       pShowProgress,
       (ShortChars: 'r'; LongName: 'showprogress';
        Options: [peoHasParameter,
                  peoParameterOptional, peoParameterOnlyForLongOption,
                  peoNotInGUIVersion]),
//       pHideProgress,
       (ShortChars: 'R'; LongName: 'hideprogress';
        Options: [peoNotInGUIVersion]),
////       pAutomaticGeneration,
//       (ShortChars: '-a'; LongName: 'autogeneration';
//        Options: [peoNotAtCommandLine]),

//       pGUILogFile,
       (ShortChars: 'i'; LongName: 'guilogfile'; Options: [peoHasParameter]),
//       pClearGUILogFiles
       (ShortChars: 'I'; LongName: 'clearguilogfiles'; Options: []),
//       pLoadGUIHelpProject,
       (ShortChars: 'H'; LongName: 'guihelpproject';
        Options: [peoHasParameter]),

//       pGenerate,
       (ShortChars: 'A'; LongName: 'generate';
        Options: [peoHasParameter, peoParameterOptional,
                                   peoParameterOnlyForLongOption])
      );











{$IFNDEF LINUX}


type
  //the types of files used by this program