merge packagestructure with package, make the commensurate change in the build

CMakeLists.txt

@@ -96,7 +96,6 @@ set(plasma_LIB_SRCS
     extenders/extender.cpp
     extenders/extendergroup.cpp
     extenders/extenderitem.cpp
-    packagestructure.cpp
     package.cpp
     paintutils.cpp
     pluginloader.cpp
@@ -315,7 +314,6 @@ set(plasma_LIB_INCLUDES
     paintutils.h
     windoweffects.h
     framesvg.h
-    packagestructure.h
     package.h
     plasma.h
     plasma_export.h
@@ -403,7 +401,7 @@ install(FILES
    data/servicetypes/plasma-containment.desktop
    data/servicetypes/plasma-containmentactions.desktop
    data/servicetypes/plasma-dataengine.desktop
-   data/servicetypes/plasma-packagestructure.desktop
+   data/servicetypes/plasma-package.desktop
    data/servicetypes/plasma-runner.desktop
    data/servicetypes/plasma-scriptengine.desktop
    data/servicetypes/plasma-service.desktop

package.h

@@ -22,8 +22,9 @@
 
 #include <QtCore/QStringList>
 
+#include <kplugininfo.h>
+
 #include <plasma/plasma.h>
-#include <plasma/packagestructure.h>
 #include <plasma/plasma_export.h>
 
 namespace Plasma
@@ -32,36 +33,71 @@ namespace Plasma
 /**
  * @class Package plasma/package.h <Plasma/Package>
  *
- * @short object representing an installed Plasmagik package
+ * @short object representing an installed Plasma package
- **/
+ *
+ * Package defines what is in a package and provides easy access to the contents.
+ *
+ * To define a package, one might write the following code:
+ *
+ @code
+    Package package;
+
+    package.addDirectoryDefinition("images", "pics/", i18n("Images"));
+    QStringList mimeTypes;
+    mimeTypes << "image/svg" << "image/png" << "image/jpeg";
+    package.setMimeTypes("images", mimeTypes);
+
+    package.addDirectoryDefinition("scripts", "code/", i18n("Executable Scripts"));
+    mimeTypes.clear();
+    mimeTypes << "text/\*";
+    package.setMimeTypes("scripts", mimeTypes);
+
+    package.addFileDefinition("mainscript", "code/main.js", i18n("Main Script File"));
+    package.setRequired("mainscript", true);
+ @endcode
+ * One may also choose to create a subclass of Package and include the setup
+ * in the constructor.
+ *
+ * Either way, Package creates a self-documenting contract between the packager and
+ * the application without exposing package internals such as actual on-disk structure
+ * of the package or requiring that all contents be explicitly known ahead of time.
+ *
+ * Subclassing Package does have provide a number of potential const benefits:
+ *    * the package can be notified of path changes via the virtual pathChanged() method
+ *    * the subclass may implement mechanisms to install and remove packages using the
+ *      virtual installPackage and uninstallPackage methods
+ *    * subclasses can be compiled as plugins for easy re-use
+ **/
+//TODO: write documentation on USING a package
 
-class PackageMetadata;
 class PackagePrivate;
 
 class PLASMA_EXPORT Package
 {
-    public:
+public:
+    /**
+     * Loads a package format by name.
+     *
+     * @param format If not empty, attempts to locate the given format, either
+     *             from built-ins or via plugins.
+     * @param specialization used to find script extensions for the given format, e.g. "QML" for "Plasma/Applet"
+     * @return a package that matches the format, if available, or an invalid package if not
+     */
+    static Package load(const QString &format, const QString &specialization = QString());
+
     /**
      * Default constructor that creates an invalid Package
      * @since 4.6
      */
     explicit Package();
 
-        /**
-          * Construct a Package object.
-          *
-          * @param packagePath full path to the package directory
-          * @param structure the package structure describing this package
-          */
-        Package(const QString &packagePath, PackageStructure::Ptr structure);
-
     /**
      * Copy constructore
      * @since 4.6
      */
     Package(const Package &other);
 
-        ~Package();
+    virtual ~Package();
 
     /**
      * Assignment operator
@@ -70,40 +106,10 @@ class PLASMA_EXPORT Package
     Package &operator=(const Package &rhs);
 
     /**
-         * @return true if all the required components as defined in
+     * @return true if all the required components exist
-         * the PackageStructure exist
      **/
     bool isValid() const;
 
-        /**
-         * Get the path to a given file.
-         *
-         * @param fileType the type of file to look for, as defined in the
-         *               package structure
-         * @param filename the name of the file
-         * @return path to the file on disk. QString() if not found.
-         **/
-        QString filePath(const char *fileType, const QString &filename) const;
-
-        /**
-         * Get the path to a given file.
-         *
-         * @param fileType the type of file to look for, as defined in the
-         *               package structure. The type must refer to a file
-         *               in the package structure and not a directory.
-         * @return path to the file on disk. QString() if not found
-         **/
-        QString filePath(const char *fileType) const;
-
-        /**
-         * Get the list of files of a given type.
-         *
-         * @param fileType the type of file to look for, as defined in the
-         *               package structure.
-         * @return list of files by name, suitable for passing to filePath
-         **/
-        QStringList entryList(const char *fileType) const;
-
     /**
      * Sets the path to the root of this package
      * @param path and absolute path
@@ -117,9 +123,70 @@ class PLASMA_EXPORT Package
     const QString path() const;
 
     /**
-         * @return the PackageStructure use in this Package
+     * Get the path to a given file based on the key and.an optional filename.
+     * Example: finding the main script in a scripting package:
+     *      filePath("mainscript")
+     *
+     * Example: finding a specific image in the images directory:
+     *      filePath("images", "myimage.png")
+     *
+     * @param key the key of the file type to look for,
+     * @param filename optional name of the file to locate within the package
+     * @return path to the file on disk. QString() if not found.
+     **/
+    QString filePath(const char *key, const QString &filename = QString()) const;
+
+    /**
+     * Get the list of files of a given type.
+     *
+     * @param fileType the type of file to look for, as defined in the
+     *               package structure.
+     * @return list of files by name, suitable for passing to filePath
+     **/
+    QStringList entryList(const char *key) const;
+
+    /**
+     * @return user visible name for the given entry
+     **/
+    QString name(const char *key) const;
+
+    /**
+     * @return true if the item at path exists and is required
+     **/
+    bool isRequired(const char *key) const;
+
+    /**
+     * @return the mimeTypes associated with the path, if any
+     **/
+    QStringList mimeTypes(const char *key) const;
+
+    /**
+     * @return the prefix paths inserted between the base path and content entries, in order of priority.
+     *         When searching for a file, all paths will be tried in order.
+     * @since 4.6
      */
-        const PackageStructure::Ptr structure() const;
+    QStringList contentsPrefixPaths() const;
+
+    /**
+     * @return preferred package root. This defaults to plasma/plasmoids/
+     */
+    QString defaultPackageRoot() const;
+
+    /**
+     * @return service prefix used in desktop files. This defaults to plasma-applet-
+     */
+    QString servicePrefix() const;
+
+    /**
+     * @return true if paths/symlinks outside the package itself should be followed.
+     * By default this is set to false for security reasons.
+     */
+    bool allowExternalPaths() const;
+
+    /**
+      * @return the package metadata object.
+      */
+    virtual KPluginInfo metadata() const;
 
     /**
      * @return a SHA1 hash digest of the contents of the package in hexadecimal form
@@ -127,15 +194,185 @@ class PLASMA_EXPORT Package
      */
     QString contentsHash() const;
 
-    private:
+    /**
-        PackagePrivate * const d;
+     * Adds a directory to the structure of the package. It is added as
+     * a not-required element with no associated mimeTypes.
+     *
+     * Starting in 4.6, if an entry with the given key
+     * already exists, the path is added to it as a search alternative.
+     *
+     * @param key  used as an internal label for this directory
+     * @param path the path within the package for this directory
+     * @param name the user visible (translated) name for the directory
+     **/
+    void addDirectoryDefinition(const char *key, const QString &path, const QString &name);
 
-        friend class Applet;
+    /**
-        friend class AppletPrivate;
+     * Adds a file to the structure of the package. It is added as
+     * a not-required element with no associated mimeTypes.
+     *
+     * Starting in 4.6, if an entry with the given key
+     * already exists, the path is added to it as a search alternative.
+     *
+     * @param key  used as an internal label for this file
+     * @param path the path within the package for this file
+     * @param name the user visible (translated) name for the file
+     **/
+    void addFileDefinition(const char *key, const QString &path, const QString &name);
+
+    /**
+     * Removes a definition from the structure of the package.
+     * @since 4.6
+     * @param key the internal label of the file or directory to remove
+     */
+    void removeDefinition(const char *key);
+
+    /**
+     * Sets whether or not a given part of the structure is required or not.
+     * The path must already have been added using addDirectoryDefinition
+     * or addFileDefinition.
+     *
+     * @param key the entry within the package
+     * @param required true if this entry is required, false if not
+     */
+    void setRequired(const char *key, bool required);
+
+    /**
+     * Defines the default mimeTypes for any definitions that do not have
+     * associated mimeTypes. Handy for packages with only one or predominantly
+     * one file type.
+     *
+     * @param mimeTypes a list of mimeTypes
+     **/
+    void setDefaultMimeTypes(QStringList mimeTypes);
+
+    /**
+     * Define mimeTypes for a given part of the structure
+     * The path must already have been added using addDirectoryDefinition
+     * or addFileDefinition.
+     *
+     * @param key the entry within the package
+     * @param mimeTypes a list of mimeTypes
+     **/
+    void setMimeTypes(const char *key, QStringList mimeTypes);
+
+    /**
+     * Sets the prefixes that all the contents in this package should
+     * appear under. This defaults to "contents/" and is added automatically
+     * between the base path and the entries as defined by the package
+     * structure. Multiple entries can be added.
+     * In this case each file request will be searched in all prefixes in order,
+     * and the first found will be returned.
+     *
+     * @param prefix paths the directory prefix to use
+     * @since 4.6
+     */
+    void setContentsPrefixPaths(const QStringList &prefixPaths);
+
+    /**
+     * Sets service prefix.
+     */
+    void setServicePrefix(const QString &servicePrefix);
+
+    /**
+     * Sets whether or not external paths/symlinks can be followed by a package
+     * @param allow true if paths/symlinks outside of the package should be followed,
+     *             false if they should be rejected.
+     */
+    void setAllowExternalPaths(bool allow);
+
+    /**
+     * Sets preferred package root.
+     */
+    void setDefaultPackageRoot(const QString &packageRoot);
+
+    /**
+     * Called whenever the path changes so that subclasses may take
+     * package specific actions.
+     */
+    virtual void pathChanged();
+
+    // Content structure description methods
+    /**
+     * @return all directories registered as part of this Package's structure
+     */
+    QList<const char*> directories() const;
+
+    /**
+     * @return all directories registered as part of this Package's required structure
+     */
+    QList<const char*> requiredDirectories() const;
+
+    /**
+     * @return all files registered as part of this Package's structure
+     */
+    QList<const char*> files() const;
+
+    /**
+     * @return all files registered as part of this Package's required structure
+     */
+    QList<const char*> requiredFiles() const;
+
+    /**
+     * Read a package structure from a config file.
+     */
+    void read(const KConfigBase *config);
+
+    /**
+     * Write this package structure to a config file.
+     */
+    void write(KConfigBase *config) const;
+
+    /**
+     * Installs a package matching this package structure. By default installs a
+     * native Plasma::Package.
+     *
+     * @param archivePath path to the package archive file
+     * @param packageRoot path to the directory where the package should be
+     *                    installed to
+     * @return true on successful installation, false otherwise
+     **/
+    virtual bool installPackage(const QString &archivePath, const QString &packageRoot);
+
+    /**
+     * Uninstalls a package matching this package structure.
+     *
+     * @param packageName the name of the package to remove
+     * @param packageRoot path to the directory where the package should be installed to
+     * @return true on successful removal of the package, false otherwise
+     */
+    virtual bool uninstallPackage(const QString &packageName, const QString &packageRoot);
+
+private:
+    PackagePrivate * const d;
+};
+
+class PackageFactory : public QObject
+{
+    Q_OBJECT
+
+public:
+    PackageFactory(QObject *parent, const QVariantList &args);
+    virtual Package package() const;
 };
 
 } // Namespace
 
+/**
+ * Register a Package class when it is contained in a loadable module
+ */
+#define K_EXPORT_PLASMA_PACKAGE(libname, classname) \
+class classname "_Factory" : public Plasma::PackageFactory { \
+    Q_OBJECT \
+public: \
+    classname "_PackageFactory"(QObject *parent, const QVariantList &args) \
+        : Plasma::PackageFactory(parent, args) {} \
+    Package package() const { return classname(); } \
+}; \
+K_PLUGIN_FACTORY(factory, registerPlugin<classname "_PackageFactory">();) \
+K_EXPORT_PLUGIN(factory("plasma_package_" #libname)) \
+K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION)
+
 Q_DECLARE_METATYPE(Plasma::Package)
 #endif