option_info.cpp

Go to the documentation of this file.

// Copyright (c) 2006-2025  Made to Order Software Corp.  All Rights Reserved
//
// https://snapwebsites.org/project/advgetopt
// contact@m2osw.com
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 2 of the License, or
// (at your option) any later version.
//
// This program 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 General Public License for more details.
//
// You should have received a copy of the GNU General Public License along
// with this program; if not, write to the Free Software Foundation, Inc.,
// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
 
// self
//
#include    "advgetopt/option_info.h"
 
#include    "advgetopt/exception.h"
#include    "advgetopt/validator_double.h"
#include    "advgetopt/validator_integer.h"
 
 
// cppthread
//
#include    <cppthread/guard.h>
#include    <cppthread/log.h>
#include    <cppthread/mutex.h>
 
 
// snapdev
//
#include    <snapdev/not_used.h>
#include    <snapdev/tokenize_string.h>
 
 
// libutf8
//
#include    <libutf8/libutf8.h>
#include    <libutf8/iterator.h>
 
 
// last include
//
#include    <snapdev/poison.h>
 
 
 
namespace advgetopt
{
 
 
namespace
{
 
 
bool g_trace_sources = false;
 
 
std::string g_configuration_filename = std::string();
 
 
 
} // no name namespace
 
 
 
// from utils.cpp
//
// (it's here because we do not want to make cppthread public in
// out header files--we could have an advgetopt_private.h, though)
//
cppthread::mutex &  get_global_mutex();
 
 
 
 
short_name_t string_to_short_name(std::string const & name)
{
    if(!name.empty())
    {
        libutf8::utf8_iterator u8(name);
        short_name_t const short_name(*u8++);
        if(u8 == name.end())
        {
            return short_name;
        }
    }
 
    return NO_SHORT_NAME;
}
 
 
std::string short_name_to_string(short_name_t short_name)
{
    if(short_name == NO_SHORT_NAME)
    {
        return std::string();
    }
    return libutf8::to_u8string(short_name);
}
 
 
option_info::option_info(std::string const & name, short_name_t short_name)
    : f_name(option_with_dashes(name))
    , f_short_name(short_name)
{
    if(f_name.empty())
    {
        if(short_name != NO_SHORT_NAME)
        {
            throw getopt_logic_error(
                          "option_info::option_info(): all options must at least have a long name (short name: '"
                        + libutf8::to_u8string(short_name)
                        + "'.)");
        }
        throw getopt_logic_error(
                      "option_info::option_info(): all options must at least have a long name.");
    }
 
    if(f_name == "--")
    {
        if(short_name != NO_SHORT_NAME)
        {
            throw getopt_logic_error(
                          "option_info::option_info(): the default parameter \"--\" cannot include a short name ('"
                        + libutf8::to_u8string(short_name)
                        + "'.)");
        }
 
        add_flag(GETOPT_FLAG_DEFAULT_OPTION);
    }
    else
    {
        if(f_name[0] == '-')
        {
            throw getopt_logic_error(
                          "option_info::option_info(): an option cannot start with a dash (-), \""
                        + f_name
                        + "\" is not valid.");
        }
 
        if(short_name == '-')
        {
            throw getopt_logic_error(
                          "option_info::option_info(): the short name of an option cannot be the dash (-).");
        }
    }
}
 
 
std::string const & option_info::get_name() const
{
    return f_name;
}
 
 
void option_info::set_short_name(short_name_t short_name)
{
    f_short_name = short_name;
}
 
 
short_name_t option_info::get_short_name() const
{
    return f_short_name;
}
 
 
std::string option_info::get_basename() const
{
    std::string::size_type const pos(f_name.rfind("::"));
    if(pos == std::string::npos)
    {
        return f_name;
    }
 
    return f_name.substr(pos + 2);
}
 
 
std::string option_info::get_section_name() const
{
    std::string::size_type const pos(f_name.rfind("::"));
    if(pos == std::string::npos)
    {
        return std::string();
    }
 
    return f_name.substr(0, pos);
}
 
 
string_list_t option_info::get_section_name_list() const
{
    std::string::size_type const pos(f_name.rfind("::"));
    if(pos == std::string::npos)
    {
        return string_list_t();
    }
 
    string_list_t section_list;
    snapdev::tokenize_string(section_list
                        , f_name.substr(0, pos)
                        , "::"
                        , true
                        , std::string()
                        , &snapdev::string_predicate<string_list_t>);
    return section_list;
}
 
 
bool option_info::is_default_option() const
{
    return has_flag(GETOPT_FLAG_DEFAULT_OPTION)
        || (f_name.size() == 2 && f_name[0] == '-' && f_name[1] == '-');
}
 
 
void option_info::set_environment_variable_name(std::string const & name)
{
    f_environment_variable_name = name;
}
 
 
void option_info::set_environment_variable_name(char const * name)
{
    if(name != nullptr)
    {
        set_environment_variable_name(std::string(name));
    }
}
 
 
std::string option_info::get_environment_variable_name() const
{
    return f_environment_variable_name;
}
 
 
bool option_info::get_environment_variable_value(
          std::string & value
        , char const * intro) const
{
    // make it empty by default
    //
    value.clear();
 
    if(f_environment_variable_name.empty())
    {
        return false;
    }
 
    std::string name(f_environment_variable_name);
    if(intro != nullptr)
    {
        name = intro + name;
    }
 
    char const * env(getenv(name.c_str()));
    if(env == nullptr)
    {
        return false;
    }
 
    value = env;
 
    return true;
}
 
 
void option_info::set_flags(flag_t flags)
{
    f_flags = flags;
}
 
 
void option_info::add_flag(flag_t flag)
{
    set_flags(f_flags | flag);
}
 
 
void option_info::remove_flag(flag_t flag)
{
    set_flags(f_flags & ~flag);
}
 
 
flag_t option_info::get_flags() const
{
    return f_flags;
}
 
 
bool option_info::has_flag(flag_t flag) const
{
    return (f_flags & flag) != 0;
}
 
 
bool option_info::has_default() const
{
    return has_flag(GETOPT_FLAG_HAS_DEFAULT);
}
 
 
void option_info::set_default(std::string const & default_value)
{
    f_default_value = default_value;
    add_flag(GETOPT_FLAG_HAS_DEFAULT);
}
 
 
void option_info::set_default(char const * default_value)
{
    if(default_value != nullptr)
    {
        set_default(std::string(default_value));
    }
}
 
 
void option_info::remove_default()
{
    f_default_value.clear();
    remove_flag(GETOPT_FLAG_HAS_DEFAULT);
}
 
 
std::string const & option_info::get_default() const
{
    return f_default_value;
}
 
 
void option_info::set_help(std::string const & help)
{
    f_help = help;
}
 
 
void option_info::set_help(char const * help)
{
    if(help != nullptr)
    {
        set_help(std::string(help));
    }
}
 
 
std::string const & option_info::get_help() const
{
    return f_help;
}
 
 
bool option_info::set_validator(std::string const & name_and_params)
{
    return set_validator(validator::create(name_and_params));
}
 
 
bool option_info::set_validator(validator::pointer_t validator)
{
    f_validator = validator;
 
    // make sure that all existing values validate against this
    // new validator
    //
    std::size_t const size(f_value.size());
    bool const r(validate_all_values());
    if(size != f_value.size())
    {
        value_changed(0);
    }
    return r;
}
 
 
bool option_info::set_validator(std::nullptr_t null_ptr)
{
    snapdev::NOT_USED(null_ptr);
 
    f_validator.reset();
 
    return true;
}
 
 
bool option_info::validates(int idx)
{
    if(static_cast<size_t>(idx) >= f_value.size())
    {
        throw getopt_undefined(                                         // LCOV_EXCL_LINE
                      "option_info::validates(): no value at index "    // LCOV_EXCL_LINE
                    + std::to_string(idx)                               // LCOV_EXCL_LINE
                    + " (idx >= "                                       // LCOV_EXCL_LINE
                    + std::to_string(f_value.size())                    // LCOV_EXCL_LINE
                    + ") for --"                                        // LCOV_EXCL_LINE
                    + f_name                                            // LCOV_EXCL_LINE
                    + " so you can't get this value.");                 // LCOV_EXCL_LINE
    }
 
    // the value is considered valid when:
    //   * there is no validator
    //   * if the value is empty
    //   * when the value validate against the specified validator
    //
    if(f_validator == nullptr
    || f_value[idx].empty()
    || f_validator->validate(f_value[idx]))
    {
        return true;
    }
 
    cppthread::log << cppthread::log_level_t::error
                   << "input \""
                   << f_value[idx]
                   << "\" given to parameter --"
                   << f_name
                   << " is not considered valid."
                   << cppthread::end;
 
    // get rid of that value since it does not validate
    //
    f_value.erase(f_value.begin() + idx);
    if(f_value.empty())
    {
        f_source = option_source_t::SOURCE_UNDEFINED;
    }
 
    return false;
}
 
 
validator::pointer_t option_info::get_validator() const
{
    return f_validator;
}
 
 
void option_info::set_alias_destination(option_info::pointer_t destination)
{
    if(destination->has_flag(GETOPT_FLAG_ALIAS))
    {
        throw getopt_invalid(
                "option_info::set_alias(): you can't set an alias as"
                " an alias of another option.");
    }
 
    f_alias_destination = destination;
}
 
 
option_info::pointer_t option_info::get_alias_destination() const
{
    return f_alias_destination;
}
 
 
void option_info::set_multiple_separators(char const * const * separators)
{
    f_multiple_separators.clear();
    if(separators == nullptr)
    {
        return;
    }
 
    for(; *separators != nullptr; ++separators)
    {
        f_multiple_separators.push_back(*separators);
    }
}
 
 
void option_info::set_multiple_separators(string_list_t const & separators)
{
    f_multiple_separators = separators;
}
 
 
string_list_t const & option_info::get_multiple_separators() const
{
    return f_multiple_separators;
}
 
 
void option_info::set_variables(variables::pointer_t vars)
{
    f_variables = vars;
}
 
 
variables::pointer_t option_info::get_variables() const
{
    return f_variables;
}
 
 
bool option_info::has_value(std::string const & value) const
{
    auto const it(std::find(f_value.begin(), f_value.end(), value));
    return it != f_value.end();
}
 
 
bool option_info::add_value(
      std::string const & value
    , string_list_t const & option_keys
    , option_source_t source)
{
    return set_value(
              has_flag(GETOPT_FLAG_MULTIPLE)
                    ? f_value.size()
                    : 0
            , value
            , option_keys
            , source);
}
 
 
bool option_info::set_value(
      int idx
    , std::string const & value
    , string_list_t const & option_keys
    , option_source_t source)
{
    if(source == option_source_t::SOURCE_UNDEFINED)
    {
        throw getopt_logic_error(
                  "option_info::set_value(): called with SOURCE_UNDEFINED ("
                + std::to_string(static_cast<int>(source))
                + ").");
    }
 
    if(has_flag(GETOPT_FLAG_LOCK))
    {
        return false;
    }
 
    if(source == option_source_t::SOURCE_DIRECT
    && !has_flag(GETOPT_FLAG_DYNAMIC_CONFIGURATION))
    {
        cppthread::log << cppthread::log_level_t::error
                       << "option \"--"
                       << f_name
                       << "\" can't be directly updated."
                       << cppthread::end;
        return false;
    }
 
    bool const multiple(has_flag(GETOPT_FLAG_MULTIPLE));
    if(multiple)
    {
        if(static_cast<size_t>(idx) > f_value.size())
        {
            throw getopt_logic_error(
                      "option_info::set_value(): no value at index "
                    + std::to_string(idx)
                    + " and it is not the last available index + 1 (idx > "
                    + std::to_string(f_value.size())
                    + ") so you can't set this value (try add_value() maybe?).");
        }
    }
    else
    {
        if(idx != 0)
        {
            throw getopt_logic_error(
                          "option_info::set_value(): single value option \"--"
                        + f_name
                        + "\" does not accepts index "
                        + std::to_string(idx)
                        + " which is not 0.");
        }
    }
 
    f_source = source;
    f_integer.clear();
    f_double.clear();
 
    bool r(true);
    if(option_keys.empty())
    {
        if(static_cast<size_t>(idx) == f_value.size())
        {
            f_value.push_back(value);
        }
        else
        {
            if(f_value[idx] == value)
            {
                // no change, we can return as is
                //
                // note: we know that the value is valid here since the
                //       validates() function removes invalid values from
                //       the f_value array
                //
                return true;
            }
            f_value[idx] = value;
        }
 
        if(validates(idx))
        {
            value_changed(idx);
        }
        else
        {
            r = false;
        }
    }
    else
    {
        bool changed(false);
        bool const append(multiple && idx >= static_cast<int>(f_value.size()));
        for(auto const & k : option_keys)
        {
            bool new_value(true);
            std::string const v(k + value);
            idx = append ? -1 : find_value_index_by_key(k);
            if(idx == -1)
            {
                f_value.push_back(v);
                changed = true;
            }
            else
            {
                if(f_value[idx] == v)
                {
                    new_value = false;
                }
                else
                {
                    changed = true;
                    f_value[idx] = v;
                }
            }
            if(new_value)
            {
                if(validates(idx))
                {
                    value_changed(idx);
                }
                else
                {
                    r = false;
                }
            }
        }
        if(!changed)
        {
            return true;
        }
    }
 
    return r;
}
 
 
bool option_info::set_multiple_values(
      std::string const & value
    , string_list_t const & option_keys
    , option_source_t source)
{
    if(!has_flag(GETOPT_FLAG_ARRAY)
    && option_keys.size() != 0)
    {
        throw getopt_logic_error(
                 "option_info::set_multiple_value(): parameter --"
               + f_name
               + " does not support array keys.");
    }
 
    if(source == option_source_t::SOURCE_UNDEFINED)
    {
        throw getopt_logic_error(
                  "option_info::set_multiple_values(): called with SOURCE_UNDEFINED ("
                + std::to_string(static_cast<int>(source))
                + ").");
    }
 
    string_list_t result;
    split_string(unquote(value, "[]"), result, f_multiple_separators);
 
    if(!has_flag(GETOPT_FLAG_MULTIPLE)
    && result.size() > 1)
    {
        throw getopt_logic_error(
                 "option_info::set_multiple_value(): parameter --"
               + f_name
               + " expects zero or one parameter. The set_multiple_value() function should not be called with parameters that only accept one value.");
    }
 
    if(!option_keys.empty())
    {
        string_list_t keyed_result;
        for(auto const & k : option_keys)
        {
            for(auto & r : result)
            {
                // note: the keys are expected to already include the ending ':'
                //
                keyed_result.push_back(k + r);
            }
        }
        result.swap(keyed_result);
    }
 
    f_source = source;
    f_value.swap(result);
    f_integer.clear();
    f_double.clear();
 
    bool const r(validate_all_values());
 
    if(f_value != result)
    {
        // TBD: should we not call this function with all instances?
        //      i.e. for(int idx(0); idx < f_value.size(); ++idx) ...
        //      and check each value in f_value with the old value in
        //      the result variable (knowing that result may be smaller)
        //
        value_changed(0);
    }
 
    return r;
}
 
 
bool option_info::validate_all_values()
{
    bool all_valid(true);
    if(f_validator != nullptr)
    {
        for(size_t idx(0); idx < f_value.size(); )
        {
            if(!validates(idx))
            {
                // the value was removed, so do not increment `idx`
                //
                all_valid = false;
            }
            else
            {
                ++idx;
            }
        }
    }
 
    return all_valid;
}
 
 
bool option_info::is_defined() const
{
    return !f_value.empty();
}
 
 
option_source_t option_info::source() const
{
    return f_source;
}
 
 
void option_info::set_trace_sources(bool trace)
{
    g_trace_sources = trace;
}
 
 
string_list_t const & option_info::trace_sources() const
{
    return f_trace_sources;
}
 
 
void option_info::set_configuration_filename(std::string const & filename)
{
    g_configuration_filename = filename;
}
 
 
size_t option_info::size() const
{
    return f_value.size();
}
 
 
std::string option_info::get_value(int idx, bool raw) const
{
    if(static_cast<size_t>(idx) >= f_value.size())
    {
        throw getopt_undefined(
                      "option_info::get_value(): no value at index "
                    + std::to_string(idx)
                    + " (idx >= "
                    + std::to_string(f_value.size())
                    + ") for --"
                    + f_name
                    + " so you can't get this value.");
    }
 
    if(!raw
    && f_variables != nullptr
    && has_flag(GETOPT_FLAG_PROCESS_VARIABLES))
    {
        return f_variables->process_value(f_value[idx]);
    }
    else
    {
        return f_value[idx];
    }
}
 
 
int option_info::find_value_index_by_key(std::string key, int idx) const
{
    if(idx < 0)
    {
        throw getopt_logic_error("idx cannot be negative in find_value_index_by_key()");
    }
    if(f_value.empty())
    {
        throw getopt_undefined(
                      "option_info::find_value_index_by_key(): --"
                    + f_name
                    + " has no values defined.");
    }
 
    if(key.back() != ':')
    {
        key += ':';
    }
    int const max(f_value.size());
    for(; idx < max; ++idx)
    {
        if(f_value[idx].rfind(key, 0) == 0)
        {
            return idx;
        }
    }
 
    return -1;
}
 
 
long option_info::get_long(int idx) const
{
    if(static_cast<size_t>(idx) >= f_value.size())
    {
        throw getopt_undefined(
                      "option_info::get_long(): no value at index "
                    + std::to_string(idx)
                    + " (idx >= "
                    + std::to_string(f_value.size())
                    + ") for --"
                    + f_name
                    + " so you can't get this value.");
    }
 
    // since we may change the f_integer vector between threads,
    // add protection (i.e. most everything else is created at the
    // beginning so in the main thread)
    //
    cppthread::guard lock(get_global_mutex());
 
    if(f_integer.size() != f_value.size())
    {
        // we did not yet convert to integers do that now
        //
        size_t const max(f_value.size());
        for(size_t i(f_integer.size()); i < max; ++i)
        {
            std::int64_t v;
            if(!validator_integer::convert_string(get_value(i), v))
            {
                f_integer.clear();
 
                cppthread::log << cppthread::log_level_t::error
                               << "invalid number ("
                               << f_value[i]
                               << ") in parameter --"
                               << f_name
                               << " at offset "
                               << i
                               << "."
                               << cppthread::end;
                return -1;
            }
            f_integer.push_back(v);
        }
    }
 
    return f_integer[idx];
}
 
 
double option_info::get_double(int idx) const
{
    if(static_cast<size_t>(idx) >= f_value.size())
    {
        throw getopt_undefined(
                      "option_info::get_double(): no value at index "
                    + std::to_string(idx)
                    + " (idx >= "
                    + std::to_string(f_value.size())
                    + ") for --"
                    + f_name
                    + " so you can't get this value.");
    }
 
    // since we may change the f_integer vector between threads,
    // add protection (i.e. most everything else is created at the
    // beginning so in the main thread)
    //
    cppthread::guard lock(get_global_mutex());
 
    if(f_double.size() != f_value.size())
    {
        // we did not yet convert to doubles do that now
        //
        size_t const max(f_value.size());
        for(size_t i(f_double.size()); i < max; ++i)
        {
            double v;
            if(!validator_double::convert_string(get_value(i), v))
            {
                f_double.clear();
 
                cppthread::log << cppthread::log_level_t::error
                               << "invalid number ("
                               << f_value[i]
                               << ") in parameter --"
                               << f_name
                               << " at offset "
                               << i
                               << "."
                               << cppthread::end;
                return -1;
            }
            f_double.push_back(v);
        }
    }
 
    return f_double[idx];
}
 
 
void option_info::lock(bool always)
{
    if(!always)
    {
        if(!is_defined())
        {
            return;
        }
    }
 
    add_flag(GETOPT_FLAG_LOCK);
}
 
 
void option_info::unlock()
{
    remove_flag(GETOPT_FLAG_LOCK);
}
 
 
void option_info::reset()
{
    if(is_defined())
    {
        f_source = option_source_t::SOURCE_UNDEFINED;
        f_value.clear();
        f_integer.clear();
        f_double.clear();
 
        value_changed(0);
    }
}
 
 
option_info::callback_id_t option_info::add_callback(callback_t const & c)
{
    cppthread::guard lock(get_global_mutex());
 
    ++f_next_callback_id;
    f_callbacks.emplace_back(f_next_callback_id, c);
    return f_next_callback_id;
}
 
 
void option_info::remove_callback(callback_id_t id)
{
    cppthread::guard lock(get_global_mutex());
 
    auto it(std::find_if(
              f_callbacks.begin()
            , f_callbacks.end()
            , [id](auto e)
            {
                return e.f_id == id;
            }));
    if(it != f_callbacks.end())
    {
        f_callbacks.erase(it);
    }
}
 
 
void option_info::value_changed(int idx)
{
    trace_source(idx);
 
    callback_vector_t callbacks;
    callbacks.reserve(f_callbacks.size());
 
    {
        cppthread::guard lock(get_global_mutex());
        callbacks = f_callbacks;
    }
 
    for(auto e : callbacks)
    {
        e.f_callback(*this);
    }
}
 
 
 
void option_info::trace_source(int idx)
{
    if(!g_trace_sources)
    {
        return;
    }
 
    std::string s;
    switch(f_source)
    {
    case option_source_t::SOURCE_COMMAND_LINE:
        s = "command-line";
        break;
 
    case option_source_t::SOURCE_CONFIGURATION:
        s = "configuration=\"" + g_configuration_filename + "\"";
        break;
 
    case option_source_t::SOURCE_DIRECT:
        s = "direct";
        break;
 
    case option_source_t::SOURCE_DYNAMIC:
        s = "dynamic";
        break;
 
    case option_source_t::SOURCE_ENVIRONMENT_VARIABLE:
        s = "environment-variable";
        break;
 
    case option_source_t::SOURCE_UNDEFINED:
        // this happens on a reset or all the values were invalid
        //
        f_trace_sources.push_back(f_name + " [*undefined-source*]");
        return;
 
    }
 
    if(f_value.empty())
    {
        // this should never ever happen
        // (if f_value is empty then f_source == SOURCE_UNDEFINED)
        //
        f_trace_sources.push_back(f_name + " [*undefined-value*]");     // LCOV_EXCL_LINE
    }
    else
    {
        // TODO: change the algorithm, if the option supports
        //
        if(!has_flag(GETOPT_FLAG_MULTIPLE)
        || static_cast<std::size_t>(idx) >= f_value.size())
        {
            f_trace_sources.push_back(f_name + "=" + f_value[0] + " [" + s + "]");
        }
        else
        {
            f_trace_sources.push_back(f_name + "[" + std::to_string(idx) + "]=" + f_value[idx] + " [" + s + "]");
        }
    }
}
 
 
}   // namespace advgetopt
// vim: ts=4 sw=4 et