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         /// Reloads the LyX file
 190         bool reload();
 191
 192         /// Fill in the ErrorList with the TeXErrors
 193         void bufferErrors(TeXErrors const &, ErrorList &) const;
 194
 195         /// Just a wrapper for writeLaTeXSource, first creating the ofstream.
 196         bool makeLaTeXFile(support::FileName const & filename,
 197                            std::string const & original_path,
 198                            OutputParams const &,
 199                            bool output_preamble = true,
 200                            bool output_body = true) const;
 201         /** Export the buffer to LaTeX.
 202             If \p os is a file stream, and params().inputenc is "auto" or
 203             "default", and the buffer contains text in different languages
 204             with more than one encoding, then this method will change the
 205             encoding associated to \p os. Therefore you must not call this
 206             method with a string stream if the output is supposed to go to a
 207             file. \code
 208             ofdocstream ofs;
 209             ofs.open("test.tex");
 210             writeLaTeXSource(ofs, ...);
 211             ofs.close();
 212             \endcode is NOT equivalent to \code
 213             odocstringstream oss;
 214             writeLaTeXSource(oss, ...);
 215             ofdocstream ofs;
 216             ofs.open("test.tex");
 217             ofs << oss.str();
 218             ofs.close();
 219             \endcode
 220          */
 221         void writeLaTeXSource(odocstream & os,
 222                            std::string const & original_path,
 223                            OutputParams const &,
 224                            bool output_preamble = true,
 225                            bool output_body = true) const;
 226         ///
 227         void makeDocBookFile(support::FileName const & filename,
 228                              OutputParams const & runparams_in,
 229                              bool only_body = false) const;
 230         ///
 231         void writeDocBookSource(odocstream & os, std::string const & filename,
 232                              OutputParams const & runparams_in,
 233                              bool only_body = false) const;
 234         ///
 235         void makeLyXHTMLFile(support::FileName const & filename,
 236                              OutputParams const & runparams_in,
 237                              bool only_body = false) const;
 238         ///
 239         void writeLyXHTMLSource(odocstream & os,
 240                              OutputParams const & runparams_in,
 241                              bool only_body = false) const;
 242         /// returns the main language for the buffer (document)
 243         Language const * language() const;
 244         /// get l10n translated to the buffers language
 245         docstring const B_(std::string const & l10n) const;
 246
 247         ///
 248         int runChktex();
 249         /// return true if the main lyx file does not need saving
 250         bool isClean() const;
 251         ///
 252         bool isBakClean() const;
 253         ///
 254         bool isDepClean(std::string const & name) const;
 255
 256         /// whether or not disk file has been externally modified
 257         bool isExternallyModified(CheckMethod method) const;
 258
 259         /// save timestamp and checksum of the given file.
 260         void saveCheckSum(support::FileName const & file) const;
 261
 262         /// mark the main lyx file as not needing saving
 263         void markClean() const;
 264
 265         ///
 266         void markBakClean() const;
 267
 268         ///
 269         void markDepClean(std::string const & name);
 270
 271         ///
 272         void setUnnamed(bool flag = true);
 273
 274         /// Whether or not a filename has been assigned to this buffer
 275         bool isUnnamed() const;
 276
 277         /// Whether or not this buffer is internal.
 278         ///
 279         /// An internal buffer does not contain a real document, but some auxiliary text segment.
 280         /// It is not associated with a filename, it is never saved, thus it does not need to be
 281         /// automatically saved, nor it needs to trigger any "do you want to save ?" question.
 282         bool isInternal() const;
 283
 284         /// Mark this buffer as dirty.
 285         void markDirty();
 286
 287         /// Returns the buffer's filename. It is always an absolute path.
 288         support::FileName fileName() const;
 289
 290         /// Returns the buffer's filename. It is always an absolute path.
 291         std::string absFileName() const;
 292
 293         /// Returns the the path where the buffer lives.
 294         /// It is always an absolute path.
 295         std::string filePath() const;
 296
 297         /** A transformed version of the file name, adequate for LaTeX.
 298             \param no_path optional if \c true then the path is stripped.
 299         */
 300         std::string latexName(bool no_path = true) const;
 301
 302         /// Get the name and type of the log.
 303         std::string logName(LogType * type = 0) const;
 304
 305         /// Change name of buffer. Updates "read-only" flag.
 306         void setFileName(std::string const & newfile);
 307
 308         /// Set document's parent Buffer.
 309         void setParent(Buffer const *);
 310         Buffer const * parent() const;
 311
 312         // Collect all relative buffer
 313         std::vector<Buffer const *> allRelatives() const;
 314
 315         /** Get the document's master (or \c this if this is not a
 316             child document)
 317          */
 318         Buffer const * masterBuffer() const;
 319
 320         /// \return true if \p child is a child of this \c Buffer.
 321         bool isChild(Buffer * child) const;
 322
 323         /// return a vector with all children (and grandchildren)
 324         std::vector<Buffer *> getChildren(bool grand_children = true) const;
 325
 326         /// Add all children (and grandchildren) to supplied vector
 327         void getChildren(std::vector<Buffer *> & children, bool grand_children = true) const;
 328
 329         /// Is buffer read-only?
 330         bool isReadonly() const;
 331
 332         /// Set buffer read-only flag
 333         void setReadonly(bool flag = true);
 334
 335         /// returns \c true if the buffer contains a LaTeX document
 336         bool isLatex() const;
 337         /// returns \c true if the buffer contains a DocBook document
 338         bool isDocBook() const;
 339         /// returns \c true if the buffer contains a Wed document
 340         bool isLiterate() const;
 341
 342         /** Validate a buffer for LaTeX.
 343             This validates the buffer, and returns a struct for use by
 344             #makeLaTeX# and others. Its main use is to figure out what
 345             commands and packages need to be included in the LaTeX file.
 346             It (should) also check that the needed constructs are there
 347             (i.e. that the \refs points to coresponding \labels). It
 348             should perhaps inset "error" insets to help the user correct
 349             obvious mistakes.
 350         */
 351         void validate(LaTeXFeatures &) const;
 352
 353         /// Update the cache with all bibfiles in use (including bibfiles
 354         /// of loaded child documents).
 355         void updateBibfilesCache(UpdateScope scope = UpdateMaster) const;
 356         ///
 357         void invalidateBibinfoCache();
 358         /// Return the cache with all bibfiles in use (including bibfiles
 359         /// of loaded child documents).
 360         support::FileNameList const &
 361                 getBibfilesCache(UpdateScope scope = UpdateMaster) const;
 362         /// \return the bibliography information for this buffer's master,
 363         /// or just for it, if it isn't a child.
 364         BiblioInfo const & masterBibInfo() const;
 365         /// \return the bibliography information for this buffer ONLY.
 366         BiblioInfo const & localBibInfo() const;
 367         ///
 368         void getLabelList(std::vector<docstring> &) const;
 369
 370         ///
 371         void changeLanguage(Language const * from, Language const * to);
 372
 373         ///
 374         bool isMultiLingual() const;
 375
 376         ///
 377         BufferParams & params();
 378         BufferParams const & params() const;
 379
 380         /** The list of paragraphs.
 381             This is a linked list of paragraph, this list holds the
 382             whole contents of the document.
 383          */
 384         ParagraphList & paragraphs();
 385         ParagraphList const & paragraphs() const;
 386
 387         /// LyX version control object.
 388         LyXVC & lyxvc();
 389         LyXVC const & lyxvc() const;
 390
 391         /// Where to put temporary files.
 392         std::string const temppath() const;
 393
 394         /// Used when typesetting to place errorboxes.
 395         TexRow const & texrow() const;
 396         TexRow & texrow();
 397
 398         ///
 399         ParIterator par_iterator_begin();
 400         ///
 401         ParConstIterator par_iterator_begin() const;
 402         ///
 403         ParIterator par_iterator_end();
 404         ///
 405         ParConstIterator par_iterator_end() const;
 406
 407         // Position of the child buffer where it appears first in the master.
 408         DocIterator firstChildPosition(Buffer const * child);
 409
 410         /** \returns true only when the file is fully loaded.
 411          *  Used to prevent the premature generation of previews
 412          *  and by the citation inset.
 413          */
 414         bool isFullyLoaded() const;
 415         /// Set by buffer_funcs' newFile.
 416         void setFullyLoaded(bool);
 417
 418         /// Our main text (inside the top InsetText)
 419         Text & text() const;
 420
 421         /// Our top InsetText
 422         Inset & inset() const;
 423
 424         //
 425         // Macro handling
 426         //
 427         /// Collect macro definitions in paragraphs
 428         void updateMacros() const;
 429         /// Iterate through the whole buffer and try to resolve macros
 430         void updateMacroInstances() const;
 431
 432         /// List macro names of this buffer, the parent and the children
 433         void listMacroNames(MacroNameSet & macros) const;
 434         /// Collect macros of the parent and its children in front of this buffer.
 435         void listParentMacros(MacroSet & macros, LaTeXFeatures & features) const;
 436
 437         /// Return macro defined before pos (or in the master buffer)
 438         MacroData const * getMacro(docstring const & name, DocIterator const & pos, bool global = true) const;
 439         /// Return macro defined anywhere in the buffer (or in the master buffer)
 440         MacroData const * getMacro(docstring const & name, bool global = true) const;
 441         /// Return macro defined before the inclusion of the child
 442         MacroData const * getMacro(docstring const & name, Buffer const & child, bool global = true) const;
 443
 444         /// Collect user macro names at loading time
 445         typedef std::set<docstring> UserMacroSet;
 446         UserMacroSet usermacros;
 447
 448         /// Replace the inset contents for insets which InsetCode is equal
 449         /// to the passed \p inset_code.
 450         void changeRefsIfUnique(docstring const & from, docstring const & to,
 451                 InsetCode code);
 452
 453         /// get source code (latex/docbook) for some paragraphs, or all paragraphs
 454         /// including preamble
 455         void getSourceCode(odocstream & os, pit_type par_begin, pit_type par_end,
 456                 bool full_source) const;
 457
 458         /// Access to error list.
 459         /// This method is used only for GUI visualisation of Buffer related
 460         /// errors (like parsing or LateX compilation). This method is const
 461         /// because modifying the returned ErrorList does not touch the document
 462         /// contents.
 463         ErrorList & errorList(std::string const & type) const;
 464
 465         /// The Toc backend.
 466         /// This is useful only for screen visualisation of the Buffer. This
 467         /// method is const because modifying this backend does not touch
 468         /// the document contents.
 469         TocBackend & tocBackend() const;
 470
 471         ///
 472         Undo & undo();
 473
 474         /// This function is called when the buffer is changed.
 475         void changed(bool update_metrics) const;
 476         ///
 477         void setChild(DocIterator const & dit, Buffer * child);
 478         ///
 479         void updateTocItem(std::string const &, DocIterator const &) const;
 480         /// This function is called when the buffer structure is changed.
 481         void structureChanged() const;
 482         /// This function is called when some parsing error shows up.
 483         void errors(std::string const & err, bool from_master = false) const;
 484         /// This function is called when the buffer busy status change.
 485         void setBusy(bool on) const;
 486         /// This function is called when the buffer readonly status change.
 487         void setReadOnly(bool on) const;
 488         /// Update window titles of all users.
 489         void updateTitles() const;
 490         /// Reset autosave timers for all users.
 491         void resetAutosaveTimers() const;
 492         ///
 493         void message(docstring const & msg) const;
 494
 495         ///
 496         void setGuiDelegate(frontend::GuiBufferDelegate * gui);
 497         ///
 498         bool hasGuiDelegate() const;
 499
 500         ///
 501         void autoSave() const;
 502         ///
 503         void removeAutosaveFile() const;
 504         ///
 505         void moveAutosaveFile(support::FileName const & old) const;
 506         ///
 507         support::FileName getAutosaveFilename() const;
 508
 509         /// return the format of the buffer on a string
 510         std::string bufferFormat() const;
 511         /// return the default output format of the current backend
 512         std::string getDefaultOutputFormat() const;
 513
 514         ///
 515         bool doExport(std::string const & format, bool put_in_tempdir,
 516                 std::string & result_file) const;
 517         ///
 518         bool doExport(std::string const & format, bool put_in_tempdir) const;
 519         ///
 520         bool preview(std::string const & format) const;
 521         ///
 522         bool isExportable(std::string const & format) const;
 523         ///
 524         std::vector<Format const *> exportableFormats(bool only_viewable) const;
 525         ///
 526         bool isExportableFormat(std::string const & format) const;
 527
 528         ///
 529         typedef std::vector<std::pair<InsetRef *, ParIterator> > References;
 530         References & references(docstring const & label);
 531         References const & references(docstring const & label) const;
 532         void clearReferenceCache() const;
 533         void setInsetLabel(docstring const & label, InsetLabel const * il);
 534         InsetLabel const * insetLabel(docstring const & label) const;
 535
 536         /// return a list of all used branches (also in children)
 537         void getUsedBranches(std::list<docstring> &, bool const from_master = false) const;
 538
 539         /// sets the buffer_ member for every inset in this buffer.
 540         // FIXME This really shouldn't be needed, but at the moment it's not
 541         // clear how to do it just for the individual pieces we need.
 542         void setBuffersForInsets() const;
 543         /// Updates screen labels and some other information associated with
 544         /// insets and paragraphs. Actually, it's more like a general "recurse
 545         /// through the Buffer" routine, that visits all the insets and paragraphs.
 546         void updateLabels() const { updateLabels(UpdateMaster, false); }
 547         /// \param scope: whether to start with the master document or just
 548         /// do this one.
 549         /// \param output: whether we are preparing for output.
 550         void updateLabels(UpdateScope scope, bool output) const;
 551         ///
 552         void updateLabels(ParIterator & parit, bool output) const;
 553
 554         /// Spellcheck starting from \p from.
 555         /// \p from initial position, will then points to the next misspelled
 556         ///    word.
 557         /// \p to will points to the end of the next misspelled word.
 558         /// \p word_lang will contain the found misspelled word.
 559         /// \return progress if a new word was found.
 560         int spellCheck(DocIterator & from, DocIterator & to,
 561                 WordLangTuple & word_lang, docstring_list & suggestions) const;
 562
 563 private:
 564         /// search for macro in local (buffer) table or in children
 565         MacroData const * getBufferMacro(docstring const & name,
 566                                          DocIterator const & pos) const;
 567         /** Update macro table starting with position of it
 568             \param it in some text inset
 569         */
 570         void updateMacros(DocIterator & it,
 571                                      DocIterator & scope) const;
 572         ///
 573         void checkBibInfoCache() const;
 574         ///
 575         void setLabel(ParIterator & it) const;
 576         ///
 577         void collectRelatives(BufferSet & bufs) const;
 578
 579         ///
 580         bool readFileHelper(support::FileName const & s);
 581         ///
 582         std::vector<std::string> backends() const;
 583         /** Inserts a file into a document
 584             \return \c false if method fails.
 585         */
 586         ReadStatus readFile(Lexer &, support::FileName const & filename,
 587                             bool fromString = false);
 588
 589         /** If we have branches that use the file suffix
 590             feature, return the file name with suffix appended.
 591         */
 592         support::FileName exportFileName() const;
 593
 594         /// Use the Pimpl idiom to hide the internals.
 595         class Impl;
 596         /// The pointer never changes although *pimpl_'s contents may.
 597         Impl * const d;
 598         ///
 599         frontend::GuiBufferDelegate * gui_;
 600
 601         /// This function is called when the buffer structure is changed.
 602         Signal structureChanged_;
 603         /// This function is called when some parsing error shows up.
 604         //Signal errors(std::string const &) = 0;
 605         /// This function is called when some message shows up.
 606         //Signal message(docstring const &) = 0;
 607         /// This function is called when the buffer busy status change.
 608         //Signal setBusy(bool) = 0;
 609         /// Reset autosave timers for all users.
 610         Signal resetAutosaveTimers_;
 611 };
 612
 613
 614 } // namespace lyx
 615
 616 #endif