bdls_tempdirectoryguard.h

Go to the documentation of this file.

/// @file bdls_tempdirectoryguard.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bdls_tempdirectoryguard.h                                          -*-C++-*-
#ifndef INCLUDED_BDLS_TEMPDIRECTORYGUARD
#define INCLUDED_BDLS_TEMPDIRECTORYGUARD
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bdls_tempdirectoryguard bdls_tempdirectoryguard
/// @brief  Provide a scoped guard that creates a unique temporary directory.
/// @addtogroup bdl
/// @{
/// @addtogroup bdls
/// @{
/// @addtogroup bdls_tempdirectoryguard
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bdls_tempdirectoryguard-purpose"> Purpose</a>
/// * <a href="#bdls_tempdirectoryguard-classes"> Classes </a>
/// * <a href="#bdls_tempdirectoryguard-description"> Description </a>
///   * <a href="#bdls_tempdirectoryguard-usage"> Usage </a>
///     * <a href="#bdls_tempdirectoryguard-example-1-basic-usage"> Example 1: Basic Usage </a>
///
/// # Purpose {#bdls_tempdirectoryguard-purpose}
/// Provide a scoped guard that creates a unique temporary directory.
///
/// # Classes {#bdls_tempdirectoryguard-classes}
///
/// -  bdls::TempDirectoryGuard: guard for creating and removing a temp directory
///
/// # Description {#bdls_tempdirectoryguard-description}
/// This component provides a scoped guard
/// `bdls::TempDirectoryGuard`, intended primarily for testing, which creates a
/// uniquely named temporary directory.  If possible, this is located in the
/// system temp directory, otherwise it is created within the current working
/// directory.
///
/// As this class is primarily intended for testing, any failures to build the
/// directory name or create the temporary directory will be fatal.
///
/// ## Usage {#bdls_tempdirectoryguard-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Basic Usage {#bdls_tempdirectoryguard-example-1-basic-usage}
///
///
/// Suppose an algorithm requires writing data to a temporary file on disk
/// during processing:
/// @code
/// /// Do "algorithm" using the specified `testFileName` for intermidiate state
/// /// storage.
/// void testAlgorithm(const bsl::string &testFileName);
/// @endcode
/// A function looking to use this algorithm can obtain a directory in which to
/// put this file, guaranteed to not be used by other processes and to be
/// cleaned up on normal exit, using an instance of `bdls::TempDirectoryGuard`:
/// @code
/// void usesTestAlgorithm()
/// {
///     bdls::TempDirectoryGuard tempDirGuard("my_algo_");
///
///     bsl::string tmpFileName(tempDirGuard.getTempDirName());
///     bdls::PathUtil::appendRaw(&tmpFileName,"algorithm.scratch");
///
///     testAlgorithm(tmpFileName);
/// }
/// @endcode
/// After exiting, the scratch file (named "algorithm.scratch") and the
/// temporary directory (with an unspecified name starting with "my_algo_"),
/// possibly in the system temp directory or the current working directory, will
/// be removed.
/// @}
/** @} */
/** @} */
 
/** @addtogroup bdl
 * @{
 */
/** @addtogroup bdls
 * @{
 */
/** @addtogroup bdls_tempdirectoryguard
 * @{
 */
 
#include <bslma_allocator.h>
#include <bslma_usesbslmaallocator.h>
 
#include <bslmf_nestedtraitdeclaration.h>
 
#include <bsl_string.h>
 
 
namespace bdls {
 
                              // ========================
                              // class TempDirectoryGuard
                              // ========================
 
/// This class implements a scoped temporary directory guard.  The guard tries
/// to create a temporary directory in the system-wide temp directory and falls
/// back to the current directory.
///
/// See @ref bdls_tempdirectoryguard 
class TempDirectoryGuard {
 
    // DATA
    bsl::string d_dirName;      // path to the created directory
 
  private:
    // NOT IMPLEMENTED
    TempDirectoryGuard(const TempDirectoryGuard&);
    TempDirectoryGuard& operator=(const TempDirectoryGuard&);
 
  public:
    // TRAITS
    BSLMF_NESTED_TRAIT_DECLARATION(TempDirectoryGuard,
                                   bslma::UsesBslmaAllocator);
 
    // CREATORS
 
    /// Create temporary directory with the specified `prefix` in the
    /// system-wide temp or current directory.  Optionally specify a
    /// `basicAllocator` used to supply memory.  If `basicAllocator` is 0, the
    /// currently installed default allocator is used.
    explicit TempDirectoryGuard(const bsl::string_view&  prefix,
                                bslma::Allocator        *basicAllocator = 0);
 
    /// Destroy this object and remove the temporary directory (recursively)
    /// created at construction.
    ~TempDirectoryGuard();
 
    // MANIPULATORS
 
    /// Remove the created temporary directory from management so that, upon
    /// this guards destruction, the created directory is not removed.  Calling
    /// `release` on a guard that has previously been released has no effect.
    void release();
 
    // ACCESSORS
 
    /// Return a `const` reference to the name of the created temporary
    /// directory, or an empty string if the directory was released
    /// from management.
    const bsl::string& getTempDirName() const;
 
};
 
}  // close package namespace
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2019 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 ----------------------------------
 
/** @} */
/** @} */
/** @} */