fileexpressions.hpp

Go to the documentation of this file.

/** ************************************************************************************************
 * \file
 * This header file is part of module \alib_files of the \aliblong.
 *
 * \emoji :copyright: 2013-2024 A-Worx GmbH, Germany.
 * Published under \ref mainpage_license "Boost Software License".
 **************************************************************************************************/
#ifndef HPP_ALIB_FILES_FILEEXPRESSIONS
#define HPP_ALIB_FILES_FILEEXPRESSIONS 1
 
#if !defined(HPP_ALIB_FILES_FTREE)
#   include "alib/files/ftree.hpp"
#endif
 
#if !defined(HPP_ALIB_FILES_FFILTER)
#   include "alib/files/ffilter.hpp"
#endif
 
 
ALIB_ASSERT_MODULE(EXPRESSIONS)
 
#ifndef HPP_ALIB_EXPRESSIONS_PLUGINS_CALCULUS
#   include "alib/expressions/plugins/calculus.hpp"
#endif
 
namespace alib{ namespace files {
 
 
/**
 * This class implements an \ref alib_mod_expressions "ALib Expression Compiler Plugin"
 * and thus enables "run-time expressions" to work with nodes of \alib{files;FTree}
 *
 * Unless multi-threaded use is planned, an application should create one singleton of this class.
 *
 * Method #CreateFilter creates an object of inner type  \alib{files;FileExpressions::Filter}, which
 * implements the \b FFilter interface  used with scan parameters of function
 * \alib{files;ScanFiles}. This allows run-time evaluation of filter rules, for example rules
 * coming from the command line, from configuration files or from interactive end-user input
 * (hence from an UX/UI).
 *
 * Of-course the expression compiler can also be used directly without using the inner
 * \b Filter class for evaluation and expressions do not need return a boolean "yes/no" result.
 *
 * @see
 *   For a quick tutorial, see the \ref alib_mod_files "Programmer's Manual".
 *
 * # Implemented Expression Features #
 * %Compiler plug-in that provides expressions on filesystem entries, stored in nodes of
 * class \alib{files;FTree}.
 *
 * All identifier and function names are defined case insensitive.
 * Furthermore, the tokens are not hard-coded but resourced with \alibcamp singleton
 * \ref alib::FILES. With that, for example language translations might be performed.
 *
 * ## Types:  ##
 * <br>
 * This plug-in introduces the following types to the expression compiler:
 * - \alib{files;FInfo::Types}
 * - \alib{files;FInfo::Permissions}
 * - \alib{files;FInfo::TOwnerAndGroupID}
 *
 * Each types are auto-casted to \b Integer to allow all common operators, especially bitwise
 * boolean operators.
 *
 * ## Constants:  ##
 * <br>
 * Type                            | Name             |Min. Abbreviation| Description
 * --------------------------------|------------------|-----------------|-------------
 * \alib{files::FInfo;Permissions} |\b OwnerRead      | ore       | Used test result of function \p{Permission}.
 * \alib{files::FInfo;Permissions} |\b OwnerWrite     | ow        | Used test result of function \p{Permission}.
 * \alib{files::FInfo;Permissions} |\b OwnerExecute   | oe        | Used test result of function \p{Permission}.
 * \alib{files::FInfo;Permissions} |\b GroupRead      | gr        | Used test result of function \p{Permission}.
 * \alib{files::FInfo;Permissions} |\b GroupWrite     | gw        | Used test result of function \p{Permission}.
 * \alib{files::FInfo;Permissions} |\b GroupExecute   | ge        | Used test result of function \p{Permission}.
 * \alib{files::FInfo;Permissions} |\b OthersRead     | otr       | Used test result of function \p{Permission}.
 * \alib{files::FInfo;Permissions} |\b OthersWrite    | otw       | Used test result of function \p{Permission}.
 * \alib{files::FInfo;Permissions} |\b OthersExecute  | ote       | Used test result of function \p{Permission}.
 * \alib{files::FInfo;Types}       |\b Directory      | dir       | Used to compare the result of function \p{Type}.
 * \alib{files::FInfo;Types}       |\b SymbolicLinkDir| sld       | Used to compare the result of function \p{Type}.
 * \alib{files::FInfo;Types}       |\b Regular        | reg       | Used to compare the result of function \p{Type}.
 * \alib{files::FInfo;Types}       |\b SymbolicLink   | sl        | Used to compare the result of function \p{Type}.
 * \alib{files::FInfo;Types}       |\b Block          | block     | Used to compare the result of function \p{Type}.
 * \alib{files::FInfo;Types}       |\b Character      | character | Used to compare the result of function \p{Type}.
 * \alib{files::FInfo;Types}       |\b Fifo           | fifo      | Used to compare the result of function \p{Type}.
 * \alib{files::FInfo;Types}       |\b Socket         | socket    | Used to compare the result of function \p{Type}.
 *
 *
 * <br>
 * ## Constant Constructor Functions:  ##
 * <br>
 * Return Type| Name        |Min. Abbreviation| Signature | Description |
 * -----------|-------------|-----------------|-----------|-------------|
 * Integer    |\b KiloBytes | KB              | int       | Returns the given number multiplied with 2^10.
 * Integer    |\b MegaBytes | MB              | int       | Returns the given number multiplied with 2^20.
 * Integer    |\b GigaBytes | GB              | int       | Returns the given number multiplied with 2^30.
 * Integer    |\b TeraBytes | TB              | int       | Returns the given number multiplied with 2^40.
 * Integer    |\b PetaBytes | PB              | int       | Returns the given number multiplied with 2^50.
 * Integer    |\b ExaBytes  | EB              | int       | Returns the given number multiplied with 2^60.
 *
 * <br>
 * ## Functions:  ##
 * <br>
 *
 * Return Type                        | Name             | Min. Abbreviation | Signature  | Description                                                                                                                           |
* ----------------------------------- | -----------      | ------------------| -----------| -------------                                                                                                                         |
* String                              | \b Name          | name              | ./.        | Returns the file name.
* \alib{files::FInfo;Types}           | \b Type          | ty                | ./.        | Returns the result of \alib{files::FInfo;Type}.
* Boolean                             | \b IsDirectory   | isdir             | ./.        | Returns the result of \alib{files::FInfo;IsDirectory}.
* Boolean                             | \b IsSymbolicLink| issl              | ./.        | Returns the result of \alib{files::FInfo;IsSymbolicLink}.
* Integer                             | \b Size          | size              | ./.        | Returns the result of \alib{files::FInfo;Size}.
* DateTime                            | \b Time          | time              | ./.        | Returns the result of \alib{files::FInfo;MTime}.
* DateTime                            | \b MTime         | mt                | ./.        | Returns the result of \alib{files::FInfo;MTime}.
* DateTime                            | \b CTime         | ct                | ./.        | Returns the result of \alib{files::FInfo;CTime}.
* DateTime                            | \b ATime         | at                | ./.        | Returns the result of \alib{files::FInfo;ATime}.
* \alib{files::FInfo;Permissions}     | \b Permissions   | perm              | ./.        | Returns the result of \alib{files::FInfo;Permissions}.
* \alib{files::FInfo;TOwnerAndGroupID}| \b Owner         | owner             | ./.        | Returns the result of \alib{files::FInfo;Owner}.
* \alib{files::FInfo;TOwnerAndGroupID}| \b Group         | group             | ./.        | Returns the result of \alib{files::FInfo;Group}.
* \alib{files::FInfo;TOwnerAndGroupID}| \b UserID        | uid               | ./.        | Returns the current user's ID (calls posix <b>getuid()</b>).
* \alib{files::FInfo;TOwnerAndGroupID}| \b GroupID       | gid               | ./.        | Returns the current user's group ID (calls posix <b>getgid()</b>).
*
*/
class FileExpressions
{
  protected:
    /** The internal compiler plug-in which adds file-related functions to the expression
     *  compiler as documented with the outer class.                                          */
    struct Plugin : public expressions::plugins::Calculus
    {
        /** Constructor
         * @param compiler The compiler that this plugin will be attached to.                 */
        Plugin( Compiler& compiler );
    };
 
