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 <vector>
  19 #include <utility>
  20
  21 #include "ParIterator.h"
  22 #include "Paragraph.h"
  23
  24 /**
  25
  26 This file, and the embedding dialog implemented in src/frontends, implements
  27 an 'Embedded Files' feature of lyx.
  28
  29
  30 Expected features:
  31 =========================
  32
  33 1. With embedding enabled (disabled by default), .lyx file can embed graphics,
  34 listings, bib file etc.
  35
  36 2. Embedded file.lyx file is a zip file, with file.lyx, manifest.txt
  37 and embedded files.
  38
  39 3. An embedding dialog is provided to change embedding status (buffer
  40 level or individual embedded files), manually embed, extract, view
  41 or edit files.
  42
  43 Overall, this feature allows two ways of editing a .lyx file
  44
  45 a. The continuous use of the pure-text .lyx file format with external
  46 files. This is the default file format, and allows external editing
  47 of .lyx file and better use of version control systems.
  48
  49 b. The embedded way. Figures etc are inserted to .lyx file and will
  50 be embedded. These embedded files can be viewed or edited through
  51 the embedding dialog. This file can be shared with others more
  52 easily.
  53
  54 Format a anb b can be converted easily, by enable/disable embedding. Diabling
  55 embedding is also called unpacking because all embedded files will be copied
  56 to their original locations.
  57
  58 Implementation:
  59 ======================
  60
  61 1. An EmbeddedFiles class is implemented to keep the embedded files (
  62 class EmbeddedFile). (c.f. src/EmbeddedFiles.[h|cpp])
  63 This class keeps a manifest that has
  64   a. external relative filename
  65   b. inzip filename. It is the relative path name if the embedded file is
  66     in or under the document directory, or file name otherwise. Name aliasing
  67     is used if two external files share the same name.
  68   c. embedding status.
  69 It also provides functions to
  70   a. manipulate manifest
  71   b. scan a buffer for embeddable files
  72   c. determine which file to use according to embedding status
  73
  74 2. When a file is saved, it is scanned for embedded files. (c.f.
  75 EmbeddedFiles::update(), Inset::registerEmbeddedFiles()).
  76
  77 3. When a lyx file file.lyx is saved, it is save to tmppath() first.
  78 Embedded files are compressed along with file.lyx and a manifest.txt.
  79 If embedding is disabled, file.lyx is saved in the usual pure-text form.
  80 (c.f. Buffer::writeFile(), EmbeddedFiles::writeFile())
  81
  82 4. When a lyx file.lyx file is opened, if it is a zip file, it is
  83 decompressed to tmppath(). If manifest.txt and file.lyx exists in
  84 tmppath(), the manifest is read to buffer, and tmppath()/file.lyx is
  85 read as usual. If file.lyx is not a zip file, it is read as usual.
  86 (c.f. bool Buffer::readFile())
  87
  88 5. A menu item Document -> Embedded Files is provided to open
  89 a embedding dialog. It handles a EmbddedFiles point directly.
  90 From this dialog, a user can disable embedding, change embedding status,
  91 or embed other files, extract, view, edit files.
  92
  93 6. If embedding of a .lyx file with embedded files is disabled, all its
  94 embedded files are copied to their respective external filenames. This
  95 is why external filename will exist even if a file is at "EMBEDDED" status.
  96
  97 7. Individual embeddable insets should find ways to handle embedded files.
  98 InsetGraphics replace params().filename with its temppath()/inzipname version
  99 when the inset is created. The filename appears as /tmp/..../inzipname
 100 when lyx runs. When params().filename is saved, lyx checks if this is an
 101 embedded file (check path == temppath()), if so, save filename() instead.
 102 (c.f. InsetGraphic::read(), InsetGraphics::edit(), InsetGraphicsParams::write())
 103
 104
 105 */
 106
 107 namespace lyx {
 108
 109 class Buffer;
 110 class Lexer;
 111 class ErrorList;
 112
 113 class EmbeddedFile : public support::DocFileName
 114 {
 115 public:
 116         EmbeddedFile() {};
 117
 118         EmbeddedFile(std::string const & file, std::string const & inzip_name,
 119                 bool embedded, Inset const * inset);
 120
 121         /// filename in the zip file, usually the relative path
 122         std::string inzipName() const { return inzip_name_; }
 123         void setInzipName(std::string name) { inzip_name_ = name; }
 124         /// embedded file, equals to temppath()/inzipName()
 125         std::string embeddedFile(Buffer const * buf) const;
 126         /// embeddedFile() or absFilename() depending on embedding status
 127         std::string availableFile(Buffer const * buf) const;
 128
 129         /// add an inset that refers to this file
 130         void addInset(Inset const * inset);
 131         Inset const * inset(int idx) const;
 132         /// save the location of this inset as bookmark so that
 133         /// it can be located using LFUN_BOOKMARK_GOTO
 134         void saveBookmark(Buffer const * buf, int idx) const;
 135         /// Number of Insets this file item is referred
 136         /// If refCount() == 0, this file must be manually inserted.
 137         /// This fact is used by the update() function to skip updating
 138         /// such items.
 139         int refCount() const { return inset_list_.size(); }
 140
 141         /// embedding status of this file
 142         bool embedded() const { return embedded_; }
 143         /// set embedding status. updateFromExternal() should be called before this
 144         /// to copy or sync the embedded file with external one.
 145         void setEmbed(bool embed) { embedded_ = embed; }
 146
 147         // A flag indicating whether or not this filename is valid.
 148         // When lyx runs, InsetGraphics etc may be added or removed so filename
 149         // maybe obsolete. In Buffer::updateEmbeddedFiles, the EmbeddedFiles is first
 150         // invalidated (c.f. invalidate()), and all insets are asked to register
 151         // embedded files. In this way, EmbeddedFileList will be refreshed, with
 152         // status setting untouched.
 153         bool valid() const { return valid_; }
 154         void validate() { valid_ = true; }
 155         void invalidate();
 156
 157         /// extract file, does not change embedding status
 158         bool extract(Buffer const * buf) const;
 159         /// update embedded file from external file, does not change embedding status
 160         bool updateFromExternalFile(Buffer const * buf) const;
 161         ///
 162         /// After the embedding status is changed, update all insets related
 163         /// to this file item.
 164         /// Because inset pointers may not be up to date, EmbeddedFiles::update()
 165         /// would better be called before this function is called.
 166         void updateInsets(Buffer const * buf) const;
 167
 168 private:
 169         /// filename in zip file
 170         std::string inzip_name_;
 171         /// the status of this docfile
 172         bool embedded_;
 173         ///
 174         bool valid_;
 175         /// Current position of the item, used to locate the files. Because one
 176         /// file item can be referred by several Insets, a vector is used.
 177         std::vector<Inset const *> inset_list_;
 178 };
 179
 180
 181 class EmbeddedFiles {
 182 public:
 183         typedef std::vector<EmbeddedFile> EmbeddedFileList;
 184 public:
 185         ///
 186         EmbeddedFiles(Buffer * buffer = 0) : file_list_(), buffer_(buffer) {}
 187         ///
 188         ~EmbeddedFiles() {}
 189
 190         /// return buffer params embedded flag
 191         bool enabled() const;
 192         /// set buffer params embedded flag. Files will be updated or extracted
 193         /// if such an operation fails, enable will fail.
 194         void enable(bool flag);
 195
 196         /// add a file item.
 197         /* \param filename filename to add
 198          * \param embed embedding status. For a new file item, this is always true.
 199          *    If the file already exists, this parameter is ignored.
 200          * \param inset Inset pointer
 201          * \param inzipName suggested inzipname
 202          */
 203         EmbeddedFile & registerFile(std::string const & filename, bool embed = false,
 204                 Inset const * inset = 0,
 205                 std::string const & inzipName = std::string());
 206
 207         /// scan the buffer and get a list of EmbeddedFile
 208         void update();
 209
 210         /// write a zip file
 211         bool writeFile(support::DocFileName const & filename);
 212
 213         void clear() { file_list_.clear(); }
 214
 215         ///
 216         EmbeddedFile & operator[](size_t idx) { return *(file_list_.begin() + idx); }
 217         EmbeddedFile const & operator[](size_t idx) const { return *(file_list_.begin() + idx); }
 218         ///
 219         EmbeddedFileList::iterator begin() { return file_list_.begin(); }
 220         EmbeddedFileList::iterator end() { return file_list_.end(); }
 221         EmbeddedFileList::const_iterator begin() const { return file_list_.begin(); }
 222         EmbeddedFileList::const_iterator end() const { return file_list_.end(); }
 223         // try to locate filename, using either absFilename() or embeddedFile()
 224         EmbeddedFileList::const_iterator find(std::string filename) const;
 225         /// extract all file items, used when disable embedding
 226         bool extract() const;
 227         /// update all files from external, used when enable embedding
 228         bool updateFromExternalFile() const;
 229         ///
 230         /// update all insets to use embedded files when embedding status is changed
 231         void updateInsets() const;
 232 private:
 233         /// get a unique inzip name, a suggestion can be given.
 234         std::string const getInzipName(std::string const & name, std::string const & inzipName);
 235         /// list of embedded files
 236         EmbeddedFileList file_list_;
 237         ///
 238         Buffer * buffer_;
 239 };
 240
 241 } // namespace lyx
 242
 243 #endif