config_file.hh

Go to the documentation of this file.
00001 /* vim: set sw=4 sts=4 et foldmethod=syntax : */
00002 
00003 /*
00004  * Copyright (c) 2006, 2007, 2008 Ciaran McCreesh
00005  *
00006  * This file is part of the Paludis package manager. Paludis is free software;
00007  * you can redistribute it and/or modify it under the terms of the GNU General
00008  * Public License version 2, as published by the Free Software Foundation.
00009  *
00010  * Paludis is distributed in the hope that it will be useful, but WITHOUT ANY
00011  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
00012  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
00013  * details.
00014  *
00015  * You should have received a copy of the GNU General Public License along with
00016  * this program; if not, write to the Free Software Foundation, Inc., 59 Temple
00017  * Place, Suite 330, Boston, MA  02111-1307  USA
00018  */
00019 
00020 #ifndef PALUDIS_GUARD_PALUDIS_CONFIG_FILE_HH
00021 #define PALUDIS_GUARD_PALUDIS_CONFIG_FILE_HH 1
00022 
00023 #include <paludis/util/config_file-fwd.hh>
00024 #include <paludis/util/map-fwd.hh>
00025 #include <paludis/util/exception.hh>
00026 #include <paludis/util/instantiation_policy.hh>
00027 #include <paludis/util/private_implementation_pattern.hh>
00028 #include <paludis/util/options-fwd.hh>
00029 #include <paludis/util/wrapped_forward_iterator-fwd.hh>
00030 #include <paludis/util/fs_entry-fwd.hh>
00031 
00032 #include <iosfwd>
00033 #include <string>
00034 #include <tr1/memory>
00035 #include <tr1/functional>
00036 
00037 /** \file
00038  * Declarations for the ConfigFile classes.
00039  *
00040  * \ingroup g_config_file
00041  *
00042  * \section Examples
00043  *
00044  * - None at this time.
00045  */
00046 
00047 namespace paludis
00048 {
00049     /**
00050      * Raised if an error is encountered parsing a configuration file.
00051      *
00052      * \ingroup g_config_file
00053      * \ingroup g_exceptions
00054      * \nosubgrouping
00055      */
00056     class PALUDIS_VISIBLE ConfigFileError :
00057         public ConfigurationError
00058     {
00059         public:
00060             ///\name Basic operations
00061             ///\{
00062 
00063             /**
00064              * Constructor, where the filename is known.
00065              *
00066              * \param filename The filename in which the error occurred. May be a blank string, if
00067              *   the filename is not necessarily known.
00068              * \param message A description of the error.
00069              */
00070             ConfigFileError(const std::string & filename, const std::string & message) throw ();
00071 
00072             /**
00073              * Constructor, where the filename is not known.
00074              *
00075              * \param message A description of the error.
00076              */
00077             ConfigFileError(const std::string & message) throw ();
00078 
00079             ///\}
00080     };
00081 
00082     /**
00083      * Base class for configuration files.
00084      *
00085      * Data is read in from a ConfigFile::Source instance, which can be created from
00086      * an FSEntry, a std::istream or a string.
00087      *
00088      * \see KeyValueConfigFile
00089      * \see LineConfigFile
00090      *
00091      * \ingroup g_config_file
00092      * \nosubgrouping
00093      */
00094     class PALUDIS_VISIBLE ConfigFile
00095     {
00096         public:
00097             /**
00098              * A source (for example, a file or a string) usable by ConfigFile.
00099              *
00100              * \see ConfigFile
00101              * \ingroup g_config_file
00102              * \nosubgrouping
00103              */
00104             class PALUDIS_VISIBLE Source :
00105                 private PrivateImplementationPattern<Source>
00106             {
00107                 public:
00108                     ///\name Basic operations
00109                     ///\{
00110 
00111                     Source(const FSEntry &);
00112                     Source(const std::string &);
00113                     Source(std::istream &);
00114 
00115                     Source(const Source &);
00116                     const Source & operator= (const Source &);
00117 
00118                     ~Source();
00119 
00120                     ///\}
00121 
00122                     /**
00123                      * Our text, for use by ConfigFile.
00124                      */
00125                     const std::string & text() const PALUDIS_ATTRIBUTE((warn_unused_result));
00126 
00127                     /**
00128                      * Our filename (may be empty), for use by ConfigFile.
00129                      */
00130                     const std::string & filename() const PALUDIS_ATTRIBUTE((warn_unused_result));
00131             };
00132 
00133             ///\name Basic operations
00134             ///\{
00135 
00136             virtual ~ConfigFile() = 0;
00137 
00138             ///\}
00139     };
00140 
00141     /**
00142      * Options for a LineConfigFile.
00143      *
00144      * \see LineConfigFileOption
00145      * \see LineConfigFile
00146      * \ingroup g_config_file
00147      */
00148     typedef Options<LineConfigFileOption> LineConfigFileOptions;
00149 
00150     /**
00151      * A line-based configuration file.
00152      *
00153      * Various syntax options are available, and are controlled by LineConfigFileOptions:
00154      *
00155      * - Unless lcfo_disallow_continuations, lines ending in a backslash are continuations
00156      * - Unless lcfo_disallow_comments, lines starting with a \# are comments
00157      * - Unless lcfo_preserve_whitespace, leading and trailing whitespace is stripped
00158      * - Unless lcfo_no_skip_blank_lines, blank lines are skipped.
00159      *
00160      * \ingroup g_config_file
00161      * \nosubgrouping
00162      */
00163     class PALUDIS_VISIBLE LineConfigFile :
00164         public ConfigFile,
00165         private PrivateImplementationPattern<LineConfigFile>
00166     {
00167         public:
00168             ///\name Basic operations
00169             ///\{
00170 
00171             LineConfigFile(const Source &, const LineConfigFileOptions &);
00172 
00173             ~LineConfigFile();
00174 
00175             ///\}
00176 
00177             ///\name Iterate over our lines
00178             ///\{
00179 
00180             struct ConstIteratorTag;
00181             typedef WrappedForwardIterator<ConstIteratorTag, const std::string> ConstIterator;
00182 
00183             ConstIterator begin() const PALUDIS_ATTRIBUTE((warn_unused_result));
00184             ConstIterator end() const PALUDIS_ATTRIBUTE((warn_unused_result));
00185 
00186             ///\}
00187     };
00188 
00189     /**
00190      * Options for a KeyValueConfigFileOptions.
00191      *
00192      * \see KeyValueConfigFileOption
00193      * \see KeyValueConfigFile
00194      */
00195     typedef Options<KeyValueConfigFileOption> KeyValueConfigFileOptions;
00196 
00197     /**
00198      * A key=value configuration file.
00199      *
00200      * Various syntax options are available, and are controlled by KeyValueConfigFileOptions:
00201      *
00202      * - Unless kvcfo_disallow_continuations, line continuations via backslashes are allowed.
00203      * - Unless kvcfo_disallow_comments, comments start with a \#.
00204      * - Unless kvcfo_disallow_space_around_equals, the equals sign can have surrounding whitespace.
00205      * - Unless kvcfo_disallow_space_inside_unquoted_values, foo = bar baz is legal.
00206      * - Unless kvcfo_disallow_single_quoted_strings, single quoted strings are legal.
00207      * - Unless kvcfo_disallow_double_quoted_strings, double quoted strings are legal.
00208      * - Unless kvcfo_disallow_unquoted_values, unquoted values are legal.
00209      * - Unless kvcfo_disallow_variables, variables using $foo and ${foo} are expanded.
00210      * - Unless kvcfo_disallow_source, source path is legal.
00211      * - Unless kvcfo_preserve_whitespace, leading and trailing whitespace on values is stripped.
00212      *
00213      * \ingroup g_config_file
00214      * \nosubgrouping
00215      */
00216     class PALUDIS_VISIBLE KeyValueConfigFile :
00217         public ConfigFile,
00218         private PrivateImplementationPattern<KeyValueConfigFile>
00219     {
00220         public:
00221             typedef std::tr1::function<std::string (const KeyValueConfigFile &, const std::string &)> DefaultFunction;
00222             typedef std::tr1::function<std::string (const KeyValueConfigFile &,
00223                     const std::string & var, const std::string & old_value, const std::string & new_value)> TransformationFunction;
00224 
00225             static std::string no_defaults(const KeyValueConfigFile &, const std::string &);
00226             static std::string no_transformation(const KeyValueConfigFile &, const std::string &, const std::string &, const std::string &);
00227 
00228             ///\name Basic operations
00229             ///\{
00230 
00231             /**
00232              * Constructor.
00233              *
00234              * \since 0.28
00235              */
00236             KeyValueConfigFile(
00237                     const Source &,
00238                     const KeyValueConfigFileOptions &,
00239                     const DefaultFunction &,
00240                     const TransformationFunction &
00241                     );
00242 
00243             ~KeyValueConfigFile();
00244 
00245             ///\}
00246 
00247             ///\name Iterate over our keys
00248             ///\{
00249 
00250             struct ConstIteratorTag;
00251             typedef WrappedForwardIterator<ConstIteratorTag,
00252                     const std::pair<const std::string, std::string> > ConstIterator;
00253             ConstIterator begin() const PALUDIS_ATTRIBUTE((warn_unused_result));
00254             ConstIterator end() const PALUDIS_ATTRIBUTE((warn_unused_result));
00255 
00256             ///\}
00257 
00258             /**
00259              * Fetch the value for a particular key.
00260              */
00261             std::string get(const std::string &) const PALUDIS_ATTRIBUTE((warn_unused_result));
00262 
00263             const KeyValueConfigFileOptions & options() const PALUDIS_ATTRIBUTE((warn_unused_result));
00264             const DefaultFunction & default_function() const PALUDIS_ATTRIBUTE((warn_unused_result));
00265             const TransformationFunction & transformation_function() const PALUDIS_ATTRIBUTE((warn_unused_result));
00266     };
00267 
00268 #ifdef PALUDIS_HAVE_EXTERN_TEMPLATE
00269     extern template class PrivateImplementationPattern<ConfigFile::Source>;
00270     extern template class PrivateImplementationPattern<LineConfigFile>;
00271     extern template class PrivateImplementationPattern<KeyValueConfigFile>;
00272 #endif
00273 
00274 }
00275 
00276 #endif

Generated on Mon Sep 21 10:36:08 2009 for paludis by  doxygen 1.5.4