info.hpp

Go to the documentation of this file.

#ifndef LIBJMMCG_CORE_INFO_HPP
#define LIBJMMCG_CORE_INFO_HPP
 
/******************************************************************************
** Copyright © 2002 by J.M.McGuiness, coder@hussar.me.uk
**
** This library is free software; you can redistribute it and/or
** modify it under the terms of the GNU Lesser General Public
** License as published by the Free Software Foundation; either
** version 2.1 of the License, or (at your option) any later version.
**
** This library is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** Lesser General Public License for more details.
**
** You should have received a copy of the GNU Lesser General Public
** License along with this library; if not, write to the Free Software
** Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
 
#include "unicode_conversions.hpp"
 
#include <cassert>
#include <climits>
#include <functional>
#include <iterator>
#include <map>
#include <typeinfo>
#include <vector>
 
namespace jmmcg { namespace LIBJMMCG_VER_NAMESPACE {
 
   /// All of this stuff is for high-quality error reporting.
   /**
      You construct a file-scope revision object to contain and wrap the basic CVS, RCS, etc revision strings.
      Then when you throw an exception, it will take this revision object and dump it when "what()" is called on the exception to give you that file information to aid debugging run-time bug requests from clients of your code.
      You can add a function object, which takes argument objects to the exception to provide yet more information, like location in the file, function name, argument names and values, the type if the "this" object (handy in template expansions to know which template expansion has occurred if there are many different specialisations).
 
      \see revision
      \see function
      \see exception
   */
   namespace info {
      /// Attempt to include revision information for the file from which the exception was constructed.
      /**
         This should be added at source-file scope, although it does support header-file usage too.
         At source file-scope the macro JMMCG_REVISION_CONSTANT is provided to allow trivial use.
         In a header file the macro JMMCG_REVISION_HDR is provided to ease use.
 
         \see JMMCG_REVISION_CONSTANT
         \see JMMCG_REVISION_HDR
      */
      class revision {
      public:
         constexpr __stdcall revision(const tchar *r=_T(LIBJMMCG_VERSION_NUMBER), const char *f=__FILE__) noexcept(true)
         : rev(r), file(f) {
         }
         __stdcall revision(const revision &r) noexcept(true)
         : rev(r.rev), file(r.file) {
         }
 
         static constexpr std::size_t max_size() noexcept(true) {
            return 9+PATH_MAX+28+32+33+PATH_MAX+3;
         }
 
         /**
            \todo Implement using the advice given in "Standard C++ IOStreams and Locales" by A.Langer & K.Kreft, page 170.
         */
         friend inline tostream & __fastcall operator<<(tostream &o, const revision &ri) noexcept(false) {
            o<<_T("Revision: '")<<ri.rev<<_T("'.\n")
               _T("Local file name: '")<<StringToTString(ri.file)<<_T("'.\n");
            return o;
         }
 
      private:
         const tchar *rev;
         const char *file;
      };
 
      /// Attempt to include function-call information for the function from which the exception was constructed.
      /**
         Use of the macros JMMCG_FUNCTION (for no arguments) & JMMCG_FUNCTION1 (for one argument) make use of this object for constructing an exception easier.
 
         \see JMMCG_FUNCTION
         \see JMMCG_FUNCTION1
      */
      class function {
      public:
         /// Attempt to include argument information for the function from which the exception was constructed.
         class argument {
         public:
#if defined(_MSC_VER) && (_MSC_VER < 1300)
            // Crappy M$ compiler can't handle member-template functions.
            __stdcall argument(tstring &&n, tstring &&v) noexcept(false)
            : name(std::move(n)), value(std::move(v)) {
               assert(CheckVals());
            }
#else
            template<typename Arg_Val> __declspec(dllexport) argument(tstring &&n, const Arg_Val &v) noexcept(false)
            : name(std::move(n)), value(tostring(v)) {
               assert(CheckVals());
            }
#endif   // _MSC_VER
 
            static constexpr std::size_t max_size() noexcept(true) {
               return 8+PATH_MAX+10+PATH_MAX+4;
            }
 
            /**
               \todo Implement using the advice given in "Standard C++ IOStreams and Locales" by A.Langer & K.Kreft, page 170.
            */
            friend inline tostream & __fastcall operator<<(tostream &o, const argument &a) noexcept(false) {
               assert(a.CheckVals());
               o<<_T("\tName: '")<<a.name<<_T("', value: '")<<a.value<<_T("'.");
               return o;
            }
 
#ifdef DEBUG
            bool __fastcall CheckVals(void) const noexcept(true) {
               return !name.empty();
            }
#endif
 
         private:
            const tstring name;
            const tstring value;
         };
         typedef std::vector<argument> args_details_type;
         static inline constexpr std::size_t max_args=10;
 
         explicit NEVER_INLINE __stdcall function(const unsigned long l=__LINE__, const char *n=NULL, const std::type_info &th=typeid(void), const argument &a=argument(_T("void"),_T("nothing"))) noexcept(false)
         : line(l), name(n ? n : __PRETTY_FUNCTION__), this_type(th), args_details(1, argument(a)) {
            assert(CheckVals());
         }
 
         void NEVER_INLINE __fastcall add_arg(argument &&a) noexcept(false) {
            assert(CheckVals());
            args_details.emplace_back(std::move(a));
            assert(CheckVals());
         }
 
         template<class ...Args>
         void NEVER_INLINE __fastcall add_args(Args &&...a) noexcept(false) {
            assert(CheckVals());
            args_details.reserve(args_details.size()+sizeof...(a));
            (
               args_details.emplace_back(std::move(a)), ...
            );
            assert(CheckVals());
         }
 
         template<typename Arg_Val> void NEVER_INLINE __fastcall add_arg(tstring &&n, const Arg_Val &v) noexcept(false) {
            assert(CheckVals());
#if defined(_MSC_VER) && (_MSC_VER < 1300)
            // Crappy M$ compiler can't handle member-template functions.
            add_arg(argument(std::move(n),tostring(v)));
#else
            add_arg(argument(std::move(n),v));
#endif   // _MSC_VER
            assert(CheckVals());
         }
 
         static constexpr std::size_t max_size() noexcept(true) {
            return 15+PATH_MAX+3
               +19+PATH_MAX+3
               +39+std::numeric_limits<std::size_t>::digits10+1
               +(argument::max_size()+1)*max_args
               +13+std::numeric_limits<std::size_t>::digits10+3;
         }
 
         /**
            \todo Implement using the advice given in "Standard C++ IOStreams and Locales" by A.Langer & K.Kreft, page 170.
         */
         friend inline tostream & __fastcall operator<<(tostream &o, const function &fi) noexcept(false) {
            o<<_T("Function name: '")<<StringToTString(fi.name)<<_T("'.\n")
               _T("C++ RTTI context: '")<<fi.this_type.name()<<_T("'.\n")
               _T("Argument details, number of arguments: ")<<fi.args_details.size()<<_T("\n");
            assert(fi.CheckVals());
            std::copy(
               fi.args_details.begin(),
               fi.args_details.end(),
               std::ostream_iterator<args_details_type::value_type,tchar>(o,_T("\n"))
            );
            o<<_T("Line number: ")<<std::dec<<fi.line<<_T(".\n");
            return o;
         }
 
      private:
         const unsigned long line;
         const char *name;
         const std::type_info &this_type;
         args_details_type args_details;
 
#ifdef DEBUG
         bool __fastcall CheckVals(void) const noexcept(true) {
            assert(args_details.size()<max_args);
            for (auto const &i : args_details) {
               const bool trouble=i.CheckVals();
               if (!trouble) {
                  return false;
               }
            }
            return true;
         }
#endif
      };
   }
 
} }
 
