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         ///
 114         enum UpdateScope {
 115                 UpdateMaster,
 116                 UpdateChildOnly
 117         };
 118
 119         /// Constructor
 120         explicit Buffer(std::string const & file, bool b = false);
 121
 122         /// Destructor
 123         ~Buffer();
 124
 125         /** High-level interface to buffer functionality.
 126             This function parses a command string and executes it
 127         */
 128         bool dispatch(std::string const & command, bool * result = 0);
 129
 130         /// Maybe we know the function already by number...
 131         bool dispatch(FuncRequest const & func, bool * result = 0);
 132
 133         /// read a new document from a string
 134         bool readString(std::string const &);
 135         /// load a new file
 136         bool readFile(support::FileName const & filename);
 137
 138         /// read the header, returns number of unknown tokens
 139         int readHeader(Lexer & lex);
 140
 141         /** Reads a file without header.
 142             \param par if != 0 insert the file.
 143             \return \c true if file is not completely read.
 144         */
 145         bool readDocument(Lexer &);
 146
 147         ///
 148         void insertStringAsLines(ParagraphList & plist,
 149                 pit_type &, pos_type &,
 150                 Font const &, docstring const &, bool);
 151         ///
 152         DocIterator getParFromID(int id) const;
 153         /// do we have a paragraph with this id?
 154         bool hasParWithID(int id) const;
 155
 156         ///
 157         frontend::WorkAreaManager & workAreaManager() const;
 158
 159         /** Save file.
 160             Takes care of auto-save files and backup file if requested.
 161             Returns \c true if the save is successful, \c false otherwise.
 162         */
 163         bool save() const;
 164
 165         /// Write document to stream. Returns \c false if unsuccesful.
 166         bool write(std::ostream &) const;
 167         /// Write file. Returns \c false if unsuccesful.
 168         bool writeFile(support::FileName const &) const;
 169
 170         /// Loads LyX file \c filename into buffer, *  and \return success
 171         bool loadLyXFile(support::FileName const & s);
 172
 173         /// Fill in the ErrorList with the TeXErrors
 174         void bufferErrors(TeXErrors const &, ErrorList &) const;
 175
 176         /// Just a wrapper for writeLaTeXSource, first creating the ofstream.
 177         bool makeLaTeXFile(support::FileName const & filename,
 178                            std::string const & original_path,
 179                            OutputParams const &,
 180                            bool output_preamble = true,
 181                            bool output_body = true) const;
 182         /** Export the buffer to LaTeX.
 183             If \p os is a file stream, and params().inputenc is "auto" or
 184             "default", and the buffer contains text in different languages
 185             with more than one encoding, then this method will change the
 186             encoding associated to \p os. Therefore you must not call this
 187             method with a string stream if the output is supposed to go to a
 188             file. \code
 189             ofdocstream ofs;
 190             ofs.open("test.tex");
 191             writeLaTeXSource(ofs, ...);
 192             ofs.close();
 193             \endcode is NOT equivalent to \code
 194             odocstringstream oss;
 195             writeLaTeXSource(oss, ...);
 196             ofdocstream ofs;
 197             ofs.open("test.tex");
 198             ofs << oss.str();
 199             ofs.close();
 200             \endcode
 201          */
 202         void writeLaTeXSource(odocstream & os,
 203                            std::string const & original_path,
 204                            OutputParams const &,
 205                            bool output_preamble = true,
 206                            bool output_body = true) const;
 207         ///
 208         void makeDocBookFile(support::FileName const & filename,
 209                              OutputParams const & runparams_in,
 210                              bool only_body = false) const;
 211         ///
 212         void writeDocBookSource(odocstream & os, std::string const & filename,
 213                              OutputParams const & runparams_in,
 214                              bool only_body = false) const;
 215         /// returns the main language for the buffer (document)
 216         Language const * language() const;
 217         /// get l10n translated to the buffers language
 218         docstring const B_(std::string const & l10n) const;
 219
 220         ///
 221         int runChktex();
 222         /// return true if the main lyx file does not need saving
 223         bool isClean() const;
 224         ///
 225         bool isBakClean() const;
 226         ///
 227         bool isDepClean(std::string const & name) const;
 228
 229         /// whether or not disk file has been externally modified
 230         bool isExternallyModified(CheckMethod method) const;
 231
 232         /// save timestamp and checksum of the given file.
 233         void saveCheckSum(support::FileName const & file) const;
 234
 235         /// mark the main lyx file as not needing saving
 236         void markClean() const;
 237
 238         ///
 239         void markBakClean() const;
 240
 241         ///
 242         void markDepClean(std::string const & name);
 243
 244         ///
 245         void setUnnamed(bool flag = true);
 246
 247         ///
 248         bool isUnnamed() const;
 249
 250         /// Mark this buffer as dirty.
 251         void markDirty();
 252
 253         /// Returns the buffer's filename. It is always an absolute path.
 254         support::FileName fileName() const;
 255
 256         /// Returns the buffer's filename. It is always an absolute path.
 257         std::string absFileName() const;
 258
 259         /// Returns the the path where the buffer lives.
 260         /// It is always an absolute path.
 261         std::string filePath() const;
 262
 263         /** A transformed version of the file name, adequate for LaTeX.
 264             \param no_path optional if \c true then the path is stripped.
 265         */
 266         std::string latexName(bool no_path = true) const;
 267
 268         /// Get thee name and type of the log.
 269         std::string logName(LogType * type = 0) const;
 270
 271         /// Change name of buffer. Updates "read-only" flag.
 272         void setFileName(std::string const & newfile);
 273
 274         /// Set document's parent Buffer.
 275         void setParent(Buffer const *);
 276         Buffer const * parent() const;
 277
 278         // Collect all relative buffer
 279         std::vector<Buffer const *> allRelatives() const;
 280
 281         /** Get the document's master (or \c this if this is not a
 282             child document)
 283          */
 284         Buffer const * masterBuffer() const;
 285
 286         /// \return true if \p child is a child of this \c Buffer.
 287         bool isChild(Buffer * child) const;
 288
 289         /// return a vector with all children and grandchildren
 290         std::vector<Buffer *> getChildren() const;
 291
 292         /// Is buffer read-only?
 293         bool isReadonly() const;
 294
 295         /// Set buffer read-only flag
 296         void setReadonly(bool flag = true);
 297
 298         /// returns \c true if the buffer contains a LaTeX document
 299         bool isLatex() const;
 300         /// returns \c true if the buffer contains a DocBook document
 301         bool isDocBook() const;
 302         /// returns \c true if the buffer contains a Wed document
 303         bool isLiterate() const;
 304
 305         /** Validate a buffer for LaTeX.
 306             This validates the buffer, and returns a struct for use by
 307             #makeLaTeX# and others. Its main use is to figure out what
 308             commands and packages need to be included in the LaTeX file.
 309             It (should) also check that the needed constructs are there
 310             (i.e. that the \refs points to coresponding \labels). It
 311             should perhaps inset "error" insets to help the user correct
 312             obvious mistakes.
 313         */
 314         void validate(LaTeXFeatures &) const;
 315
 316         /// Update the cache with all bibfiles in use (including bibfiles
 317         /// of loaded child documents).
 318         void updateBibfilesCache(UpdateScope scope = UpdateMaster) const;
 319         ///
 320         void invalidateBibinfoCache();
 321         /// Return the cache with all bibfiles in use (including bibfiles
 322         /// of loaded child documents).
 323         support::FileNameList const &
 324                 getBibfilesCache(UpdateScope scope = UpdateMaster) const;
 325         /// \return the bibliography information for this buffer's master,
 326         /// or just for it, if it isn't a child.
 327         BiblioInfo const & masterBibInfo() const;
 328         /// \return the bibliography information for this buffer ONLY.
 329         BiblioInfo const & localBibInfo() const;
 330         ///
 331         void getLabelList(std::vector<docstring> &) const;
 332
 333         ///
 334         void changeLanguage(Language const * from, Language const * to);
 335
 336         ///
 337         bool isMultiLingual() const;
 338
 339         ///
 340         BufferParams & params();
 341         BufferParams const & params() const;
 342
 343         /** The list of paragraphs.
 344             This is a linked list of paragraph, this list holds the
 345             whole contents of the document.
 346          */
 347         ParagraphList & paragraphs();
 348         ParagraphList const & paragraphs() const;
 349
 350         /// LyX version control object.
 351         LyXVC & lyxvc();
 352         LyXVC const & lyxvc() const;
 353
 354         /// Where to put temporary files.
 355         std::string const temppath() const;
 356
 357         /// Used when typesetting to place errorboxes.
 358         TexRow const & texrow() const;
 359         TexRow & texrow();
 360
 361         ///
 362         ParIterator par_iterator_begin();
 363         ///
 364         ParConstIterator par_iterator_begin() const;
 365         ///
 366         ParIterator par_iterator_end();
 367         ///
 368         ParConstIterator par_iterator_end() const;
 369
 370         // Position of the child buffer where it appears first in the master.
 371         DocIterator firstChildPosition(Buffer const * child);
 372
 373         /** \returns true only when the file is fully loaded.
 374          *  Used to prevent the premature generation of previews
 375          *  and by the citation inset.
 376          */
 377         bool isFullyLoaded() const;
 378         /// Set by buffer_funcs' newFile.
 379         void setFullyLoaded(bool);
 380
 381         /// Our main text (inside the top InsetText)
 382         Text & text() const;
 383
 384         /// Our top InsetText
 385         Inset & inset() const;
 386
 387         //
 388         // Macro handling
 389         //
 390         /// Collect macro definitions in paragraphs
 391         void updateMacros() const;
 392         /// Iterate through the whole buffer and try to resolve macros
 393         void updateMacroInstances() const;
 394
 395         /// List macro names of this buffer, the parent and the children
 396         void listMacroNames(MacroNameSet & macros) const;
 397         /// Collect macros of the parent and its children in front of this buffer.
 398         void listParentMacros(MacroSet & macros, LaTeXFeatures & features) const;
 399
 400         /// Return macro defined before pos (or in the master buffer)
 401         MacroData const * getMacro(docstring const & name, DocIterator const & pos, bool global = true) const;
 402         /// Return macro defined anywhere in the buffer (or in the master buffer)
 403         MacroData const * getMacro(docstring const & name, bool global = true) const;
 404         /// Return macro defined before the inclusion of the child
 405         MacroData const * getMacro(docstring const & name, Buffer const & child, bool global = true) const;
 406
 407         /// Replace the inset contents for insets which InsetCode is equal
 408         /// to the passed \p inset_code.
 409         void changeRefsIfUnique(docstring const & from, docstring const & to,
 410                 InsetCode code);
 411
 412         /// get source code (latex/docbook) for some paragraphs, or all paragraphs
 413         /// including preamble
 414         void getSourceCode(odocstream & os, pit_type par_begin, pit_type par_end,
 415                 bool full_source) const;
 416
 417         /// Access to error list.
 418         /// This method is used only for GUI visualisation of Buffer related
 419         /// errors (like parsing or LateX compilation). This method is const
 420         /// because modifying the returned ErrorList does not touch the document
 421         /// contents.
 422         ErrorList & errorList(std::string const & type) const;
 423
 424         /// The Toc backend.
 425         /// This is useful only for screen visualisation of the Buffer. This
 426         /// method is const because modifying this backend does not touch
 427         /// the document contents.
 428         TocBackend & tocBackend() const;
 429
 430         ///
 431         Undo & undo();
 432
 433         /// This function is called when the buffer is changed.
 434         void changed() const;
 435         ///
 436         void updateTocItem(std::string const &, DocIterator const &) const;
 437         /// This function is called when the buffer structure is changed.
 438         void structureChanged() const;
 439         /// This function is called when some parsing error shows up.
 440         void errors(std::string const & err) const;
 441         /// This function is called when the buffer busy status change.
 442         void setBusy(bool on) const;
 443         /// This function is called when the buffer readonly status change.
 444         void setReadOnly(bool on) const;
 445         /// Update window titles of all users.
 446         void updateTitles() const;
 447         /// Reset autosave timers for all users.
 448         void resetAutosaveTimers() const;
 449         ///
 450         void message(docstring const & msg) const;
 451
 452         ///
 453         void setGuiDelegate(frontend::GuiBufferDelegate * gui);
 454         ///
 455         bool hasGuiDelegate() const;
 456
 457         ///
 458         void autoSave() const;
 459         ///
 460         void removeAutosaveFile() const;
 461
 462         /// return the format of the buffer on a string
 463         std::string bufferFormat() const;
 464
 465         ///
 466         bool doExport(std::string const & format, bool put_in_tempdir,
 467                 std::string & result_file) const;
 468         ///
 469         bool doExport(std::string const & format, bool put_in_tempdir) const;
 470         ///
 471         bool preview(std::string const & format) const;
 472         ///
 473         bool isExportable(std::string const & format) const;
 474         ///
 475         std::vector<Format const *> exportableFormats(bool only_viewable) const;
 476
 477         ///
 478         typedef std::vector<std::pair<InsetRef *, ParIterator> > References;
 479         References & references(docstring const & label);
 480         References const & references(docstring const & label) const;
 481         void clearReferenceCache() const;
 482         void setInsetLabel(docstring const & label, InsetLabel const * il);
 483         InsetLabel const * insetLabel(docstring const & label) const;
 484
 485         /// sets the buffer_ member for every inset in this buffer.
 486         // FIXME This really shouldn't be needed, but at the moment it's not
 487         // clear how to do it just for the individual pieces we need.
 488         void setBuffersForInsets() const;
 489         ///
 490         void updateLabels(UpdateScope = UpdateMaster) const;
 491         ///
 492         void updateLabels(ParIterator & parit) const;
 493
 494         /// Find next word starting from \p from.
 495         /// \p from initial position to search, will then points to the next
 496         ///    word.
 497         /// \p to will points to the end of the next word.
 498         /// \p word will contain the found word if any.
 499         /// \return true if a new word was found.
 500         bool nextWord(DocIterator & from, DocIterator & to,
 501                 docstring & word) const;
 502
 503 private:
 504         /// search for macro in local (buffer) table or in children
 505         MacroData const * getBufferMacro(docstring const & name,
 506                                          DocIterator const & pos) const;
 507         /** Update macro table starting with position of it
 508             \param it in some text inset
 509         */
 510         void updateMacros(DocIterator & it,
 511                                      DocIterator & scope) const;
 512
 513         ///
 514         void collectRelatives(BufferSet & bufs) const;
 515
 516         ///
 517         bool readFileHelper(support::FileName const & s);
 518         ///
 519         std::vector<std::string> backends() const;
 520         /** Inserts a file into a document
 521             \return \c false if method fails.
 522         */
 523         ReadStatus readFile(Lexer &, support::FileName const & filename,
 524                             bool fromString = false);
 525         ///
 526         support::FileName getAutosaveFilename() const;
 527
 528         /// Use the Pimpl idiom to hide the internals.
 529         class Impl;
 530         /// The pointer never changes although *pimpl_'s contents may.
 531         Impl * const d;
 532
 533         frontend::GuiBufferDelegate * gui_;
 534
 535         /// This function is called when the buffer structure is changed.
 536         Signal structureChanged_;
 537         /// This function is called when some parsing error shows up.
 538         //Signal errors(std::string const &) = 0;
 539         /// This function is called when some message shows up.
 540         //Signal message(docstring const &) = 0;
 541         /// This function is called when the buffer busy status change.
 542         //Signal setBusy(bool) = 0;
 543         /// Reset autosave timers for all users.
 544         Signal resetAutosaveTimers_;
 545 };
 546
 547
 548 } // namespace lyx
 549
 550 #endif