// bdlb_printadapter.h                                                -*-C++-*-
#ifndef INCLUDED_BDLB_PRINTADAPTER
#define INCLUDED_BDLB_PRINTADAPTER

#include <bsls_ident.h>
BSLS_IDENT("$Id: $")

//@PURPOSE: Provide object for streaming objects using `bdlb::PrintMethods`.
//
//@CLASSES:
//  bdlb::PrintAdapter: class for streaming objects using `bdlb::PrintMethods`.
//  bdlb::PrintAdapterUtil: utility for constructing `bdlb::PrintAdapter`.
//
//@DESCRIPTION: This component provides a template `class` that will enable any
// object that can be streamed using `bdlb::PrintMethods` to be streamed via
// `<<`.
//
// Through using this `class`, one can stream an object using `operator<<` and
// at the same time specify `level` and `spacesPerLevel` arguments to
// appropriately indent and format the output.
//
///Usage
///-----
// This section illustrates intended use of this component.
//
///Example 1: Use in C++03
///- - - - - - - - - - - -
// Suppose we have a few `bdlb::IdentSpan` objects that we want to print, only
// we want to stream them with `operator<<` and we want to specify non-default
// values of `level` and `spacesPerLevel` to their streaming.
// ```
// const bdlb::IndexSpan a(3, 7), b(241, 22), c(23, 17);
// ```
// First, we create a typedef of 'PrintAdapter<IdentSpan>' to use:
// ```
// typedef bdlb::PrintAdapter<bdlb::IndexSpan> PAIS;
// ```
// Then, we create a line of dashes:
// ```
// const char * const line = "------------------------------------"
//                           "------------------------------------\n";
// ```
// Now, we use the `typedef` to construct temporary `PrintAdapter` objects to
// stream our `IndexSpan` objects:
// ```
// cout << "    a: " << line << PAIS(&a, 2, 2)
//      << "    b: " << line << PAIS(&b, 3, 2)
//      << "    c: " << line << PAIS(&c, 4, 2);
// ```
// Finally, we see the output:
// ```
//  a: ------------------------------------------------------------------------
//  [
//    position = 3
//    length = 7
//  ]
//  b: ------------------------------------------------------------------------
//    [
//      position = 241
//      length = 22
//    ]
//  c: ------------------------------------------------------------------------
//      [
//        position = 23
//        length = 17
//      ]
// ```
//
///Example 2: Use of `PrintAdapterUtil::makeAdapter`
///- - - - - - - - - - - - - - - - - - - - - - - - -
// Suppose we have a few `bdlb::IdentSpan` objects that we want to print, only
// we want to stream them with `operator<<` and we want to specify
// non-default values of `level` and `spacesPerLevel` to their streaming.
// ```
// const bdlb::IndexSpan a(3, 7), b(241, 22), c(23, 17);
// ```
// First, we make a typedef to the namespace `struct`:
// ```
// typedef bdlb::PrintAdapterUtil Util;
// ```
// Then, we create a line of dashes:
// ```
// const char * const line = "------------------------------------"
//                           "------------------------------------\n";
// ```
// Now, we call the static function `PrintAdapterUtil::makeAdapter` on the
// `IndexSpan` objects to stream which will return streamable `PrintAdapter`
// objects:
// ```
// cout << "    a: " << line << Util::makeAdapter(a, 2, 2)
//      << "    b: " << line << Util::makeAdapter(b, 3, 2)
//      << "    c: " << line << Util::makeAdapter(c, 4, 2);
// ```
// Finally, we see the output:
// ```
//  a: ------------------------------------------------------------------------
//  [
//    position = 3
//    length = 7
//  ]
//  b: ------------------------------------------------------------------------
//    [
//      position = 241
//      length = 22
//    ]
//  c: ------------------------------------------------------------------------
//      [
//        position = 23
//        length = 17
//      ]
// ```
//
///Example 3: Use in C++17 With CTAD
///- - - - - - - - - - - - - - - - -
// Suppose you have a few `bdlb::IdentSpan` objects that you want to print,
// only you want to stream them with `operator<<` and you want to specify
// non-default values of `level` and `spacesPerLevel` to their streaming.
// ```
// const bdlb::IndexSpan a(3, 7), b(241, 22), c(23, 17);
// ```
// First, we create a line of dashes:
// ```
// const char * const line = "------------------------------------"
//                           "------------------------------------\n";
// ```
// Now, you call the constructor `PrintAdapter` on the `IndexSpan` objects to
// stream and CTAD will create the right template specification:
// ```
// cout << "    a: " << line << bdlb::PrintAdapter(&a, 2, 2)
//      << "    b: " << line << bdlb::PrintAdapter(&b, 3, 2)
//      << "    c: " << line << bdlb::PrintAdapter(&c, 4, 2);
// ```
// Finally, we see the output:
// ```
//  a: ------------------------------------------------------------------------
//  [
//    position = 3
//    length = 7
//  ]
//  b: ------------------------------------------------------------------------
//    [
//      position = 241
//      length = 22
//    ]
//  c: ------------------------------------------------------------------------
//      [
//        position = 23
//        length = 17
//      ]
// ```

