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