/// Much as I despise macros, I despise adding error information more. (That's why I wrote these classes first - just to get it out of the way, so I can get on with more fun stuff...
/**
   So these take some of the tedium out of adding that boiler-plate error-information that may come in handy that once-in-a-blue-moon occasion I didn't bother to put it in, because one finds it just too tedious....)
 
   \see revision
*/
 
/// Handy for use in header files for constructing "libjmmcg::exception"s, but see that file for a more useful macro.
#define JMMCG_REVISION_HDR(_JMMCG_REVISION_HDR) jmmcg::LIBJMMCG_VER_NAMESPACE::info::revision((_JMMCG_REVISION_HDR),__FILE__)
 
/// Introduces the constant "__REV_INFO__" (c.f. __LINE__, etc) into a private namespace for that compilation unit.
/**
   An easier way of getting this boiler-plate revision information into your source files.
   Handy for source files.
 
   \see revision
*/
#define JMMCG_REVISION_CONSTANT(_JMMCG_REVISION_HDR)
   namespace {
      [[maybe_unused]] const jmmcg::LIBJMMCG_VER_NAMESPACE::info::revision __REV_INFO__((_JMMCG_REVISION_HDR),__FILE__);
   }
 
/// Construction a function error-information object with no arguments.
/**
   Eases construction of this object in a source or header file.
 
   \see function
*/
#  define JMMCG_FUNCTION(JMMCG_FUNCTION_TYPE_) jmmcg::LIBJMMCG_VER_NAMESPACE::info::function(__LINE__,__PRETTY_FUNCTION__,typeid(JMMCG_FUNCTION_TYPE_))
 
/// Construction a function error-information object with one argument.
/**
   Eases construction of this object in a source or header file.
 
   \see function
*/
#  define JMMCG_FUNCTION1(JMMCG_FUNCTION_TYPE_,JMMCG_FUNCTION_ARGUMENTS_) jmmcg::LIBJMMCG_VER_NAMESPACE::info::function(__LINE__,__PRETTY_FUNCTION__,typeid(JMMCG_FUNCTION_TYPE_),(JMMCG_FUNCTION_ARGUMENTS_))
 
#endif