config.hpp

Go to the documentation of this file.

/// \file jsonv/config.hpp
///
/// Copyright (c) 2014-2020 by Travis Gockel. All rights reserved.
///
/// This program is free software: you can redistribute it and/or modify it under the terms of the Apache License
/// as published by the Apache Software Foundation, either version 2 of the License, or (at your option) any later
/// version.
///
/// \author Travis Gockel (travis@gockelhut.com)
#pragma once
 
/// \addtogroup Configuration
/// \{
 
/// \def JSONV_USER_CONFIG
/// A user-defined configuration file to be included before all other JSON Voorhees content.
#ifdef JSONV_USER_CONFIG
#   include JSONV_USER_CONFIG
#endif
 
/// \def JSONV_VERSION_MAJOR
/// The major version of JSON Voorhees these headers belong to.
#define JSONV_VERSION_MAJOR 2
 
/// \def JSONV_VERSION_MINOR
/// The minor version of JSON Voorhees these headers belong to.
#define JSONV_VERSION_MINOR 0
 
/// \def JSONV_VERSION_PATCH
/// The patch version of JSON Voorhees these headers belong to.
#define JSONV_VERSION_PATCH 0
 
/// \def JSONV_VERSION_PRERELEASE
/// The pre-release of JSON Voorhees these headers belong to, as a string literal: `"rc.1"` for 2.0.0-rc.1 and `""`
/// for a release. It is a SemVer pre-release written without the `-` which joins it to the version, and the build
/// accepts only dot-separated letters and digits.
///
/// A pre-release has the same three numbers, and so the same \c JSONV_VERSION, as the release it leads up to: a check
/// such as `#if JSONV_VERSION >= 2000000` holds for the release candidates of 2.0.0 as well as for 2.0.0 itself. The
/// preprocessor cannot look inside a string, but `std::string_view(JSONV_VERSION_PRERELEASE).empty()` is a constant
/// expression which is \c true for a release.
#define JSONV_VERSION_PRERELEASE "rc.1"
 
/// \def JSONV_VERSION
/// The version of JSON Voorhees these headers belong to as a single number,
/// `JSONV_VERSION_MAJOR * 1000000 + JSONV_VERSION_MINOR * 1000 + JSONV_VERSION_PATCH`, so a version check can be
/// written as `#if JSONV_VERSION >= 2000000`. It does not carry \c JSONV_VERSION_PRERELEASE.
#define JSONV_VERSION (JSONV_VERSION_MAJOR * 1000000 + JSONV_VERSION_MINOR * 1000 + JSONV_VERSION_PATCH)
 
/// \def JSONV_DEBUG
/// \brief Was JSON Voorhees compiled in debug mode?
/// This value must be the same between when the SO was built and when you are compiling. In general, this is not useful
/// outside of library maintainers.
///
/// \warning
/// Keep in mind this value is \e always defined. Use `#if JSONV_DEBUG`, \e not `#ifdef JSONV_DEBUG`.
#ifndef JSONV_DEBUG
#   define JSONV_DEBUG 0
#endif
 
/// \def JSONV_SO
/// \brief Are you using shared objects (DLLs in Windows)?
#ifndef JSONV_SO
#   define JSONV_SO 1
#endif
 
/// \def JSONV_COMPILING
/// \brief Is JSON Voorhees currently compiling?
/// You do not want to set this by hand. It is set by the build system when the library is compiled.
#ifndef JSONV_COMPILING
#   ifdef jsonv_EXPORTS
#      define JSONV_COMPILING 1
#   else
#      define JSONV_COMPILING 0
#   endif
#endif
 
/// \def JSONV_EXPORT
/// If using shared objects, this class or function should be exported.
///
/// \def JSONV_IMPORT
/// If using shared objects, this class or function should be imported.
///
/// \def JSONV_HIDDEN
/// This symbol is only visible within the same shared object in which the translation unit will end up. Symbols which
/// are "hidden" will \e not be put into the global offset table, which means code can be more optimal when it involves
/// hidden symbols at the cost that nothing outside of the SO can access it.
#if JSONV_SO
#   if defined(__GNUC__)
#       define JSONV_EXPORT          __attribute__((visibility("default")))
#       define JSONV_IMPORT
#       define JSONV_HIDDEN          __attribute__((visibility("hidden")))
#   elif defined(_MSC_VER)
#       if defined(_LIB)
#           define JSONV_EXPORT
#           define JSONV_IMPORT
#           define JSONV_HIDDEN
#       else
#           define JSONV_EXPORT      __declspec(dllexport)
#           define JSONV_IMPORT      __declspec(dllimport)
#           define JSONV_HIDDEN
#       endif
#   else
#       error "Unknown shared object semantics for this compiler."
#   endif
#else
#   define JSONV_EXPORT
#   define JSONV_IMPORT
#   define JSONV_HIDDEN
#endif
 
/// \def JSONV_PUBLIC
/// \brief This function or class is part of the public API for JSON Voorhees.
/// If you are including JsonVoorhees for another library, this will have import semantics (\c JSONV_IMPORT); if you are
/// building JsonVoorhees, this will have export semantics (\c JSONV_EXPORT).
///
/// \def JSONV_LOCAL
/// \brief This function or class is internal-use only.
/// \see JSONV_HIDDEN
#if JSONV_COMPILING
#   define JSONV_PUBLIC JSONV_EXPORT
#   define JSONV_LOCAL  JSONV_HIDDEN
#else
#   define JSONV_PUBLIC JSONV_IMPORT
#   define JSONV_LOCAL  JSONV_HIDDEN
#endif
 
/// \def JSONV_UNUSED
/// \brief Note that you know the variable is unused, but make the compiler stop complaining about it.
#ifndef JSONV_UNUSED
#   define JSONV_UNUSED [[maybe_unused]]
#endif
 
/// \def JSONV_NODISCARD
/// \brief Warn if the caller discards the result of this function.
/// This decorates the side-effect-free parts of the API, where dropping the result means the call did nothing at all.
///
/// The guard checks \c JSONV_DOXYGEN as well as the usual \c ifndef because \c config/Doxyfile predefines this macro
/// as empty to keep it out of the rendered signatures. That also hides this \c define from Doxygen, which then warns
/// about documentation for a macro it never saw; re-entering the block for Doxygen alone keeps the two consistent. No
/// compiler defines \c JSONV_DOXYGEN, so everywhere else this is exactly the \c ifndef its siblings use.
#if defined(JSONV_DOXYGEN) || !defined(JSONV_NODISCARD)
#   define JSONV_NODISCARD [[nodiscard]]
#endif
 
/// \def JSONV_NO_RETURN
/// \brief Mark that a given function will never return control to the caller, either by exiting or throwing an
/// exception.
#ifndef JSONV_NO_RETURN
#   define JSONV_NO_RETURN [[noreturn]]
#endif
 
/// \def JSONV_INTEGER_ALTERNATES_LIST
/// \brief An item list of types to also consider as an integer.
/// This mostly exists to help resolve the C-induced type ambiguity for the literal \c 0. It most prefers to be an
/// \c int, but might also become a \c long or a pointer type.
#ifndef JSONV_INTEGER_ALTERNATES_LIST
#   define JSONV_INTEGER_ALTERNATES_LIST(item) \
        item(int)                              \
        item(unsigned int)                     \
        item(unsigned long)                    \
        item(unsigned long long)
#endif
 
/// \}