fileexpressions.inl

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_files of the \aliblong.
///
/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software License".
//==================================================================================================
ALIB_EXPORT 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 multithreaded compilation of expressions 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 then do not need to 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 to be matched case-insensitive.
/// Furthermore, the matchable 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 type is auto-cast to built-in expression type \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 Date          | timestamp         | ./.        | Returns the result of \alib{files::FInfo;MDate}.
/// DateTime                            | \b MDate         | md                | ./.        | Returns the result of \alib{files::FInfo;MDate}.
/// DateTime                            | \b BDate         | bd                | ./.        | Returns the result of \alib{files::FInfo;BDate}.
/// DateTime                            | \b CDate         | cd                | ./.        | Returns the result of \alib{files::FInfo;CDate}.
/// DateTime                            | \b ATime         | ad                | ./.        | Returns the result of \alib{files::FInfo;ADate}.
/// \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>).
///
/// \par Availability
///   This class is available only if the module \alib_expressions is included in the \alibbuild.
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:
    class Filter;
 
    /// The expression scope used with file expressions. Contains a \b FTree cursor and
    /// the string of the path that the file or folder is located in.
    struct FexScope : expressions::Scope
    {
        friend class Filter;              ///<The filter class needs casting this class to its base.
        File                        Node; ///<A node of a \alib{files;FTree}.
        system::PathString    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 the 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.
    ///
    /// \par Availability
    ///   This class is available only if the module \alib_expressions is included in the \alibbuild.
    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.
        Expression                 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_DLL
        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 File& node, const system::PathString& 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_DLL
    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_DLL
    SPFileFilter    CreateFilter( const String& expressionString );
 
}; // class FileExpressions
 
} // namespace alib[::files]
 
 
/// Type alias in namespace \b alib.
using     FileExpressions=   files::FileExpressions;
 
}  // namespace [alib]