CTK/Libs/CommandLineModules/Core/ctkCmdLineModuleDefaultPathBuilder.h

/*=============================================================================

  Library: CTK

  Copyright (c) University College London

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.

=============================================================================*/

#ifndef __ctkCmdLineModuleDefaultPathBuilder_h
#define __ctkCmdLineModuleDefaultPathBuilder_h

#include "ctkCommandLineModulesCoreExport.h"
#include <QStringList>
#include <QScopedPointer>

struct ctkCmdLineModuleDefaultPathBuilderPrivate;

/**
 * \class ctkCmdLineModuleDefaultPathBuilder
 * \brief Builds up a list of directory paths to search for command line modules.
 * \ingroup CommandLineModulesCore_API
 * \author m.clarkson@ucl.ac.uk
 *
 * Simple class to enable the user to easily add various directories
 * to a list of directories. You create this object, add a load of directories
 * and then call getDirectoryList() to get a StringList of directory locations.
 *
 * The choices are:
 * <pre>
 * 1. The directory defined by the CTK_MODULE_LOAD_PATH environment variable or any sub-directory under this.
 * 2. The directory defined by the users HOME directory, or any sub-directory under this.
 * 3. The directory defined by the current working directory, or any sub-directory under this.
 * 4. The directory defined by the application installation directory or any sub-directory under this.
 * </pre>
 *
 * A strictMode flag exists to decide if this class only returns directories that already exist.
 */
class CTK_CMDLINEMODULECORE_EXPORT ctkCmdLineModuleDefaultPathBuilder
{

public:

  ctkCmdLineModuleDefaultPathBuilder();
  ~ctkCmdLineModuleDefaultPathBuilder();

  /**
   * @brief Clears the current list of directories.
   */
  virtual void clear();

  /**
   * @brief Sets strict mode which checks that all directories already exist.
   * @param strict if true this object will only return existing directories,
   * if false, the return StringList is un-checked.
   */
  virtual void setStrictMode(const bool& strict);

  /**
   * @brief Returns the strict mode flag.
   */
  virtual bool strictMode() const;

  /**
   * @brief Adds the users home directory, or if specified a sub-directory.
   *
   * This depends on QDir::home() existing. If this is not the case,
   * then this method will do nothing and ignore the request.
   */
  virtual void addHomeDir(const QString& subFolder = QString());

  /**
   * @brief Adds the current working directory, or if specified a sub-directory.
   *
   * This depends on QDir::current() existing. If this is not the case,
   * then this method will do nothing and ignore the request.
   */
  virtual void addCurrentDir(const QString& subFolder = QString());

  /**
   * @brief Adds the application installation directory, or if specified a sub-directory.
   */
  virtual void addApplicationDir(const QString& subFolder = QString());

  /**
   * @brief Adds the directory denoted by the environment variable CTK_MODULE_LOAD_PATH,
   * or if specified a sub-directory.
   */
  virtual void addCtkModuleLoadPathDir(const QString& subFolder = QString());

  /**
   * @brief Returns the QStringList containing directories.
   * @return QStringList of directories or, if in strict mode, directories that already exist.
   */
  virtual QStringList getDirectoryList() const;

private:

  QScopedPointer<ctkCmdLineModuleDefaultPathBuilderPrivate> d;
  Q_DISABLE_COPY(ctkCmdLineModuleDefaultPathBuilder)
};

#endif