// file      : build2/config/utility -*- C++ -*-
// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
// license   : MIT; see accompanying LICENSE file

#ifndef BUILD2_CONFIG_UTILITY
#define BUILD2_CONFIG_UTILITY

#include <build2/types>
#include <build2/utility>

#include <build2/variable>
#include <build2/diagnostics>

namespace build2
{
  class scope;

  namespace config
  {
    // Set, if necessary, a required config.* variable.
    //
    // If override is true and the variable doesn't come from this root scope
    // or from the command line (i.e., it is inherited from the amalgamtion),
    // then its value is "overridden" to the default value on this root scope.
    // See save_variable() for more information on save_flags.
    //
    // Return the reference to the value as well as the indication of whether
    // the value is "new", that is, it was set to the default value (inherited
    // or not, including overrides). We also treat command line overrides
    // (inherited or not) as new. This flag is usually used to test that the
    // new value is valid, print report, etc.
    //
    // Note also that if save_flags has save_commented, then a default value
    // is never considered "new" since for such variables absence of a value
    // means the default value.
    //
    template <typename T>
    pair<reference_wrapper<const value>, bool>
    required (scope& root,
              const variable&,
              const T& default_value,
              bool override = false,
              uint64_t save_flags = 0);

    template <typename T>
    inline pair<reference_wrapper<const value>, bool>
    required (scope& root,
              const string& name,
              const T& default_value,
              bool override = false,
              uint64_t save_flags = 0)
    {
      return required (
        root, var_pool[name], default_value, override, save_flags);
    }

    inline pair<reference_wrapper<const value>, bool>
    required (scope& root,
              const string& name,
              const char* default_value,
              bool override = false,
              uint64_t save_flags = 0)
    {
      return required (
        root, name, string (default_value), override, save_flags);
    }

    // As above, but leave the unspecified value as undefined (and return
    // NULL pointer) rather than setting it to the default value.
    //
    // This can be useful when we don't have a default value but may figure
    // out some fallback. See config.bin.target for an example.
    //
    pair<const value*, bool>
    omitted (scope& root, const variable&);

    inline pair<const value*, bool>
    omitted (scope& root, const string& name)
    {
      return omitted (root, var_pool[name]);
    }

    // Set, if necessary, an optional config.* variable. In particular,
    // an unspecified variable is set to NULL which is used to distinguish
    // between the "configured as unspecified" and "not yet configured"
    // cases.
    //
    // Return the value, which can be NULL.
    //
    const value&
    optional (scope& root, const variable&);

    inline const value&
    optional (scope& root, const string& var)
    {
      return optional (root, var_pool[var]);
    }

    // Check whether there are any variables specified from the config
    // namespace. The idea is that we can check if there are any, say,
    // config.install.* values. If there are none, then we can assume
    // this functionality is not (yet) used and omit writing a whole
    // bunch of NULL config.install.* values to the config.build file.
    // We call it omitted/delayed configuration.
    //
    // Note that this function detects and ignores the special
    // config.*.configured variable which may be used by a module to
    // "remember" that it is unconfigured (e.g., in order to avoid re-
    // running the tests, etc).
    //
    bool
    specified (scope& root, const string& ns);

    // Check if there is a false config.*.configured value. This mechanism can
    // be used to "remember" that the module is left unconfigured in order to
    // avoid re-running the tests, etc.
    //
    bool
    unconfigured (scope& root, const string& ns);

    // Set the config.*.configured value. Note that you only need to set it to
    // false. It will be automatically ignored if there are any other config.*
    // values for this module. Return true if this sets a new value.
    //
    bool
    unconfigured (scope& root, const string& ns, bool);

    // Enter the variable so that it is saved during configuration. See
    // config::module for details.
    //
    const uint64_t save_commented = 0x01; // Save default value as commented.

    void
    save_variable (scope& root, const variable&, uint64_t flags = 0);

    // Establish module order/priority. See config::module for details.
    //
    void
    save_module (scope& root, const char* name, int prio = 0);
  }
}

#include <build2/config/utility.txx>

#endif // BUILD2_CONFIG_UTILITY