uoptions.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 UOptions;

{Contains types and functions to handle ~[em options]. These options are f.i.
 used in the generators of documentation. They are also used to edit texts of
 the generators to localize the documentation. }

interface

uses SysUtils, Classes, IniFiles;


type

  {The type of a value for an option. }
  TOptionType = (
                 //option is a (short-)string
                 otString,
                 //option is a boolean value
                 otBoolean,
                 //option is an integer number
                 otInteger,
                 //option is a real number
                 otReal,
                 //option is a value out of an enumeration
                 otEnumeration,
                 //option is a set of an enumeration (maximal 32 items)
                 otSet
                );



  //the type to express a set of an enumeration (at least 32 bits)
  TOptionSetType = Longword;

  {The value for an option as used by ~[link TOptionWrapper.Option]. }
  TOptionValue = record
    //a string describing the value of the option
    StrData: String;                 //(only valid if TOptionType is otString)
    case TOptionType of
      otBoolean:     (
                       //a boolean value
                       BoolData  :Boolean;          );
      otInteger:     (
                       //an integer number value
                       IntData   :Integer;          );
      otReal:        (
                       //an real (floating point) number value
                       RealData  :Double;           );
      otEnumeration: (
                       //the number of a value out of an enumeration
                       EnumData  :Integer;          );
      otSet:         (
                       //a set of an enumeration
                       SetData   :TOptionSetType;   );
    end;




  //additional options of the options
  TOptionOption = (
                   //the option can not be read, reading it will always return
                   ooNoRead,                //some kind of a default value
                   //the option can not be written (read-only)
                   ooNoWrite,
                   //if this the option is set, others options may change, too
                   ooChangesOtherOptions);

  //additional options of the options
  TOptionOptions = set of TOptionOption;

      //texts to show for attributes of options
const OptionOptionTexts: array[TOptionOption] of String =
                         ('No Read', 'No Write', 'Changes Options');

      //the value for ~[link TOptionDescription.HelpOptionIndex] to show the
      //help text of the option itself
      HelpOptionIndexShowThisTopic = 0;
      //the value for ~[link TOptionDescription.HelpOptionIndex] to show the
      //help text of the topic of the option
      HelpOptionIndexShowMainTopic = High(Cardinal);
      //the value for ~[link TOptionDescription.HelpOptionIndex] to indicate
      //that no help text is available
      HelpOptionIndexNoHelp = High(Cardinal) - 1;

type
  {Describes an option as returned by ~[link TOptionWrapper.Description]. }
  TOptionDescription = record
    //the name of the option (should be unique)
    //allowed characters: [' '..#255] - ['=', '.'];
    //                    ' ' not at the beginning or the end
    Name: String;
    //the category of the option (can f.i. be sorted/filtered by it);
    //allowed characters: [' '..#255] - ['='];
    //                   ' ' and '.' not at the beginning or the end;
    //                   '.' has a special meaning by separating subcategories;
    //                   ' ' also not before or after '.'
    Category: String;
    //a description of the option
    Description: String;

    //additional options of the option
    Options: TOptionOptions;

    //the index whose help text should be shown instead for this option,
    //~[link HelpOptionIndexShowThisTopic] = 0 means show these options help
    //text, any other value means show the help text of the option with
    //index - 1; recursive look-ups are not supported, has to be the final
    //option;
    //the special values ~[link HelpOptionIndexShowMainTopic] and
    //~[link HelpOptionIndexNoHelp] are also available
    HelpOptionIndex: Cardinal;

    //the type of the value of the option
    DataType: TOptionType;
    //the default-value for a the option
    DefaultValue: TOptionValue;


    case TOptionType of       //additional information for the option
      otString:      (
                       //maximum length of the string (0 = not given)
                       StrMaxLen: Integer;  );
      otBoolean:     (                      );
      otInteger:     (
                       //maximum value for this option
                       MinInt: Integer;
                       //minimum value for this option
                       MaxInt: Integer      );
      otReal:        (
                       //maximum value for this option
                       MinReal: Single;
                       //minimum value for this option
                       MaxReal: Single;     );
      otEnumeration: (
                       //list of the names of the enumeration;
                       //won't be freed by the caller (i.e. should be a
                       //constant)
                       EnumNames: TStrings; );
      otSet:         (
                       //list of the names of the enumeration;
                       //won't be freed by the caller (i.e. should be a
                       //constant)
                       SetNames: TStrings;  );
  end;







  {Although options should generally be set (and read) without raising any
   exceptions, in some cases there might really be a reason to notify the user
   of an invalid value. In this case an exception of this type should be used.
  }
  EInvalidOption = class(Exception)
  end;








//Gets a string representation of the value.
function ValueToString(const Value: TOptionValue;
                       const Description: TOptionDescription): String;

