src/TextClass.h

   1 // -*- C++ -*-
   2 /**
   3  * \file TextClass.h
   4  * This file is part of LyX, the document processor.
   5  * Licence details can be found in the file COPYING.
   6  *
   7  * Full author contact details are available in file CREDITS.
   8  */
   9
  10 #ifndef TEXTCLASS_H
  11 #define TEXTCLASS_H
  12
  13 #include "ColorCode.h"
  14 #include "Counters.h"
  15 #include "FloatList.h"
  16 #include "FontInfo.h"
  17 #include "Layout.h"
  18 #include "LayoutEnums.h"
  19
  20 #include "insets/InsetLayout.h"
  21
  22 #include "support/docstring.h"
  23 #include "support/types.h"
  24
  25 #include <boost/noncopyable.hpp>
  26
  27 #include <map>
  28 #include <set>
  29 #include <vector>
  30 #include <list>
  31
  32 namespace lyx {
  33
  34 namespace support { class FileName; }
  35
  36 class Counters;
  37 class FloatList;
  38 class Layout;
  39 class LayoutFile;
  40 class Lexer;
  41
  42 /// Based upon ideas in boost::noncopyable, inheriting from this
  43 /// class effectively makes the copy constructor protected but the
  44 /// assignment constructor private.
  45 class ProtectCopy
  46 {
  47 protected:
  48         ProtectCopy() {}
  49         ~ProtectCopy() {}
  50         ProtectCopy(const ProtectCopy &) {};
  51 private:
  52         const ProtectCopy & operator=(const ProtectCopy &);
  53 };
  54
  55
  56 /// A TextClass represents a collection of layout information: At the
  57 /// moment, this includes Layout's and InsetLayout's.
  58 ///
  59 /// There are two major subclasses of TextClass: LayoutFile and
  60 /// DocumentClass. These subclasses are what are actually used in LyX.
  61 /// Simple TextClass objects are not directly constructed in the main
  62 /// LyX code---the constructor is protected. (That said, in tex2lyx
  63 /// there are what amount to simple TextClass objects.)
  64 ///
  65 /// A LayoutFile (see LayoutFile.{h,cpp}) represents a *.layout file.
  66 /// These are generally static objects---though they can be reloaded
  67 /// from disk via LFUN_LAYOUT_RELOAD, so one should not assume that
  68 /// they will never change.
  69 ///
  70 /// A DocumentClass (see below) represents the layout information that
  71 /// is associated with a given Buffer. These are static, in the sense
  72 /// that they will not themselves change, but which DocumentClass is
  73 /// associated with a Buffer can change, as modules are loaded and
  74 /// unloaded, for example.
  75 ///
  76 class TextClass : protected ProtectCopy {
  77 public:
  78         ///
  79         virtual ~TextClass() {};
  80         ///////////////////////////////////////////////////////////////////
  81         // typedefs
  82         ///////////////////////////////////////////////////////////////////
  83         /// The individual paragraph layouts comprising the document class
  84         // NOTE Do NOT try to make this a container of Layout pointers, e.g.,
  85         // std::vector<Layout *>. This will lead to problems. The reason is
  86         // that DocumentClass objects are generally created by copying a
  87         // LayoutFile, which serves as a base for the DocumentClass. If the
  88         // LayoutList is a container of pointers, then every DocumentClass
  89         // that derives from a given LayoutFile (e.g., article) will SHARE
  90         // a basic set of layouts. So if one Buffer were to modify a layout
  91         // (say, Standard), that would modify that layout for EVERY Buffer
  92         // that was based upon the same DocumentClass. (Of course, if you
  93         // really, REALLY want to make LayoutList a vector<Layout *>, then
  94         // you can implement custom assignment and copy constructors.)
  95         //
  96         // NOTE: Layout pointers are directly assigned to paragraphs so a
  97         // container that does not invalidate these pointers after insertion
  98         // is needed.
  99         typedef std::list<Layout> LayoutList;
 100         /// The inset layouts available to this class
 101         typedef std::map<docstring, InsetLayout> InsetLayouts;
 102         ///
 103         typedef LayoutList::const_iterator const_iterator;
 104
 105         ///////////////////////////////////////////////////////////////////
 106         // Iterators
 107         ///////////////////////////////////////////////////////////////////
 108         ///
 109         const_iterator begin() const { return layoutlist_.begin(); }
 110         ///
 111         const_iterator end() const { return layoutlist_.end(); }
 112
 113
 114         ///////////////////////////////////////////////////////////////////
 115         // Layout Info
 116         ///////////////////////////////////////////////////////////////////
 117         ///
 118         Layout const & defaultLayout() const;
 119         ///
 120         docstring const & defaultLayoutName() const;
 121         ///
 122         bool isDefaultLayout(Layout const &) const;
 123         ///
 124         bool isPlainLayout(Layout const &) const;
 125         /// returns a special layout for use when we don't really want one,
 126         /// e.g., in table cells
 127         Layout const & emptyLayout() const
 128                         { return operator[](emptylayout_); };
 129         /// the name of the empty layout
 130         docstring const & emptyLayoutName() const
 131                         { return emptylayout_; }
 132         /// Enumerate the paragraph styles.
 133         size_t layoutCount() const { return layoutlist_.size(); }
 134         ///
 135         bool hasLayout(docstring const & name) const;
 136         ///
 137         Layout const & operator[](docstring const & vname) const;
 138
 139         ///////////////////////////////////////////////////////////////////
 140         // reading routines
 141         ///////////////////////////////////////////////////////////////////
 142         /// Enum used with TextClass::read
 143         enum ReadType {
 144                 BASECLASS, //>This is a base class, i.e., top-level layout file
 145                 MERGE, //>This is a file included in a layout file
 146                 MODULE, //>This is a layout module
 147                 VALIDATION //>We're just validating
 148         };
 149         /// return values for read()
 150         enum ReturnValues {
 151                 OK,
 152                 ERROR,
 153                 FORMAT_MISMATCH
 154         };
 155
 156         /// Performs the read of the layout file.
 157         /// \return true on success.
 158         bool read(support::FileName const & filename, ReadType rt = BASECLASS);
 159         ///
 160         bool read(std::string const & str, ReadType rt = BASECLASS);
 161         ///
 162         ReturnValues read(Lexer & lex, ReadType rt = BASECLASS);
 163         /// validates the layout information passed in str
 164         static bool validate(std::string const & str);
 165
 166         ///////////////////////////////////////////////////////////////////
 167         // loading
 168         ///////////////////////////////////////////////////////////////////
 169         /// Sees to it the textclass structure has been loaded
 170         /// This function will search for $classname.layout in default directories
 171         /// and an optional path, but if path points to a file, it will be loaded
 172         /// directly.
 173         bool load(std::string const & path = std::string()) const;
 174         /// Has this layout file been loaded yet?
 175         /// Overridden by DocumentClass
 176         virtual bool loaded() const { return loaded_; }
 177
 178         ///////////////////////////////////////////////////////////////////
 179         // accessors
 180         ///////////////////////////////////////////////////////////////////
 181         ///
 182         std::string const & name() const { return name_; };
 183         ///
 184         std::string const & description() const {       return description_; };
 185         ///
 186         std::string const & latexname() const { return latexname_; }
 187 protected:
 188         /// Protect construction
 189         TextClass();
 190         ///
 191         Layout & operator[](docstring const & vname);
 192         /// Create an empty layout for this textclass.
 193         /** \param unknown Set to true if this layout is a default layout used to
 194          * represent an unknown layout
 195          */
 196         Layout createEmptyLayout(docstring const & name, bool unknown = false) const;
 197
 198         ///////////////////////////////////////////////////////////////////
 199         // non-const iterators
 200         ///////////////////////////////////////////////////////////////////
 201         ///
 202         typedef LayoutList::iterator iterator;
 203         ///
 204         iterator begin() { return layoutlist_.begin(); }
 205         ///
 206         iterator end() { return layoutlist_.end(); }
 207
 208         ///////////////////////////////////////////////////////////////////
 209         // members
 210         ///////////////////////////////////////////////////////////////////
 211         /// Paragraph styles used in this layout
 212         /// This variable is mutable because unknown layouts can be added
 213         /// to const textclass.
 214         mutable LayoutList layoutlist_;
 215         /// Layout file name
 216         std::string name_;
 217         /// document class name
 218         std::string latexname_;
 219         /// document class description
 220         std::string description_;
 221         /// available types of float, eg. figure, algorithm.
 222         mutable FloatList floatlist_;
 223         /// Types of counters, eg. sections, eqns, figures, avail. in document class.
 224         mutable Counters counters_;
 225         /// Has this layout file been loaded yet?
 226         mutable bool loaded_;
 227         /// Is the TeX class available?
 228         bool texClassAvail_;
 229         ///
 230         std::string opt_fontsize_;
 231         ///
 232         std::string opt_pagestyle_;
 233         /// Specific class options
 234         std::string options_;
 235         ///
 236         std::string pagestyle_;
 237         ///
 238         std::string class_header_;
 239         ///
 240         docstring defaultlayout_;
 241         /// name of empty layout
 242         static const docstring emptylayout_;
 243         /// preamble text to support layout styles
 244         docstring preamble_;
 245         /// latex packages loaded by document class.
 246         std::set<std::string> provides_;
 247         /// latex packages requested by document class.
 248         std::set<std::string> requires_;
 249         /// modules wanted by document class
 250         std::set<std::string> usemod_;
 251         ///
 252         unsigned int columns_;
 253         ///
 254         PageSides sides_;
 255         /// header depth to have numbering
 256         int secnumdepth_;
 257         /// header depth to appear in table of contents
 258         int tocdepth_;
 259         /// Can be LaTeX, DocBook, etc.
 260         OutputType outputType_;
 261         /** Base font. The paragraph and layout fonts are resolved against
 262             this font. This has to be fully instantiated. Attributes
 263             FONT_INHERIT, FONT_IGNORE, and FONT_TOGGLE are
 264             extremely illegal.
 265         */
 266         FontInfo defaultfont_;
 267         /// Text that dictates how wide the left margin is on the screen
 268         docstring leftmargin_;
 269         /// Text that dictates how wide the right margin is on the screen
 270         docstring rightmargin_;
 271         /// The type of command used to produce a title
 272         TitleLatexType titletype_;
 273         /// The name of the title command
 274         std::string titlename_;
 275         /// Input layouts available to this layout
 276         InsetLayouts insetlayoutlist_;
 277         /// The minimal TocLevel of sectioning layouts
 278         int min_toclevel_;
 279         /// The maximal TocLevel of sectioning layouts
 280         int max_toclevel_;
 281 private:
 282         ///////////////////////////////////////////////////////////////////
 283         // helper routines for reading layout files
 284         ///////////////////////////////////////////////////////////////////
 285         ///
 286         bool deleteLayout(docstring const &);
 287         ///
 288         bool convertLayoutFormat(support::FileName const &, ReadType);
 289         /// \return true for success.
 290         bool readStyle(Lexer &, Layout &) const;
 291         ///
 292         void readOutputType(Lexer &);
 293         ///
 294         void readTitleType(Lexer &);
 295         ///
 296         void readMaxCounter(Lexer &);
 297         ///
 298         void readClassOptions(Lexer &);
 299         ///
 300         void readCharStyle(Lexer &, std::string const &);
 301         ///
 302         void readFloat(Lexer &);
 303         ///
 304         void readCounter(Lexer &);
 305 };
 306
 307
 308 /// A DocumentClass represents the layout information associated with a
 309 /// Buffer. It is based upon a LayoutFile, but may be modified by loading
 310 /// various Modules.
 311 ///
 312 /// In that regard, DocumentClass objects are "dynamic". But this is really
 313 /// an illusion, since DocumentClass objects are not (currently) changed
 314 /// when, say, a new Module is loaded. Rather, the old DocumentClass is
 315 /// discarded---actually, it's kept around in case something on the cut
 316 /// stack needs it---and a new one is created from scratch.
 317 ///
 318 /// In the main LyX code, DocumentClass objects are created only by
 319 /// DocumentClassBundle, for which see below.
 320 ///
 321 class DocumentClass : public TextClass, boost::noncopyable {
 322 public:
 323         ///
 324         virtual ~DocumentClass() {}
 325
 326         ///////////////////////////////////////////////////////////////////
 327         // Layout Info
 328         ///////////////////////////////////////////////////////////////////
 329         /// \return true if there is a Layout with latexname lay
 330         bool hasLaTeXLayout(std::string const & lay) const;
 331         /// A DocumentClass nevers count as loaded, since it is dynamic
 332         virtual bool loaded() { return false; }
 333         /// Inset layouts of this doc class
 334         InsetLayouts const & insetLayouts() const { return insetlayoutlist_; };
 335         /// \return the layout object of an inset given by name. If the name
 336         /// is not found as such, the part after the ':' is stripped off, and
 337         /// searched again. In this way, an error fallback can be provided:
 338         /// An erroneous 'CharStyle:badname' (e.g., after a documentclass switch)
 339         /// will invoke the layout object defined by name = 'CharStyle'.
 340         /// If that doesn't work either, an empty object returns (shouldn't
 341         /// happen).  -- Idea JMarc, comment MV
 342         InsetLayout const & insetLayout(docstring const & name) const;
 343         /// an empty inset layout for use as a default
 344         static InsetLayout const & emptyInsetLayout() { return empty_insetlayout_; }
 345         /// add an empty layout \c name if it does not exist in layoutlist_
 346         void addLayoutIfNeeded(docstring const & name) const;
 347
 348         ///////////////////////////////////////////////////////////////////
 349         // accessors
 350         ///////////////////////////////////////////////////////////////////
 351         /// the list of floats defined in the document class
 352         FloatList const & floats() const { return floatlist_; }
 353         ///
 354         Counters & counters() const { return counters_; }
 355         ///
 356         std::string const & opt_fontsize() const { return opt_fontsize_; }
 357         ///
 358         std::string const & opt_pagestyle() const { return opt_pagestyle_; }
 359         ///
 360         std::string const & options() const { return options_; }
 361         ///
 362         std::string const & class_header() const { return class_header_; }
 363         ///
 364         std::string const & pagestyle() const { return pagestyle_; }
 365         ///
 366         docstring const & preamble() const { return preamble_; }
 367         /// is this feature already provided by the class?
 368         bool provides(std::string const & p) const;
 369         /// features required by the class?
 370         std::set<std::string> const & requires() const { return requires_; }
 371         ///
 372         unsigned int columns() const { return columns_; }
 373         ///
 374         PageSides sides() const { return sides_; }
 375         ///
 376         int secnumdepth() const { return secnumdepth_; }
 377         ///
 378         int tocdepth() const { return tocdepth_; }
 379         ///
 380         FontInfo const & defaultfont() const { return defaultfont_; }
 381         /// Text that dictates how wide the left margin is on the screen
 382         docstring const & leftmargin() const { return leftmargin_; }
 383         /// Text that dictates how wide the right margin is on the screen
 384         docstring const & rightmargin() const { return rightmargin_; }
 385         /// The type of command used to produce a title
 386         TitleLatexType titletype() const { return titletype_; };
 387         /// The name of the title command
 388         std::string const & titlename() const { return titlename_; };
 389         ///
 390         int size() const { return layoutlist_.size(); }
 391         /// The minimal TocLevel of sectioning layouts
 392         int min_toclevel() const { return min_toclevel_; }
 393         /// The maximal TocLevel of sectioning layouts
 394         int max_toclevel() const { return max_toclevel_; }
 395         /// returns true if the class has a ToC structure
 396         bool hasTocLevels() const;
 397         /// Can be LaTeX, DocBook, etc.
 398         OutputType outputType() const { return outputType_; }
 399 protected:
 400         /// Constructs a DocumentClass based upon a LayoutFile.
 401         DocumentClass(LayoutFile const & tc);
 402         /// Needed in tex2lyx
 403         DocumentClass() {}
 404 private:
 405         /// The only class that can create a DocumentClass is
 406         /// DocumentClassBundle, which calls the protected constructor.
 407         friend class DocumentClassBundle;
 408         ///
 409         static InsetLayout empty_insetlayout_;
 410 };
 411
 412
 413 /// DocumentClassBundle is a container for DocumentClass objects, so that
 414 /// they stay in memory for use by Insets, CutAndPaste, and the like, even
 415 /// when their associated Buffers are destroyed.
 416 /// FIXME Some sort of garbage collection or reference counting wouldn't
 417 /// be a bad idea here. It might be enough to check when a Buffer is closed
 418 /// (or makeDocumentClass is called) whether the old DocumentClass is in use
 419 /// anywhere.
 420 ///
 421 /// This is a singleton class. Its sole instance is accessed via
 422 /// DocumentClassBundle::get().
 423 class DocumentClassBundle : boost::noncopyable {
 424 public:
 425         /// \return Pointer to a new class equal to baseClass
 426         DocumentClass & newClass(LayoutFile const & baseClass);
 427         /// \return The sole instance of this class.
 428         static DocumentClassBundle & get();
 429 private:
 430         /// control instantiation
 431         DocumentClassBundle() {}
 432         /// clean up
 433         ~DocumentClassBundle();
 434         ///
 435         std::vector<DocumentClass *> documentClasses_;
 436 };
 437
 438
 439 /// convert page sides option to text 1 or 2
 440 std::ostream & operator<<(std::ostream & os, PageSides p);
 441
 442
 443 } // namespace lyx
 444
 445 #endif