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