#include <bdlscm_version.h>

#include <bdlb_printmethods.h>

#include <bsl_ostream.h>

namespace BloombergLP {
namespace bdlb {

                              // ==================
                              // class PrintAdapter
                              // ==================

/// This `class` provides an object that may be streamed with `operator<<`
/// to give full control of the indentation format of the streaming.
template <class TYPE>
class PrintAdapter {

    // DATA
    const TYPE *d_object_p;
    int         d_level;
    int         d_spacesPerLevel;

  public:
    // CREATORS

    // Create a print adapter object bound to the specified `object`, and
    // with the optionally specified `level` and `spacesPerLevel`
    // attributes, to be used when the `PrintAdapter` object is streamed.
    // Unless `level` is specified, a value of 0 is used, unless
    // `spacesPerLevel` is specified, a value of 4 is used.
    explicit
    PrintAdapter(const TYPE *object,
                 int         level          = 0,
                 int         spacesPerLevel = 4);

    //! PrintAdapter(const PrintAdapter&) = default;

    // MANIPULATORS

    //! PrintAdapter& operator=(const PrintAdapter&) = default;

    // ACCESSORS

    /// Return the `level` attribute.
    int level() const;

    /// Return a reference to the object referred to by this print adapter.
    const TYPE& object() const;

    /// Return the `spacesPerLevel` attribute.
    int spacesPerLevel() const;
};

                            // ======================
                            // class PrintAdapterUtil
                            // ======================

// This `struct` provides a namespace for a function template that
// facilitates the construction of a `PrintAdapter` without having to
// explicitly specify template arguments in C++03.  Note that in C++17 and
// later, CTAD may be used instead of this `struct` to call the
// `PrintAdapter` constructor without having to explicitly specify the
// template argument.
struct PrintAdapterUtil {

    // CLASS METHOD

    /// Create and return a `PrintAdapter` object, passing the constructor
    /// the specified `object`, `level`, and `spacesPerLevel`.
    template <class TYPE>
    static
    PrintAdapter<TYPE> makeAdapter(const TYPE& object,
                                   int         level          = 0,
                                   int         spacesPerLevel = 4);
};

// FREE OPERATORS

/// Write the value of the specified `object` to the specified output
/// `stream` and return a non-`const` reference to `stream`.  If `stream` is
/// not valid on entry, this operation has no effect.  Note that this
/// human-readable format is not fully specified and can change without
/// notice.
template <class TYPE>
bsl::ostream& operator<<(bsl::ostream&             stream,
                         const PrintAdapter<TYPE>& adapter);

// ============================================================================
//                         INLINE FUNCTION DEFINITIONS
// ============================================================================

                              // ------------
                              // PrintAdapter
                              // ------------

// CREATORS
template <class TYPE>
inline
PrintAdapter<TYPE>::PrintAdapter(const TYPE *object,
                                 int         level,
                                 int         spacesPerLevel)
: d_object_p(object)
, d_level(level)
, d_spacesPerLevel(spacesPerLevel)
{}

// ACCESSORS
template <class TYPE>
inline
int PrintAdapter<TYPE>::level() const
{
    return d_level;
}

template <class TYPE>
inline
const TYPE& PrintAdapter<TYPE>::object() const
{
    return *d_object_p;
}

template <class TYPE>
inline
int PrintAdapter<TYPE>::spacesPerLevel() const
{
    return d_spacesPerLevel;
}

// FREE OPERATORS
template <class TYPE>
inline
bsl::ostream& operator<<(bsl::ostream&             stream,
                         const PrintAdapter<TYPE>& adapter)
    // Format this object to the specified output 'stream' at the (absolute
    // value of) the optionally specified indentation 'level' and return a
    // reference to 'stream'.  If 'stream' is not valid on entry, this
    // operation has no effect.
{
    return bdlb::PrintMethods::print(stream,
                                     adapter.object(),
                                     adapter.level(),
                                     adapter.spacesPerLevel());
}

                            // ----------------
                            // PrintAdapterUtil
                            // ----------------

// CLASS METHOD
template <class TYPE>
inline
PrintAdapter<TYPE> PrintAdapterUtil::makeAdapter(const TYPE& object,
                                                 int         level,
                                                 int         spacesPerLevel)
{
    return PrintAdapter<TYPE>(&object, level, spacesPerLevel);
}

}  // close package namespace
}  // close enterprise namespace

#endif

// ----------------------------------------------------------------------------
// Copyright 2022 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 ----------------------------------
