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