3 * \file CiteEnginesList.h
4 * This file is part of LyX, the document processor.
5 * Licence details can be found in the file COPYING.
8 * \author Jürgen Spitzmüller
10 * Full author contact details are available in file CREDITS.
13 #ifndef CITEENGINESLIST_H
14 #define CITEENGINESLIST_H
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.
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}
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.
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.
43 * Engines can also be "provided" or "excluded" by document classes, using
44 * the ProvidesEngine and ExcludesEngine tags.
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;
61 std::string const & getName() const { return name_; }
63 std::string const & getID() const { return id_; }
65 std::string const & getFilename() const { return filename_; }
67 std::vector<std::string> const & getEngineType() const { return engine_types_; }
69 std::string const & getDescription() const { return description_; }
71 std::vector<std::string> const & getPackageList() const
72 { return package_list_; }
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;
85 static bool areCompatible(std::string const & eng1, std::string const & eng2);
87 /// what appears in the ui
89 /// the engine's unique identifier
90 /// at present, this is the filename, without the extension
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.
107 mutable bool checked_;
109 mutable bool available_;
111 mutable std::vector<std::string> prerequisites_;
114 typedef std::vector<LyXCiteEngine> LyXCiteEnginesList;
117 * The CiteEnginesList represents the various LyXCiteEngine's that are available at
120 class CiteEnginesList {
124 /// reads the engines from a file generated by configure.py
127 LyXCiteEnginesList::const_iterator begin() const;
129 LyXCiteEnginesList::iterator begin();
131 LyXCiteEnginesList::const_iterator end() const;
133 LyXCiteEnginesList::iterator end();
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;
140 LyXCiteEngine * operator[](std::string const & str);
143 CiteEnginesList(CiteEnginesList const &);
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 &);
151 std::vector<LyXCiteEngine> englist_;
154 extern CiteEnginesList theCiteEnginesList;