/src/yolk-config_file_parser.ads

  1-------------------------------------------------------------------------------
  2--                                                                           --
  3--                   Copyright (C) 2010-, Thomas Løcke                   --
  4--                                                                           --
  5--  This library is free software;  you can redistribute it and/or modify    --
  6--  it under terms of the  GNU General Public License  as published by the   --
  7--  Free Software  Foundation;  either version 3,  or (at your  option) any  --
  8--  later version. This library is distributed in the hope that it will be   --
  9--  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of  --
 10--  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                     --
 11--                                                                           --
 12--  As a special exception under Section 7 of GPL version 3, you are         --
 13--  granted additional permissions described in the GCC Runtime Library      --
 14--  Exception, version 3.1, as published by the Free Software Foundation.    --
 15--                                                                           --
 16--  You should have received a copy of the GNU General Public License and    --
 17--  a copy of the GCC Runtime Library Exception along with this program;     --
 18--  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
 19--  <http://www.gnu.org/licenses/>.                                          --
 20--                                                                           --
 21-------------------------------------------------------------------------------
 22
 23--  This package provides simple access to configuration files.
 24--  The format is:
 25--       KEY VALUE
 26--
 27--  Comments are prefixed with a # or a --
 28--
 29--  # This is a comment
 30--  -- This is also a comment
 31--
 32--  Blank lines and comments are ignored and so is pre-/postfixed whitespace,
 33--  so this:
 34--
 35--  [lots of whitespace]KEY[lots of whitespace]VALUE[lots of whitespace]
 36--
 37--  is treated as:
 38--
 39--  KEY VALUE
 40--
 41--  Values containing whitespace, eg. full sentences and similar, are returned
 42--  as is. It is not necessary to quote such values, so this:
 43--
 44--    KEY some value with whitespace
 45--
 46--  is perfectly valid, and will, when calling Get (KEY), return:
 47--
 48--    some value with whitespace
 49--
 50--  If VALUE is True or False (case-insensitive), then the KEY can be returned
 51--  as both a String or as a Boolean.
 52--
 53--  Trying to convert VALUE to an incompatible type, e.g. a Float to a Boolean
 54--  will raise the Conversion_Error exception. It will NOT return some dummy
 55--  value.
 56--
 57--  To clear a default value, simply add the key to the configuration file,
 58--  with no value set. Conversely, you must omit (or comment) keys for which
 59--  you want to use the default value.
 60
 61with Ada.Strings.Unbounded;
 62
 63generic
 64   use Ada.Strings.Unbounded;
 65
 66   type Key_Type is (<>);
 67   type Defaults_Array_Type is array (Key_Type) of Unbounded_String;
 68   Defaults    : in Defaults_Array_Type;
 69   Config_File : in String;
 70
 71package Yolk.Config_File_Parser is
 72
 73   Unknown_Key             : exception;
 74   --  Is raised when an unknown KEY has been found in the config file.
 75   Cannot_Open_Config_File : exception;
 76   --  Is raised when the given config file cannot be opened, eg. due to bad
 77   --  path.
 78   Conversion_Error        : exception;
 79   --  Is raised when a value cannot be converted to a specific type.
 80
 81   function Get
 82     (Key : in Key_Type)
 83      return Boolean;
 84
 85   function Get
 86     (Key : in Key_Type)
 87      return Duration;
 88
 89   function Get
 90     (Key : in Key_Type)
 91      return Float;
 92
 93   function Get
 94     (Key : in Key_Type)
 95      return Integer;
 96
 97   function Get
 98     (Key : in Key_Type)
 99      return String;
100
101   function Get
102     (Key : in Key_Type)
103      return Unbounded_String;
104   --  Get the VALUE for Key and convert it to target type.
105   --  Exceptions:
106   --    Conversion_Error
107
108   function Has_Non_Empty_Value
109     (Key : in Key_Type)
110      return Boolean;
111   --  Return True if Key is _not_ a Null_Unbounded_String.
112
113   procedure Load_File
114     (Config_File : in String);
115   --  Load the config file Config_File. This can be done over and over as many
116   --  times as necessary. The values from the latest file overwrites the
117   --  previous values.
118   --  Exceptions:
119   --    Cannot_Open_Ini_File
120   --    Unknown_Key
121
122end Yolk.Config_File_Parser;