src/EmbeddedFiles.h

   1 // -*- C++ -*-
   2 /**
   3  * \file EmbeddedFiles.h
   4  * This file is part of LyX, the document processor.
   5  * Licence details can be found in the file COPYING.
   6  *
   7  * \author Bo Peng
   8  *
   9  * Full author contact details are available in file CREDITS.
  10  *
  11  */
  12
  13 #ifndef EMBEDDEDFILES_H
  14 #define EMBEDDEDFILES_H
  15
  16 #include "support/FileName.h"
  17
  18 #include <string>
  19 #include <vector>
  20
  21 /**
  22
  23 This file, and the embed checkbox in dialogs of InsetGraphics etc, implements
  24 an 'Embedded Files' feature of lyx.
  25
  26
  27 Expected features:
  28 =========================
  29
  30 1. Bundled .lyx file can embed graphics, listings, bib file etc. The bundle
  31 format is used when Document->Save in bundled format is selected.
  32
  33 2. Embedded file.lyx file is a zip file, with content.lyx and embedded files.
  34
  35 3. The embedding status of embedded files are set from individual insets.
  36
  37 4. Extra files such as .cls and .layout can be embedded from Document->
  38 Settings->Embedded Files->Extra Embedded Files.
  39
  40 5. When Document->Save in bundled format is selected, all embedded files
  41 become bundled. Changes to the external version of this file does not
  42 affect the output of the .lyx file.
  43
  44 6. When Document->Save in bundled format is unchecked, all embedded files
  45 are copied to their original locations.
  46
  47 Overall, this feature allows two ways of editing a .lyx file
  48
  49 a. The continuous use of the pure-text .lyx file format with external
  50 files. This is the default file format, and allows external editing
  51 of .lyx file and better use of version control systems.
  52
  53 b. The embedded way. Figures etc are inserted to .lyx file and will
  54 be embedded. These embedded files can be viewed or edited through
  55 the embedding dialog. This file can be shared with others more
  56 easily.
  57
  58 Format a and b can be converted easily, by packing/unpacking a .lyx file.
  59
  60 Implementation:
  61 ======================
  62
  63 1. An EmbeddedFiles class is implemented to keep the embedded files (
  64 class EmbeddedFile). (c.f. src/EmbeddedFiles.[h|cpp])
  65
  66 2. When a file is saved, it is scanned for embedded files. (c.f.
  67 EmbeddedFiles::update(), Inset::registerEmbeddedFiles()).
  68
  69 3. When a lyx file file.lyx is saved, it is save to tmppath()/content.lyx
  70 first. Embedded files are compressed along with content.lyx.
  71 If embedding is disabled, file.lyx is saved in the usual pure-text format.
  72 (c.f. Buffer::writeFile(), EmbeddedFiles::writeFile())
  73
  74 4. When a lyx file.lyx file is opened, if it is a zip file, it is
  75 decompressed to tmppath() and tmppath()/content.lyx is read as usual.
  76 (c.f. bool Buffer::readFile())
  77
  78 5. A menu item Document -> Save in bundled format is provided to pack/unpack
  79 a .lyx file.
  80
  81 6. If embedding of a .lyx file with embedded files is disabled, all its
  82 embedded files are copied to their respective external filenames. This
  83 is why external filename will exist even if a file is at "EMBEDDED" status.
  84
  85 */
  86
  87 namespace lyx {
  88
  89 class Buffer;
  90 class Inset;
  91 class Lexer;
  92 class ErrorList;
  93
  94 class EmbeddedFile : public support::DocFileName
  95 {
  96 public:
  97         EmbeddedFile(std::string const & file = std::string(),
  98                 std::string const & buffer_path = std::string());
  99
 100         /// set filename and inzipName.
 101         /**
 102          * NOTE: inzip_name_ is not unique across operation systems and is not
 103          * guaranteed to be the same across different versions of LyX.
 104          * inzip_name_ will be saved to the LyX file, and is used to indicate
 105          * whether or not a file is embedded, and where the embedded file is in
 106          * the bundled file. When a file is read, the stored inzip names are used
 107          * at first. EmbeddedFiles::validate() will then scan these embedded files
 108          * and update their inzip name, moving bundled files around if needed.
 109          * This scheme has the advantage that it is safe to change how inzip files
 110          * are saved in a bundled file.
 111          *
 112          * NOTE that this treatment does not welcome an UUID solution because
 113          * all embedded files will have to be renamed when an embedded file is
 114          * opened. It is of course possible to use saved inzipname, but that is
 115          * not easy. For example, when a new EmbeddedFile is created with the same
 116          * file as an old one, it needs to be synced to the old inzipname...
 117         **/
 118         void set(std::string const & filename, std::string const & buffer_path);
 119         /** Set the inzip name of an EmbeddedFile, which should be the name
 120          *  of an actual embedded file on disk.
 121          */
 122         void setInzipName(std::string const & name);
 123
 124         /// filename in the zip file, which is related to buffer temp directory.
 125         std::string inzipName() const { return inzip_name_; }
 126
 127         /// embedded file, equals to temppath()/inzipName()
 128         std::string embeddedFile() const;
 129         /// embeddedFile() or absFilename() depending on embedding status
 130         /// and whether or not embedding is enabled.
 131         FileName availableFile() const;
 132         /// relative file name or inzipName()
 133         std::string latexFilename(std::string const & buffer_path) const;
 134
 135         /// add an inset that refers to this file
 136         void addInset(Inset const * inset);
 137         /// clear all isnets that associated with this file.
 138         void clearInsets() const { inset_list_.clear(); }
 139
 140         /// embedding status of this file
 141         bool embedded() const { return embedded_; }
 142         /// set embedding status.
 143         void setEmbed(bool embed);
 144
 145         /// whether or not embedding is enabled in the current buffer
 146         /**
 147          * An embedded file needs to know the temp path of a buffer to know
 148          * where its embedded copy is. This has to be stored within EmbeddedFile
 149          * because this class is often used when Buffer is unavailable. However,
 150          * when an embedded file is copied to another buffer, temp_path_ has
 151          * to be updated and file copying may be needed.
 152          */
 153         bool enabled() const { return !temp_path_.empty(); }
 154         /// enable embedding of this file
 155         void enable(bool flag, Buffer const * buf, bool updateFile);
 156
 157         /// extract file, does not change embedding status
 158         bool extract() const;
 159         /// update embedded file from external file, does not change embedding status
 160         bool updateFromExternalFile() const;
 161         /// copy an embedded file to another buffer
 162         EmbeddedFile copyTo(Buffer const * buf);
 163         ///
 164         /// After the embedding status is changed, update all insets related
 165         /// to this file item. For example, a graphic inset may need to monitor
 166         /// embedded file instead of external file.
 167         void updateInsets() const;
 168
 169         /// Check readability of availableFile
 170         bool isReadableFile() const;
 171         /// Calculate checksum of availableFile
 172         unsigned long checksum() const;
 173
 174         // calculate inzip_name_ from filename
 175         std::string calcInzipName(std::string const & buffer_path);
 176         // move an embedded disk file with an existing inzip_name_ to
 177         // a calculated inzip_name_, if they differ.
 178         void syncInzipFile(std::string const & buffer_path);
 179
 180 private:
 181         /// filename in zip file
 182         std::string inzip_name_;
 183         /// the status of this docfile
 184         bool embedded_;
 185         /// Insets that contains this file item. Because a
 186         /// file item can be referred by several Insets, a vector is used.
 187         mutable std::vector<Inset const *> inset_list_;
 188         /// Embedded file needs to know whether enbedding is enabled,
 189         /// and where is the lyx temporary directory. Such information can
 190         /// be retrived from a buffer, but a buffer is not always available when
 191         /// an EmbeddedFile is used.
 192         std::string temp_path_;
 193 };
 194
 195
 196 bool operator==(EmbeddedFile const & lhs, EmbeddedFile const & rhs);
 197 bool operator!=(EmbeddedFile const & lhs, EmbeddedFile const & rhs);
 198
 199
 200 class EmbeddedFileList : public std::vector<EmbeddedFile> {
 201 public:
 202         /// set buffer params embedded flag. Files will be updated or extracted
 203         /// if such an operation fails, enable will fail.
 204         void enable(bool flag, Buffer & buffer, bool updateFile);
 205
 206         /// add a file item.
 207         /* \param file Embedded file to add
 208          * \param inset Inset pointer
 209          */
 210         void registerFile(EmbeddedFile const & file, Inset const * inset,
 211                 Buffer const & buffer);
 212         /// returns a pointer to the Embedded file representing this object,
 213         /// or null if not found. The filename should be absolute.
 214         const_iterator findFile(std::string const & filename) const;
 215         iterator findFile(std::string const & filename);
 216         /// validate embedded fies after a file is read.
 217         void validate(Buffer const & buffer);
 218         /// scan the buffer and get a list of EmbeddedFile
 219         void update(Buffer const & buffer);
 220         /// write a zip file
 221         bool writeFile(support::DocFileName const & filename, Buffer const & buffer);
 222 };
 223
 224 } // namespace lyx
 225
 226 #endif