src/Buffer.h

   1 // -*- C++ -*-
   2 /**
   3  * \file Buffer.h
   4  * This file is part of LyX, the document processor.
   5  * Licence details can be found in the file COPYING.
   6  *
   7  * \author Lars Gullik Bjønnes
   8  *
   9  * Full author contact details are available in file CREDITS.
  10  */
  11
  12 #ifndef BUFFER_H
  13 #define BUFFER_H
  14
  15 #include "insets/InsetCode.h"
  16
  17 #include "support/strfwd.h"
  18 #include "support/types.h"
  19 #include "support/SignalSlot.h"
  20
  21 #include <string>
  22 #include <vector>
  23
  24
  25 namespace lyx {
  26
  27 class BiblioInfo;
  28 class BufferParams;
  29 class BufferSet;
  30 class DocIterator;
  31 class ErrorItem;
  32 class ErrorList;
  33 class FuncRequest;
  34 class Inset;
  35 class InsetRef;
  36 class InsetLabel;
  37 class Font;
  38 class Format;
  39 class Lexer;
  40 class LyXRC;
  41 class Text;
  42 class LyXVC;
  43 class LaTeXFeatures;
  44 class Language;
  45 class MacroData;
  46 class MacroNameSet;
  47 class MacroSet;
  48 class OutputParams;
  49 class Paragraph;
  50 class ParConstIterator;
  51 class ParIterator;
  52 class ParagraphList;
  53 class TeXErrors;
  54 class TexRow;
  55 class TocBackend;
  56 class Undo;
  57
  58 namespace frontend {
  59 class GuiBufferDelegate;
  60 class WorkAreaManager;
  61 }
  62
  63 namespace support {
  64 class FileName;
  65 class FileNameList;
  66 }
  67
  68 /** The buffer object.
  69  * This is the buffer object. It contains all the informations about
  70  * a document loaded into LyX.
  71  * The buffer object owns the Text (wrapped in an InsetText), which
  72  * contains the individual paragraphs of the document.
  73  *
  74  *
  75  * I am not sure if the class is complete or
  76  * minimal, probably not.
  77  * \author Lars Gullik Bjønnes
  78  */
  79 class Buffer {
  80 public:
  81         /// What type of log will \c getLogName() return?
  82         enum LogType {
  83                 latexlog, ///< LaTeX log
  84                 buildlog  ///< Literate build log
  85         };
  86
  87         /// Result of \c readFile()
  88         enum ReadStatus {
  89                 failure, ///< The file could not be read
  90                 success, ///< The file could not be read
  91                 wrongversion ///< The version of the file does not match ours
  92         };
  93
  94
  95         /// Method to check if a file is externally modified, used by
  96         /// isExternallyModified()
  97         /**
  98          * timestamp is fast but inaccurate. For example, the granularity
  99          * of timestamp on a FAT filesystem is 2 second. Also, various operations
 100          * may touch the timestamp of a file even when its content is unchanged.
 101          *
 102          * checksum is accurate but slow, which can be a problem when it is
 103          * frequently used, or used for a large file on a slow (network) file
 104          * system.
 105          *
 106          * FIXME: replace this method with support/FileMonitor.
 107          */
 108         enum CheckMethod {
 109                 checksum_method,  ///< Use file checksum
 110                 timestamp_method, ///< Use timestamp, and checksum if timestamp has changed
 111         };
 112
 113         /// Constructor
 114         explicit Buffer(std::string const & file, bool b = false);
 115
 116         /// Destructor
 117         ~Buffer();
 118
 119         /** High-level interface to buffer functionality.
 120             This function parses a command string and executes it
 121         */
 122         bool dispatch(std::string const & command, bool * result = 0);
 123
 124         /// Maybe we know the function already by number...
 125         bool dispatch(FuncRequest const & func, bool * result = 0);
 126
 127         /// Load the autosaved file.
 128         void loadAutoSaveFile();
 129
 130         /// read a new document from a string
 131         bool readString(std::string const &);
 132         /// load a new file
 133         bool readFile(support::FileName const & filename);
 134
 135         /// read the header, returns number of unknown tokens
 136         int readHeader(Lexer & lex);
 137
 138         /** Reads a file without header.
 139             \param par if != 0 insert the file.
 140             \return \c true if file is not completely read.
 141         */
 142         bool readDocument(Lexer &);
 143
 144         ///
 145         void insertStringAsLines(ParagraphList & plist,
 146                 pit_type &, pos_type &,
 147                 Font const &, docstring const &, bool);
 148         ///
 149         DocIterator getParFromID(int id) const;
 150         /// do we have a paragraph with this id?
 151         bool hasParWithID(int id) const;
 152
 153         ///
 154         frontend::WorkAreaManager & workAreaManager() const;
 155
 156         /** Save file.
 157             Takes care of auto-save files and backup file if requested.
 158             Returns \c true if the save is successful, \c false otherwise.
 159         */
 160         bool save() const;
 161
 162         /// Write document to stream. Returns \c false if unsuccesful.
 163         bool write(std::ostream &) const;
 164         /// Write file. Returns \c false if unsuccesful.
 165         bool writeFile(support::FileName const &) const;
 166
 167         /// Loads LyX file \c filename into buffer, *  and \return success
 168         bool loadLyXFile(support::FileName const & s);
 169
 170         /// Fill in the ErrorList with the TeXErrors
 171         void bufferErrors(TeXErrors const &, ErrorList &) const;
 172
 173         /// Just a wrapper for writeLaTeXSource, first creating the ofstream.
 174         bool makeLaTeXFile(support::FileName const & filename,
 175                            std::string const & original_path,
 176                            OutputParams const &,
 177                            bool output_preamble = true,
 178                            bool output_body = true) const;
 179         /** Export the buffer to LaTeX.
 180             If \p os is a file stream, and params().inputenc is "auto" or
 181             "default", and the buffer contains text in different languages
 182             with more than one encoding, then this method will change the
 183             encoding associated to \p os. Therefore you must not call this
 184             method with a string stream if the output is supposed to go to a
 185             file. \code
 186             ofdocstream ofs;
 187             ofs.open("test.tex");
 188             writeLaTeXSource(ofs, ...);
 189             ofs.close();
 190             \endcode is NOT equivalent to \code
 191             odocstringstream oss;
 192             writeLaTeXSource(oss, ...);
 193             ofdocstream ofs;
 194             ofs.open("test.tex");
 195             ofs << oss.str();
 196             ofs.close();
 197             \endcode
 198          */
 199         void writeLaTeXSource(odocstream & os,
 200                            std::string const & original_path,
 201                            OutputParams const &,
 202                            bool output_preamble = true,
 203                            bool output_body = true) const;
 204         ///
 205         void makeDocBookFile(support::FileName const & filename,
 206                              OutputParams const & runparams_in,
 207                              bool only_body = false) const;
 208         ///
 209         void writeDocBookSource(odocstream & os, std::string const & filename,
 210                              OutputParams const & runparams_in,
 211                              bool only_body = false) const;
 212         /// returns the main language for the buffer (document)
 213         Language const * language() const;
 214         /// get l10n translated to the buffers language
 215         docstring const B_(std::string const & l10n) const;
 216
 217         ///
 218         int runChktex();
 219         /// return true if the main lyx file does not need saving
 220         bool isClean() const;
 221         ///
 222         bool isBakClean() const;
 223         ///
 224         bool isDepClean(std::string const & name) const;
 225
 226         /// whether or not disk file has been externally modified
 227         bool isExternallyModified(CheckMethod method) const;
 228
 229         /// save timestamp and checksum of the given file.
 230         void saveCheckSum(support::FileName const & file) const;
 231
 232         /// mark the main lyx file as not needing saving
 233         void markClean() const;
 234
 235         ///
 236         void markBakClean() const;
 237
 238         ///
 239         void markDepClean(std::string const & name);
 240
 241         ///
 242         void setUnnamed(bool flag = true);
 243
 244         ///
 245         bool isUnnamed() const;
 246
 247         /// Mark this buffer as dirty.
 248         void markDirty();
 249
 250         /// Returns the buffer's filename. It is always an absolute path.
 251         support::FileName fileName() const;
 252
 253         /// Returns the buffer's filename. It is always an absolute path.
 254         std::string absFileName() const;
 255
 256         /// Returns the the path where the buffer lives.
 257         /// It is always an absolute path.
 258         std::string filePath() const;
 259
 260         /** A transformed version of the file name, adequate for LaTeX.
 261             \param no_path optional if \c true then the path is stripped.
 262         */
 263         std::string latexName(bool no_path = true) const;
 264
 265         /// Get thee name and type of the log.
 266         std::string logName(LogType * type = 0) const;
 267
 268         /// Change name of buffer. Updates "read-only" flag.
 269         void setFileName(std::string const & newfile);
 270
 271         /// Set document's parent Buffer.
 272         void setParent(Buffer const *);
 273         Buffer const * parent() const;
 274
 275         // Collect all relative buffer
 276         std::vector<Buffer const *> allRelatives() const;
 277
 278         /** Get the document's master (or \c this if this is not a
 279             child document)
 280          */
 281         Buffer const * masterBuffer() const;
 282
 283         /// \return true if \p child is a child of this \c Buffer.
 284         bool isChild(Buffer * child) const;
 285
 286         /// return a vector with all children and grandchildren
 287         std::vector<Buffer *> getChildren() const;
 288
 289         /// Is buffer read-only?
 290         bool isReadonly() const;
 291
 292         /// Set buffer read-only flag
 293         void setReadonly(bool flag = true);
 294
 295         /// returns \c true if the buffer contains a LaTeX document
 296         bool isLatex() const;
 297         /// returns \c true if the buffer contains a DocBook document
 298         bool isDocBook() const;
 299         /// returns \c true if the buffer contains a Wed document
 300         bool isLiterate() const;
 301
 302         /** Validate a buffer for LaTeX.
 303             This validates the buffer, and returns a struct for use by
 304             #makeLaTeX# and others. Its main use is to figure out what
 305             commands and packages need to be included in the LaTeX file.
 306             It (should) also check that the needed constructs are there
 307             (i.e. that the \refs points to coresponding \labels). It
 308             should perhaps inset "error" insets to help the user correct
 309             obvious mistakes.
 310         */
 311         void validate(LaTeXFeatures &) const;
 312
 313         /// Update the cache with all bibfiles in use (including bibfiles
 314         /// of loaded child documents).
 315         void updateBibfilesCache() const;
 316         ///
 317         void invalidateBibinfoCache();
 318         /// Return the cache with all bibfiles in use (including bibfiles
 319         /// of loaded child documents).
 320         support::FileNameList const & getBibfilesCache() const;
 321         /// \return the bibliography information for this buffer's master,
 322         /// or just for it, if it isn't a child.
 323         BiblioInfo const & masterBibInfo() const;
 324         /// \return the bibliography information for this buffer ONLY.
 325         BiblioInfo const & localBibInfo() const;
 326         ///
 327         void getLabelList(std::vector<docstring> &) const;
 328
 329         ///
 330         void changeLanguage(Language const * from, Language const * to);
 331
 332         ///
 333         bool isMultiLingual() const;
 334
 335         ///
 336         BufferParams & params();
 337         BufferParams const & params() const;
 338
 339         /** The list of paragraphs.
 340             This is a linked list of paragraph, this list holds the
 341             whole contents of the document.
 342          */
 343         ParagraphList & paragraphs();
 344         ParagraphList const & paragraphs() const;
 345
 346         /// LyX version control object.
 347         LyXVC & lyxvc();
 348         LyXVC const & lyxvc() const;
 349
 350         /// Where to put temporary files.
 351         std::string const temppath() const;
 352
 353         /// Used when typesetting to place errorboxes.
 354         TexRow const & texrow() const;
 355         TexRow & texrow();
 356
 357         ///
 358         ParIterator par_iterator_begin();
 359         ///
 360         ParConstIterator par_iterator_begin() const;
 361         ///
 362         ParIterator par_iterator_end();
 363         ///
 364         ParConstIterator par_iterator_end() const;
 365
 366         // Position of the child buffer where it appears first in the master.
 367         DocIterator firstChildPosition(Buffer const * child);
 368
 369         /** \returns true only when the file is fully loaded.
 370          *  Used to prevent the premature generation of previews
 371          *  and by the citation inset.
 372          */
 373         bool isFullyLoaded() const;
 374         /// Set by buffer_funcs' newFile.
 375         void setFullyLoaded(bool);
 376
 377         /// Our main text (inside the top InsetText)
 378         Text & text() const;
 379
 380         /// Our top InsetText
 381         Inset & inset() const;
 382
 383         //
 384         // Macro handling
 385         //
 386         /// Collect macro definitions in paragraphs
 387         void updateMacros() const;
 388         /// Iterate through the whole buffer and try to resolve macros
 389         void updateMacroInstances() const;
 390
 391         /// List macro names of this buffer, the parent and the children
 392         void listMacroNames(MacroNameSet & macros) const;
 393         /// Collect macros of the parent and its children in front of this buffer.
 394         void listParentMacros(MacroSet & macros, LaTeXFeatures & features) const;
 395
 396         /// Return macro defined before pos (or in the master buffer)
 397         MacroData const * getMacro(docstring const & name, DocIterator const & pos, bool global = true) const;
 398         /// Return macro defined anywhere in the buffer (or in the master buffer)
 399         MacroData const * getMacro(docstring const & name, bool global = true) const;
 400         /// Return macro defined before the inclusion of the child
 401         MacroData const * getMacro(docstring const & name, Buffer const & child, bool global = true) const;
 402
 403         /// Replace the inset contents for insets which InsetCode is equal
 404         /// to the passed \p inset_code.
 405         void changeRefsIfUnique(docstring const & from, docstring const & to,
 406                 InsetCode code);
 407
 408         /// get source code (latex/docbook) for some paragraphs, or all paragraphs
 409         /// including preamble
 410         void getSourceCode(odocstream & os, pit_type par_begin, pit_type par_end,
 411                 bool full_source) const;
 412
 413         /// Access to error list.
 414         /// This method is used only for GUI visualisation of Buffer related
 415         /// errors (like parsing or LateX compilation). This method is const
 416         /// because modifying the returned ErrorList does not touch the document
 417         /// contents.
 418         ErrorList & errorList(std::string const & type) const;
 419
 420         /// The Toc backend.
 421         /// This is useful only for screen visualisation of the Buffer. This
 422         /// method is const because modifying this backend does not touch
 423         /// the document contents.
 424         TocBackend & tocBackend() const;
 425
 426         ///
 427         Undo & undo();
 428
 429         /// This function is called when the buffer is changed.
 430         void changed() const;
 431         ///
 432         void updateTocItem(std::string const &, DocIterator const &) const;
 433         /// This function is called when the buffer structure is changed.
 434         void structureChanged() const;
 435         /// This function is called when some parsing error shows up.
 436         void errors(std::string const & err) const;
 437         /// This function is called when the buffer busy status change.
 438         void setBusy(bool on) const;
 439         /// This function is called when the buffer readonly status change.
 440         void setReadOnly(bool on) const;
 441         /// Update window titles of all users.
 442         void updateTitles() const;
 443         /// Reset autosave timers for all users.
 444         void resetAutosaveTimers() const;
 445         ///
 446         void message(docstring const & msg) const;
 447
 448         ///
 449         void setGuiDelegate(frontend::GuiBufferDelegate * gui);
 450         ///
 451         bool hasGuiDelegate() const;
 452
 453         ///
 454         void autoSave() const;
 455
 456         /// return the format of the buffer on a string
 457         std::string bufferFormat() const;
 458
 459         ///
 460         bool doExport(std::string const & format, bool put_in_tempdir,
 461                 std::string & result_file) const;
 462         ///
 463         bool doExport(std::string const & format, bool put_in_tempdir) const;
 464         ///
 465         bool preview(std::string const & format) const;
 466         ///
 467         bool isExportable(std::string const & format) const;
 468         ///
 469         std::vector<Format const *> exportableFormats(bool only_viewable) const;
 470
 471         ///
 472         typedef std::vector<std::pair<InsetRef *, ParIterator> > References;
 473         References & references(docstring const & label);
 474         References const & references(docstring const & label) const;
 475         void clearReferenceCache() const;
 476         void setInsetLabel(docstring const & label, InsetLabel const * il);
 477         InsetLabel const * insetLabel(docstring const & label) const;
 478
 479         // FIXME: buf should should be const because updateLabels() modifies
 480         // the contents of the paragraphs.
 481         void updateLabels(bool childonly = false) const;
 482         ///
 483         void updateLabels(ParIterator & parit) const;
 484
 485 private:
 486         /// search for macro in local (buffer) table or in children
 487         MacroData const * getBufferMacro(docstring const & name,
 488                                          DocIterator const & pos) const;
 489         /** Update macro table starting with position of it
 490             \param it in some text inset
 491         */
 492         void updateMacros(DocIterator & it,
 493                                      DocIterator & scope) const;
 494
 495         ///
 496         void collectRelatives(BufferSet & bufs) const;
 497
 498         ///
 499         bool readFileHelper(support::FileName const & s);
 500         ///
 501         std::vector<std::string> backends() const;
 502         /** Inserts a file into a document
 503             \return \c false if method fails.
 504         */
 505         ReadStatus readFile(Lexer &, support::FileName const & filename,
 506                             bool fromString = false);
 507
 508         /// Use the Pimpl idiom to hide the internals.
 509         class Impl;
 510         /// The pointer never changes although *pimpl_'s contents may.
 511         Impl * const d;
 512
 513         frontend::GuiBufferDelegate * gui_;
 514
 515         /// This function is called when the buffer structure is changed.
 516         Signal structureChanged_;
 517         /// This function is called when some parsing error shows up.
 518         //Signal errors(std::string const &) = 0;
 519         /// This function is called when some message shows up.
 520         //Signal message(docstring const &) = 0;
 521         /// This function is called when the buffer busy status change.
 522         //Signal setBusy(bool) = 0;
 523         /// Reset autosave timers for all users.
 524         Signal resetAutosaveTimers_;
 525 };
 526
 527
 528 } // namespace lyx
 529
 530 #endif