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         /// embeddedFile() or absFilename() depending on status_ and
 155         /// file availability
 156         std::string availableFile(Buffer const * buf) const;
 157
 158         /// paragraph id
 159         void setParIter(ParConstIterator const & pit);
 160         int const parID() const;
 161
 162         /// embedding status of this file
 163         bool embedded() const { return status_ != EXTERNAL; }
 164         STATUS status() const { return status_; }
 165         void setStatus(STATUS status) { status_ = status; }
 166
 167         // A flag indicating whether or not this filename is valid.
 168         // When lyx runs, InsetGraphics etc may be added or removed so filename
 169         // maybe obsolete. In Buffer::updateEmbeddedFiles, the EmbeddedFiles is first
 170         // invalidated (c.f. invalidate()), and all insets are asked to register
 171         // embedded files. In this way, EmbeddedFileList will be refreshed, with
 172         // status setting untouched.
 173         bool valid() const { return valid_; }
 174         void validate() { valid_ = true; }
 175         void invalidate() {     valid_ = false; }
 176         ///
 177         bool extract(Buffer const * buf) const;
 178
 179 private:
 180         /// filename in zip file
 181         std::string inzip_name_;
 182         /// the status of this docfile
 183         STATUS status_;
 184         ///
 185         bool valid_;
 186         /// Current position of the item, used to locate the files
 187         /// A figure may be referred by several items. In this case
 188         /// only the last location is recorded.
 189         ParConstIterator par_it_;
 190 };
 191
 192
 193 class EmbeddedFiles {
 194 public:
 195         typedef std::vector<EmbeddedFile> EmbeddedFileList;
 196 public:
 197         ///
 198         EmbeddedFiles(Buffer * buffer = NULL): file_list_(), buffer_(buffer) {}
 199         ///
 200         ~EmbeddedFiles() {}
 201
 202         /// return buffer params embedded flag
 203         bool enabled() const;
 204         /// set buffer params embedded flag
 205         void enable(bool flag);
 206
 207         /// add a file item
 208         void registerFile(std::string const & filename,
 209                 EmbeddedFile::STATUS status = EmbeddedFile::AUTO,
 210                 ParConstIterator const & pit = ParConstIterator());
 211
 212         /// scan the buffer and get a list of EmbeddedFile
 213         void update();
 214
 215         /// write a zip file
 216         bool write(support::DocFileName const & filename);
 217
 218         void clear() { file_list_.clear(); }
 219
 220         ///
 221         EmbeddedFile & operator[](size_t idx) { return *(file_list_.begin() + idx); }
 222         EmbeddedFile const & operator[](size_t idx) const { return *(file_list_.begin() + idx); }
 223         ///
 224         EmbeddedFileList::iterator begin() { return file_list_.begin(); }
 225         EmbeddedFileList::iterator end() { return file_list_.end(); }
 226         EmbeddedFileList::const_iterator begin() const { return file_list_.begin(); }
 227         EmbeddedFileList::const_iterator end() const { return file_list_.end(); }
 228         ///
 229         bool extractAll() const;
 230         ///
 231         friend std::istream & operator>> (std::istream & is, EmbeddedFiles &);
 232
 233         friend std::ostream & operator<< (std::ostream & os, EmbeddedFiles const &);
 234 private:
 235         /// get a unique inzip name
 236         std::string const getInzipName(std::string const & name);
 237         /// list of embedded files
 238         EmbeddedFileList file_list_;
 239         ///
 240         Buffer * buffer_;
 241 };
 242
 243
 244 std::istream & operator>> (std::istream & is, EmbeddedFiles &);
 245
 246 std::ostream & operator<< (std::ostream & os, EmbeddedFiles const &);
 247
 248 }
 249 #endif