ball_patternutil.h

Go to the documentation of this file.

/// @file ball_patternutil.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// ball_patternutil.h                                                 -*-C++-*-
#ifndef INCLUDED_BALL_PATTERNUTIL
#define INCLUDED_BALL_PATTERNUTIL
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup ball_patternutil ball_patternutil
/// @brief  Provide a utility class for string pattern matching.
/// @addtogroup bal
/// @{
/// @addtogroup ball
/// @{
/// @addtogroup ball_patternutil
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#ball_patternutil-purpose"> Purpose</a>
/// * <a href="#ball_patternutil-classes"> Classes </a>
/// * <a href="#ball_patternutil-description"> Description </a>
///   * <a href="#ball_patternutil-usage"> Usage </a>
///     * <a href="#ball_patternutil-example-1-basic-usage"> Example 1: Basic Usage </a>
///
/// # Purpose {#ball_patternutil-purpose}
/// Provide a utility class for string pattern matching.
///
/// # Classes {#ball_patternutil-classes}
///
/// -  ball::PatternUtil: utility class for string pattern matching
///
/// # Description {#ball_patternutil-description}
/// This component defines a namespace, `ball::PatternUtil`, that
/// provides utility functions for matching input strings to a given pattern
/// based on wild-card and simple escape sequences.
///
/// This component participates in the implementation of "Rule-Based Logging".
/// For more information on how to use that feature, please see the package
/// level documentation and usage examples for "Rule-Based Logging".
///
/// ## Usage {#ball_patternutil-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Basic Usage {#ball_patternutil-example-1-basic-usage}
///
///
/// The following code fragments illustrate basic usage of this component's
/// utility functions.
///
/// A string matches a pattern if they are identical:
/// @code
/// assert(ball::PatternUtil::isMatch("EQ",           "EQ"));
/// @endcode
/// A string matches a pattern containing an (unescaped) trailing `*` if that
/// pattern (without the trailing `*`) is a prefix of the string:
/// @code
/// assert(ball::PatternUtil::isMatch("EQ.MARKET",    "EQ*"));
/// assert(ball::PatternUtil::isMatch("EQ",           "EQ*"));
/// @endcode
/// An escaped `*` at the end loses its wild-card semantics and matches a single
/// `*`:
/// @code
/// assert(false == ball::PatternUtil::isMatch("EQ.MARKET", "EQ\\*"));
/// assert(ball::PatternUtil::isMatch("EQ*",          "EQ\\*"));
/// @endcode
/// Escape sequences include '\\' and '\*' only and they can appear anywhere in
/// the pattern:
/// @code
/// assert(ball::PatternUtil::isMatch("\\EQ",         "\\\\EQ"));
/// assert(ball::PatternUtil::isMatch("E*Q",          "E\\*Q"));
/// @endcode
/// A pattern is invalid if it contains a non-trailing `*`, or any '\' that is
/// not followed by either '\' or `*`.  The `isValidPattern` function can be
/// used to determine whether or not a pattern is valid:
/// @code
/// assert(false == ball::PatternUtil::isValidPattern("E\\Q"));
/// assert(false == ball::PatternUtil::isValidPattern("E*Q"));
/// assert(true  == ball::PatternUtil::isValidPattern("E\\\\Q"));
/// assert(true  == ball::PatternUtil::isValidPattern("E\\*Q"));
/// @endcode
/// The `isMatch` function always returns `false` on an invalid pattern:
/// @code
/// assert(false == ball::PatternUtil::isMatch("E\\Q","E\\Q"));
/// assert(false == ball::PatternUtil::isMatch("E*Q", "E*Q"));
/// assert(false == ball::PatternUtil::isMatch("ETQ", "E*Q"));
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bal
 * @{
 */
/** @addtogroup ball
 * @{
 */
/** @addtogroup ball_patternutil
 * @{
 */
 
#include <balscm_version.h>
 
 
namespace ball {
 
                        // ==================
                        // struct PatternUtil
                        // ==================
 
/// This utility class provides functions relating to pattern matching for
/// strings.
///
/// See @ref ball_patternutil 
struct PatternUtil {
 
    // CLASS METHODS
 
    /// Return `true` if the specified `pattern` matches the specified
    /// `inputString`, and `false` if the pattern does not match or is
    /// invalid.  There are two types of escape sequences that are allowed
    /// in `pattern`.  (See the function-level documentation of
    /// `PatternUtil::isValidPattern` for the definition of invalid
    /// patterns.)  A '\*` escape sequence in `pattern' matches a single `*`
    /// in `inputString`.  A '\\' escape sequence in `pattern` matches a
    /// single '\' in `inputString`.  If `pattern` ends with an unescaped
    /// `*`, then `pattern` matches `inputString` if the string indicated by
    /// `pattern` (after escape sequence processing) with the final `*`
    /// removed is a prefix of `inputString`.  Otherwise `pattern` matches
    /// `inputString` only if the string indicated by `pattern` (after
    /// escape sequence processing) and `inputString` are the same.  
    /// 
    /// \pre The behavior is undefined   unless both `inputString` and `pattern` are
    /// null-terminated c-style strings.
    static bool isMatch(const char *inputString, const char *pattern);
 
    /// Return `true` if the specified `pattern` does not contain a '\' not
    /// followed by either '\' or `*`, or an unescaped `*` at locations other than at the end, and `false` otherwise.  
    /// 
    /// \note Note that   an
    /// unescaped `*` not at the end may someday be considered a valid
    /// pattern.
    static bool isValidPattern(const char *pattern);
};
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2015 Bloomberg Finance L.P.
//
// 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.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */