src/CiteEnginesList.h

   1 // -*- C++ -*-
   2 /**
   3  * \file CiteEnginesList.h
   4  * This file is part of LyX, the document processor.
   5  * Licence details can be found in the file COPYING.
   6  *
   7  * \author Richard Heck
   8  * \author Jürgen Spitzmüller
   9  *
  10  * Full author contact details are available in file CREDITS.
  11  */
  12
  13 #ifndef CITEENGINESLIST_H
  14 #define CITEENGINESLIST_H
  15
  16 #include <string>
  17 #include <vector>
  18
  19 namespace lyx {
  20
  21 /**
  22  *  This class represents a particular LyX "cite engine", which defines the features
  23  * of a particular citation backend such as natbib or biblatex. In that sense, it is more like
  24  *  a LaTeX package, where a layout file corresponds to a LaTeX class.
  25  *
  26  *  In general, a given cite engine can be used with any document class. That said,
  27  *  one cite engine may `require' another, or it may `exclude' some other cite engine.
  28  *  The requires and excludes are given in comments within the cite engine file,
  29  *  which must begin roughly so:
  30  *  # \DeclareLyXCiteEngine[natbib.sty]{Natbib}
  31  *  # DescriptionBegin
  32  *  #   Loads the LaTeX package natbib, a citation engine. Natbib supports
  33  *  #   both author-year and numerical styles for citations, automatic sorting
  34  *  #   and merging of numerical citations, annotations, capitalization of the
  35  *  #   `van' part of author names, shortened and full author lists, and more.
  36  *  # DescriptionEnd
  37  *  # Excludes: basic | jurabib
  38  *  The description might be used in the gui to give information to the user. The
  39  *  Requires and Excludes lines are read by the configuration script
  40  *  and written to a file citeengines.lst in the user configuration directory.
  41  *  That file is then read on startup to populate the CiteEnginesList, below.
  42  *
  43  *  Engines can also be "provided" or "excluded" by document classes, using
  44  *  the ProvidesEngine and ExcludesEngine tags.
  45  */
  46
  47 class LyXCiteEngine {
  48 public:
  49         ///
  50         LyXCiteEngine(std::string const & name, std::string const & id,
  51                       std::vector<std::string> const & enginetypes,
  52                       std::string const & description,
  53                       std::vector<std::string> const & packagelist,
  54                       std::vector<std::string> const & requires,
  55                       std::vector<std::string> const & excludes);
  56         /// whether the required packages are available
  57         bool isAvailable() const;
  58         /// the missing prerequisites, if any
  59         std::vector<std::string> prerequisites() const;
  60         ///
  61         std::string const & getName() const { return name_; }
  62         ///
  63         std::string const & getID() const { return id_; }
  64         ///
  65         std::string const & getFilename() const { return filename_; }
  66         ///
  67         std::vector<std::string> const & getEngineType() const { return engine_types_; }
  68         ///
  69         std::string const & getDescription() const { return description_; }
  70         ///
  71         std::vector<std::string> const & getPackageList() const
  72                 { return package_list_; }
  73         ///
  74         std::vector<std::string> const & getRequiredEngines() const
  75                 { return required_engines_; }
  76         /// Engines this one excludes: the list should be treated disjunctively
  77         std::vector<std::string> const & getExcludedEngines() const
  78                 { return excluded_engines_; }
  79         /// \return true if the engine is compatible with this one, i.e.,
  80         /// it does not exclude us and we do not exclude it.
  81         /// this will also return true if cename is unknown and we do not
  82         /// exclude it, since in that case we cannot check its exclusions.
  83         bool isCompatible(std::string const & cename) const;
  84         ///
  85         static bool areCompatible(std::string const & eng1, std::string const & eng2);
  86 private:
  87         /// what appears in the ui
  88         std::string name_;
  89         /// the engine's unique identifier
  90         /// at present, this is the filename, without the extension
  91         std::string id_;
  92         /// the filename
  93         std::string filename_;
  94         /// the engine type(s)
  95         std::vector<std::string> engine_types_;
  96         /// a short description for use in the ui
  97         std::string description_;
  98         /// the LaTeX packages on which this depends, if any
  99         std::vector<std::string> package_list_;
 100         /// Engines this one requires: at least one
 101         std::vector<std::string> required_engines_;
 102         /// Engines this one excludes: none of these
 103         std::vector<std::string> excluded_engines_;
 104         // these are mutable because they are used to cache the results
 105         // or an otherwise const operation.
 106         ///
 107         mutable bool checked_;
 108         ///
 109         mutable bool available_;
 110         ///
 111         mutable std::vector<std::string> prerequisites_;
 112 };
 113
 114 typedef std::vector<LyXCiteEngine> LyXCiteEnginesList;
 115
 116 /**
 117  *  The CiteEnginesList represents the various LyXCiteEngine's that are available at
 118  *  present.
 119  */
 120 class CiteEnginesList {
 121 public:
 122         ///
 123         CiteEnginesList() {}
 124         /// reads the engines from a file generated by configure.py
 125         bool read();
 126         ///
 127         LyXCiteEnginesList::const_iterator begin() const;
 128         ///
 129         LyXCiteEnginesList::iterator begin();
 130         ///
 131         LyXCiteEnginesList::const_iterator end() const;
 132         ///
 133         LyXCiteEnginesList::iterator end();
 134         ///
 135         bool empty() const { return englist_.empty(); }
 136         /// Returns a pointer to the LyXCiteEngine with filename str.
 137         /// Returns a null pointer if no such engine is found.
 138         LyXCiteEngine const * operator[](std::string const & str) const;
 139         ///
 140         LyXCiteEngine * operator[](std::string const & str);
 141         private:
 142         /// noncopyable
 143         CiteEnginesList(CiteEnginesList const &);
 144         ///
 145         void operator=(CiteEnginesList const &);
 146         /// add an engine to the list
 147         void addCiteEngine(std::string const &, std::string const &,
 148                 std::vector<std::string> const &, std::string const &, std::vector<std::string> const &,
 149                 std::vector<std::string> const &, std::vector<std::string> const &);
 150         ///
 151         std::vector<LyXCiteEngine> englist_;
 152 };
 153
 154 extern CiteEnginesList theCiteEnginesList;
 155 }
 156 #endif