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. Embedding of certain files are automatic (graphics, bib etc), and
  37 other files can be embedded manually.
  38
  39 3. Embedded file.lyx file is a zip file, with file.lyx, manifest.txt
  40 and embedded files.
  41
  42 4. Embedded files can be "EMBEDDED", "EXTERNAL", or "AUTO". In the
  43 "AUTO" mode, external files will be used if available; otherwise the
  44 embedded version will be used. In this way, users can work as usual by
  45 modifying external listings, graphics, and do not have to worry about
  46 embedding. "EMBEDDED" and "EXTERNAL" modes ignore or use external files
  47 respectively.
  48
  49 5. An embedding dialog is provided to change embedding status (buffer
  50 level or individual embedded files), manually embed, extract, view
  51 or edit files.
  52
  53 Overall, this feature allows two ways of editing a .lyx file
  54
  55 a. The continuous use of the pure-text .lyx file format with external
  56 files. This is the default file format, and allows external editing
  57 of .lyx file and better use of version control systems.
  58
  59 b. The embedded way. Figures etc are inserted to .lyx file and will
  60 be embedded. These embedded files can be viewed or edited through
  61 the embedding dialog. This file can be shared with others more
  62 easily. The advantage of lyx' embedding approach is that external files
  63 will be automatically used and embedded if the file is in "AUTO" mode.
  64
  65
  66 Implementation:
  67 ======================
  68
  69 1. An EmbeddedFiles class is implemented to keep the embedded files (
  70 class EmbeddedFile). (c.f. src/EmbeddedFiles.[h|cpp])
  71 This class keeps a manifest that has
  72   a. external relative filename
  73   b. inzip filename. It is the relative path name if the embedded file is
  74     in or under the document directory, or file name otherwise. Name aliasing
  75     is used if two external files share the same name.
  76   c. embedding mode.
  77 It also provides functions to
  78   a. manipulate manifest
  79   b. scan a buffer for embeddable files
  80   c. look up inzipname from external filename
  81   d. look up external filename from inzipname
  82
  83 2. When a file is saved, it is scanned for embedded files. (c.f.
  84 EmbeddedFiles::update(), Inset::registerEmbeddedFiles()).
  85
  86 3. When a lyx file file.lyx is saved, it is save to tmppath() first.
  87 Embedded files are compressed along with file.lyx and a manifest.txt.
  88 If embedding is disabled, file.lyx is saved in the usual pure-text form.
  89 (c.f. Buffer::writeFile(), EmbeddedFiles::write())
  90
  91 4. When a lyx file.lyx file is opened, if it is a zip file, it is
  92 decompressed to tmppath(). If manifest.txt and file.lyx exists in
  93 tmppath(), the manifest is read to buffer, and tmppath()/file.lyx is
  94 read as usual. If file.lyx is not a zip file, it is read as usual.
  95 (c.f. bool Buffer::readFile())
  96
  97 5. A menu item Document -> Embedded Files is provided to open
  98 a embedding dialog. It handles a EmbddedFiles point directly.
  99 From this dialog, a user can disable embedding, change embedding status,
 100 or embed other files, extract, view, edit files.
 101
 102 6. When a lyx file is loaded, Embedded files can have
 103   a. both external and internal copy
 104   b. only external copy (filename())
 105   c. only embedded copy (temppath()/inzipname)
 106 And each can have "AUTO", "EXTERNAL", "EMBEDDED" status. Proper
 107 handling of each case is required.
 108
 109 7. If embedding of a .lyx file with embedded files is disabled, all its
 110 embedded files are copied to their respective external filenames. This
 111 is why external filename will exist even if a file is at "EMBEDDED" status.
 112
 113 8. Individual embeddable insets should find ways to handle embedded files.
 114 InsetGraphics replace params().filename with its temppath()/inzipname version
 115 when the inset is created. The filename appears as /tmp/..../inzipname
 116 when lyx runs. When params().filename is saved, lyx checks if this is an
 117 embedded file (check path == temppath()), if so, save filename() instead.
 118 (c.f. InsetGraphic::read(), InsetGraphics::edit(), InsetGraphicsParams::write())
 119
 120
 121 */
 122
 123 namespace lyx {
 124
 125 class Buffer;
 126
 127 class EmbeddedFile : public support::DocFileName
 128 {
 129 public:
 130         /**
 131                 Embedding status of this DocFileName.
 132          */
 133         enum STATUS {
 134                 // uninitialized/invalid status
 135                 NONE,
 136                 // If the external version of the file is available, it will be used
 137                 // to generate output, and be embedded to the saved lyx file.
 138                 // Otherwise, embedded version will be used.
 139                 AUTO,
 140                 // Always use embedded version.
 141                 EMBEDDED,
 142                 // Do not embed this file, always use external version.
 143                 EXTERNAL
 144         };
 145
 146         EmbeddedFile(std::string const & file, std::string const & inzip_name,
 147                 STATUS status, ParConstIterator const & pit);
 148
 149         /// filename in the zip file, usually the relative path
 150         std::string inzipName() const { return inzip_name_; }
 151         /// embedded file, equals to temppath()/inzipName()
 152         std::string embeddedFile(Buffer const * buf) const;
 153
 154         /// paragraph id
 155         void setParIter(ParConstIterator const & pit);
 156         int const parID() const { return par_it_->id(); }
 157
 158         /// embedding status of this file
 159         bool embedded() const { return status_ != EXTERNAL; }
 160         STATUS status() const { return status_; }
 161         void setStatus(STATUS status) { status_ = status; }
 162
 163         // A flag indicating whether or not this filename is valid.
 164         // When lyx runs, InsetGraphics etc may be added or removed so filename
 165         // maybe obsolete. In Buffer::updateEmbeddedFiles, the EmbeddedFiles is first
 166         // invalidated (c.f. invalidate()), and all insets are asked to register
 167         // embedded files. In this way, EmbeddedFileList will be refreshed, with
 168         // status setting untouched.
 169         bool valid() const { return valid_; }
 170         void validate() { valid_ = true; }
 171         void invalidate() {     valid_ = false; }
 172
 173 private:
 174         /// filename in zip file
 175         std::string inzip_name_;
 176         /// the status of this docfile
 177         STATUS status_;
 178         ///
 179         bool valid_;
 180         /// Current position of the item, used to locate the files
 181         /// A figure may be referred by several items. In this case
 182         /// only the last location is recorded.
 183         ParConstIterator par_it_;
 184 };
 185
 186
 187 class EmbeddedFiles {
 188 public:
 189         typedef std::vector<EmbeddedFile> EmbeddedFileList;
 190 public:
 191         ///
 192         EmbeddedFiles(Buffer * buffer = NULL): file_list_(), buffer_(buffer) {}
 193         ///
 194         ~EmbeddedFiles() {}
 195
 196         /// return buffer params embedded flag
 197         bool enabled() const;
 198         /// set buffer params embedded flag
 199         void enable(bool flag);
 200
 201         /// add a file item
 202         void registerFile(std::string const & filename,
 203                 EmbeddedFile::STATUS status = EmbeddedFile::AUTO,
 204                 ParConstIterator const & pit = ParConstIterator());
 205
 206         /// scan the buffer and get a list of EmbeddedFile
 207         void update();
 208
 209         /// write a zip file
 210         bool write(support::DocFileName const & filename);
 211
 212         void clear() { file_list_.clear(); }
 213
 214         ///
 215         EmbeddedFile & operator[](size_t idx) { return *(file_list_.begin() + idx); }
 216         EmbeddedFile const & operator[](size_t idx) const { return *(file_list_.begin() + idx); }
 217         ///
 218         EmbeddedFileList::iterator begin() { return file_list_.begin(); }
 219         EmbeddedFileList::iterator end() { return file_list_.end(); }
 220         EmbeddedFileList::const_iterator begin() const { return file_list_.begin(); }
 221         EmbeddedFileList::const_iterator end() const { return file_list_.end(); }
 222
 223         ///
 224         friend std::istream & operator>> (std::istream & is, EmbeddedFiles &);
 225
 226         friend std::ostream & operator<< (std::ostream & os, EmbeddedFiles const &);
 227 private:
 228         /// if a inzip name already exists
 229         bool validInzipName(std::string const & name);
 230         /// list of embedded files
 231         EmbeddedFileList file_list_;
 232         ///
 233         Buffer * buffer_;
 234 };
 235
 236
 237 std::istream & operator>> (std::istream & is, EmbeddedFiles &);
 238
 239 std::ostream & operator<< (std::ostream & os, EmbeddedFiles const &);
 240
 241 }
 242 #endif