  public:
    /** The expression scope used with file expressions. Contains an \b FTree cursor and
     *  the string of the path the file or folder is located in.                             */
    struct FexScope : public expressions::Scope
    {
        FTree::ConstCursor  Node;          ///< A node of a \alib{files;FTree}.
        String              ParentPath;    ///< The absolute path to the parent directory.
 
        /**
         * Constructor. Passes the formatter to the parent constructor.
         * @param formatter A reference to a \c std::shared_ptr holding a formatter.
         *                  Usually \alib{expressions;Compiler::CfgFormatter}.
         */
        FexScope( SPFormatter& formatter )
        : expressions::Scope(formatter)                                                           {}
 
    };
 
    /** Implementation of abstract class \alib{files;FFilter} which uses run-time
     *  compiled and evaluated expressions to determine inclusion of files or directories.
     *  Instances of this type can be created with outer classes' method
     *  \alib{files;FileExpressions::CreateFilter} and for example be attached to fields
     *  \alib{files::ScanParameters;FileFilter},
     *  \alib{files::ScanParameters;DirectoryFilterPreRecursion} and
     *  \alib{files::ScanParameters;DirectoryFilterPostRecursion} of class
     *  \b ScanParameters.                                                                       */
    class Filter  : public FFilter
    {
      protected:
        friend class FileExpressions;         ///< The outer class is our friend.
        FileExpressions&        fex;          ///< The scope used with this filter.
        FileExpressions::FexScope  scope;        ///< The scope used with this filter.
        SPExpression            expression;   ///< The compiled expression.
 
 
        /** Protected constructor. Compiles the given expression.
         *  To create an instance of this class, use
         *  \alib{files;FileExpressions::CreateFilter}.
         *  @param pFex              The expression compiler to use.
         *  @param expressionString The expression string.         */
        ALIB_API
        Filter( FileExpressions& pFex, const String& expressionString );
 
 
      public:
        /** The filter method.
         * @param node        The node in the file-tree to examine.
         * @param parentPath  The absolute path to the parent directory that the file resides in.
         * @return The result determines, whether the given file or directory has passed the filter
         *         or not. Consequently, \c true means "passed" and \c false means
         *         "filtered out".                                                            */
        virtual bool Includes(const FTree::ConstCursor& node, const String& parentPath) override
        {
            scope.Node       = node;
            scope.ParentPath = parentPath;
            return expression->Evaluate( scope ).Unbox<bool>();
        }
    }; // class Filter
 
 
    Compiler  compiler;    ///< The expression compiler.
    Plugin    plugin;      ///< The file expression Plugin
 
 
    /** Default constructor. */
    ALIB_API
    FileExpressions();
 
    /** Creates a file filter using the expression compiler of this instance.
     *  @param expressionString The expression string to filter files and directories.
     *  @return A shared pointer to the dynamically allocated filter object.           */
    ALIB_API
    SPFileFilter    CreateFilter( const String& expressionString );
 
}; // class FileExpressions
 
} // namespace alib[::files]
 
 
/// Type alias in namespace \b alib.
using     FileExpressions=   files::FileExpressions;
 
}  // namespace [alib]
 
#endif // HPP_ALIB_FILES_FILEEXPRESSIONS