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 embedding dialog implemented in src/frontends, 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 can be set at the inset level,
  36 or from Document->Settings->Embedded Files.
  37
  38 4. Extra files such as .cls and .layout can be embedded from Document->
  39 Settings->Embedded Files->Extra Files.
  40
  41 5. When Document->Save in bundled format is selected, all embedded files
  42 become bundled. Changes to the external version of this file does not
  43 affect the output of the .lyx file.
  44
  45 6. When Document->Save in bundled format is unchecked, all embedded files
  46 are copied to their original locations.
  47
  48 Overall, this feature allows two ways of editing a .lyx file
  49
  50 a. The continuous use of the pure-text .lyx file format with external
  51 files. This is the default file format, and allows external editing
  52 of .lyx file and better use of version control systems.
  53
  54 b. The embedded way. Figures etc are inserted to .lyx file and will
  55 be embedded. These embedded files can be viewed or edited through
  56 the embedding dialog. This file can be shared with others more
  57 easily.
  58
  59 Format a and b can be converted easily, by packing/unpacking a .lyx file.
  60
  61 NOTE: With current implementation, files with absolute filenames (not in
  62 or deeper under the current document directory) can not be embedded.
  63
  64 Implementation:
  65 ======================
  66
  67 1. An EmbeddedFiles class is implemented to keep the embedded files (
  68 class EmbeddedFile). (c.f. src/EmbeddedFiles.[h|cpp])
  69
  70 2. When a file is saved, it is scanned for embedded files. (c.f.
  71 EmbeddedFiles::update(), Inset::registerEmbeddedFiles()).
  72
  73 3. When a lyx file file.lyx is saved, it is save to tmppath()/content.lyx
  74 first. Embedded files are compressed along with content.lyx.
  75 If embedding is disabled, file.lyx is saved in the usual pure-text form.
  76 (c.f. Buffer::writeFile(), EmbeddedFiles::writeFile())
  77
  78 4. When a lyx file.lyx file is opened, if it is a zip file, it is
  79 decompressed to tmppath() and tmppath()/content.lyx is read as usual.
  80 (c.f. bool Buffer::readFile())
  81
  82 5. A menu item Document -> Save in bundled format is provided to pack/unpack
  83 a .lyx file.
  84
  85 6. If embedding of a .lyx file with embedded files is disabled, all its
  86 embedded files are copied to their respective external filenames. This
  87 is why external filename will exist even if a file is at "EMBEDDED" status.
  88
  89 */
  90
  91 namespace lyx {
  92
  93 class Buffer;
  94 class Inset;
  95 class Lexer;
  96 class ErrorList;
  97
  98 class EmbeddedFile : public support::DocFileName
  99 {
 100 public:
 101         EmbeddedFile(std::string const & file = std::string(),
 102                 std::string const & buffer_path = std::string());
 103
 104         /// set filename and inzipName.
 105         void set(std::string const & filename, std::string const & buffer_path);
 106
 107         /// filename in the zip file, which is the relative path
 108         std::string inzipName() const { return inzip_name_; }
 109
 110         /// embedded file, equals to temppath()/inzipName()
 111         std::string embeddedFile(Buffer const * buf) const;
 112         /// embeddedFile() or absFilename() depending on embedding status
 113         std::string availableFile(Buffer const * buf) const;
 114
 115         /// add an inset that refers to this file
 116         void addInset(Inset const * inset);
 117         Inset const * inset(int idx) const;
 118         /// Number of Insets this file item is referred
 119         /// If refCount() == 0, this file must be manually inserted.
 120         /// This fact is used by the update() function to skip updating
 121         /// such items.
 122         int refCount() const { return inset_list_.size(); }
 123
 124         /// embedding status of this file
 125         bool embedded() const { return embedded_; }
 126         /// set embedding status. updateFromExternal() should be called before this
 127         /// to copy or sync the embedded file with external one.
 128         void setEmbed(bool embed);
 129         /// Only files in or under current document path is embeddable
 130         bool embeddable() const { return inzip_name_ != ""; }
 131
 132         /// extract file, does not change embedding status
 133         bool extract(Buffer const * buf) const;
 134         /// update embedded file from external file, does not change embedding status
 135         bool updateFromExternalFile(Buffer const * buf) const;
 136         ///
 137         /// After the embedding status is changed, update all insets related
 138         /// to this file item. For example, a graphic inset may need to monitor
 139         /// embedded file instead of external file. To make sure inset pointers
 140         /// are up to date, please make sure there is no modification to the
 141         /// document between EmbeddedFiles::update() and this function.
 142         void updateInsets(Buffer const * buf) const;
 143
 144 private:
 145         /// filename in zip file
 146         std::string inzip_name_;
 147         /// the status of this docfile
 148         bool embedded_;
 149         /// Insets that contains this file item. Because a
 150         /// file item can be referred by several Insets, a vector is used.
 151         std::vector<Inset const *> inset_list_;
 152 };
 153
 154
 155 bool operator==(EmbeddedFile const & lhs, EmbeddedFile const & rhs);
 156 bool operator!=(EmbeddedFile const & lhs, EmbeddedFile const & rhs);
 157
 158
 159 class EmbeddedFiles {
 160 public:
 161         typedef std::vector<EmbeddedFile> EmbeddedFileList;
 162 public:
 163         ///
 164         EmbeddedFiles(Buffer * buffer = 0) : file_list_(), buffer_(buffer) {}
 165         ///
 166         ~EmbeddedFiles() {}
 167
 168         /// return buffer params embedded flag
 169         bool enabled() const;
 170         /// set buffer params embedded flag. Files will be updated or extracted
 171         /// if such an operation fails, enable will fail.
 172         void enable(bool flag);
 173
 174         /// add a file item.
 175         /* \param file Embedded file to add
 176          * \param inset Inset pointer
 177          */
 178         EmbeddedFile & registerFile(EmbeddedFile const & file, Inset const * inset = 0);
 179
 180         /// scan the buffer and get a list of EmbeddedFile
 181         void update();
 182
 183         /// write a zip file
 184         bool writeFile(support::DocFileName const & filename);
 185
 186         void clear() { file_list_.clear(); }
 187
 188         ///
 189         EmbeddedFile & operator[](size_t idx) { return *(file_list_.begin() + idx); }
 190         EmbeddedFile const & operator[](size_t idx) const { return *(file_list_.begin() + idx); }
 191         ///
 192         EmbeddedFileList::iterator begin() { return file_list_.begin(); }
 193         EmbeddedFileList::iterator end() { return file_list_.end(); }
 194         EmbeddedFileList::const_iterator begin() const { return file_list_.begin(); }
 195         EmbeddedFileList::const_iterator end() const { return file_list_.end(); }
 196         // try to locate filename, using either absFilename() or embeddedFile()
 197         EmbeddedFileList::const_iterator find(std::string filename) const;
 198         /// extract all file items, used when disable embedding
 199         bool extractAll() const;
 200         /// update all files from external, used when enable embedding
 201         bool updateFromExternalFile() const;
 202         ///
 203         /// update all insets to use embedded files when embedding status is changed
 204         void updateInsets() const;
 205 private:
 206         /// list of embedded files
 207         EmbeddedFileList file_list_;
 208         ///
 209         Buffer * buffer_;
 210 };
 211
 212 } // namespace lyx
 213
 214 #endif