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. The file will be embedded even
 141                 // if the file is no longer referred by the document.
 142                 EMBEDDED,
 143                 // Do not embed this file, always use external version.
 144                 EXTERNAL
 145         };
 146
 147         EmbeddedFile(std::string const & file, std::string const & inzip_name,
 148                 STATUS status, ParConstIterator const & pit);
 149
 150         /// filename in the zip file, usually the relative path
 151         std::string inzipName() const { return inzip_name_; }
 152         /// embedded file, equals to temppath()/inzipName()
 153         std::string embeddedFile(Buffer const * buf) const;
 154
 155         /// paragraph id
 156         void setParIter(ParConstIterator const & pit);
 157         int const parID() const;
 158
 159         /// embedding status of this file
 160         bool embedded() const { return status_ != EXTERNAL; }
 161         STATUS status() const { return status_; }
 162         void setStatus(STATUS status) { status_ = status; }
 163
 164         // A flag indicating whether or not this filename is valid.
 165         // When lyx runs, InsetGraphics etc may be added or removed so filename
 166         // maybe obsolete. In Buffer::updateEmbeddedFiles, the EmbeddedFiles is first
 167         // invalidated (c.f. invalidate()), and all insets are asked to register
 168         // embedded files. In this way, EmbeddedFileList will be refreshed, with
 169         // status setting untouched.
 170         bool valid() const { return valid_; }
 171         void validate() { valid_ = true; }
 172         void invalidate() {     valid_ = false; }
 173
 174 private:
 175         /// filename in zip file
 176         std::string inzip_name_;
 177         /// the status of this docfile
 178         STATUS status_;
 179         ///
 180         bool valid_;
 181         /// Current position of the item, used to locate the files
 182         /// A figure may be referred by several items. In this case
 183         /// only the last location is recorded.
 184         ParConstIterator par_it_;
 185 };
 186
 187
 188 class EmbeddedFiles {
 189 public:
 190         typedef std::vector<EmbeddedFile> EmbeddedFileList;
 191 public:
 192         ///
 193         EmbeddedFiles(Buffer * buffer = NULL): file_list_(), buffer_(buffer) {}
 194         ///
 195         ~EmbeddedFiles() {}
 196
 197         /// return buffer params embedded flag
 198         bool enabled() const;
 199         /// set buffer params embedded flag
 200         void enable(bool flag);
 201
 202         /// add a file item
 203         void registerFile(std::string const & filename,
 204                 EmbeddedFile::STATUS status = EmbeddedFile::AUTO,
 205                 ParConstIterator const & pit = ParConstIterator());
 206
 207         /// scan the buffer and get a list of EmbeddedFile
 208         void update();
 209
 210         /// write a zip file
 211         bool write(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
 224         ///
 225         friend std::istream & operator>> (std::istream & is, EmbeddedFiles &);
 226
 227         friend std::ostream & operator<< (std::ostream & os, EmbeddedFiles const &);
 228 private:
 229         /// get a unique inzip name
 230         std::string const getInzipName(std::string const & name);
 231         /// list of embedded files
 232         EmbeddedFileList file_list_;
 233         ///
 234         Buffer * buffer_;
 235 };
 236
 237
 238 std::istream & operator>> (std::istream & is, EmbeddedFiles &);
 239
 240 std::ostream & operator<< (std::ostream & os, EmbeddedFiles const &);
 241
 242 }
 243 #endif