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