//Tries to get the value of an option from its string representation.
function StringToValue(const Str: String; var Value: TOptionValue;
                       const Description: TOptionDescription): Boolean;

//Tries to get a boolean value from its string representation.
function StringToBoolean(const Str: String; var Value: Boolean): Boolean;



//Extracts a set to a bit-masked number.
function SetToOption(const TheSet; SizeOfSet: Integer;
                     BaseIndex: Integer = 0): TOptionSetType;
//Assigns a bit-masked number to a set.
procedure OptionToSet(Value: TOptionSetType; var TheSet; SizeOfSet: Integer;
                      BaseIndex: Integer = 0);
//Checks whether the set uses short cuts.
function SetUsesShortCuts(const Description: TOptionDescription): Boolean;

//Clears the description structure.
procedure ClearDescription(var Description: TOptionDescription);














type



   { * * *  ***  * * *  ***   TOptionWrapper   ***  * * *  ***  * * *  }



  {Abstract base class defining an interface to access options to get and set
   them. Can be used to edit options of different classes by creating wrappers
   for them.
   ~[diagram /class /members /showfile=1 /layout=post /size=8 /margin=5
             TOptionWrapper.tree]}
  TOptionWrapper = class
  protected
    //if the options should be loaded by the class hierarchy this is the base
    //class; if it is nil, the options are loaded by their topics
    FBaseClass: TClass;


    //Returns the current class if the options are loaded in a hierarchy.
    function GetStartClass: TClass; virtual;


    {Gets the value of an option. Call ~[link Description] to get the type and
     the meaning of the option.
    ~param Index index of the option to get the value of
    ~result the value of the option }
    function GetOption(Index: Cardinal): TOptionValue; virtual; abstract;

    {Sets the value of an option. Call ~[link Description] to get the type and
     the meaning of the option.
    ~param Index index of the option to set the value
    ~param Value the new value of the option}
    procedure SetOption(Index: Cardinal; const Value: TOptionValue); virtual;
                                                                     abstract;
  public
    {Returns the number of available options.
    ~result the number of available options }
    function Count: Cardinal; virtual; abstract;

    {Gets a description of an option.
    ~param Index index of the option to get data of
    ~param Desc  out: the description of the option (name, type, default value,
                      etc.) }
    procedure Description(Index: Cardinal;
                          var Desc: TOptionDescription); virtual; abstract;


    //Gets the topic of the options. '' is the default and means no topic is
    //available.
    function DefaultTopic: String; virtual;

    //Gets the topic of an option. '' is the default and means no topics used.
    function Topic(Index: Cardinal): String; virtual;




    //Gets the index of an option by its name (and type).
    function GetOptionIndex(const Name: String; OptionType: TOptionType;
                            var Index: Cardinal): Boolean;
    //Sets option to the value. It is ignored if the option is unknown.
    function SetOptionByName(const Name, Value: String): Boolean;
    //Gets the value of an option.
    function GetOptionAsStringByName(const Name: String;
                                     var Value: String): Boolean;
    //Reads "Name=Value"-lines and sets the values.
    procedure LoadOptionList(Options: TStrings);
    //Reads the section of the actual class and sets the options.
    procedure LoadIniOptions(Options: TCustomIniFile);
    //Reads the section of the actual class and all ancestor classes and sets
    //the options.
    procedure LoadAllIniOptions(Options: TCustomIniFile); //virtual;




    property Option[Index: Cardinal]: TOptionValue read GetOption
                                                   write SetOption;
  end;






   { * * *  ***  * *  ***   TCollectionOptionWrapper   ***  * *  ***  * * *  }


  //a list of option wrappers, for instance for
  //~[link TCollectionOptionWrapper.Create]
  TOptionWrapperList = array of TOptionWrapper;


  {Allows editing of the options of several wrappers by wrapping them in just
   object. }
  TCollectionOptionWrapper = class(TOptionWrapper)
  private
    //the wrappers to wrap
    FWrappers: TOptionWrapperList;
    //summed up number of options of the wrappers
    FCountSums: array of Cardinal;

    //Returns the wrapper and the corrected index.
    function GetWrapper(var Index: Cardinal): TOptionWrapper;
  protected
    //Gets the value of an option.
    function GetOption(Index: Cardinal): TOptionValue; override;

    //Sets the value of an option.
    procedure SetOption(Index: Cardinal; const Value: TOptionValue); override;
  public
    //Creates the wrapper and save the references to the wrappers.
    constructor Create(const Wrappers: array of TOptionWrapper);


    //Returns the number of available options.
    function Count: Cardinal; override;

    //Gets a description of an option.
    procedure Description(Index: Cardinal;
                          var Desc: TOptionDescription); override;