/usr/include/hocon/config.hpp is in libcpp-hocon-dev 0.1.6-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 | #pragma once
#include "types.hpp"
#include "config_mergeable.hpp"
#include "config_origin.hpp"
#include "config_object.hpp"
#include "config_resolve_options.hpp"
#include "config_value.hpp"
#include "config_list.hpp"
#include "config_exception.hpp"
#include "path.hpp"
#include <vector>
#include <string>
#include <set>
#include "export.h"
#include <leatherman/locale/locale.hpp>
namespace hocon {
enum class time_unit { NANOSECONDS, MICROSECONDS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS };
/**
* An immutable map from config paths to config values. Paths are dot-separated
* expressions such as <code>foo.bar.baz</code>. Values are as in JSON
* (booleans, strings, numbers, lists, or objects), represented by
* {@link config_value} instances. Values accessed through the
* <code>config</code> interface are never null.
*
* <p>
* {@code config} is an immutable object and thus safe to use from multiple
* threads. There's never a need for "defensive copies."
*
* <p>
* Fundamental operations on a {@code config} include getting configuration
* values, <em>resolving</em> substitutions with {@link config#resolve()}, and
* merging configs using {@link config#with_fallback(config_mergeable)}.
*
* <p>
* All operations return a new immutable {@code config} rather than modifying
* the original instance.
*
* <p>
* <strong>Examples</strong>
*
* <p>
* You can find an example app and library <a
* href="https://github.com/typesafehub/config/tree/master/examples">on
* GitHub</a>. Also be sure to read the <a
* href="package-summary.html#package_description">package overview</a> which
* describes the big picture as shown in those examples.
*
* <p>
* <strong>Paths, keys, and config vs. config_object</strong>
*
* <p>
* <code>config</code> is a view onto a tree of {@link config_object}; the
* corresponding object tree can be found through {@link config#root()}.
* <code>config_object</code> is a map from config <em>keys</em>, rather than
* paths, to config values. Think of <code>config_object</code> as a JSON object
* and <code>config</code> as a configuration API.
*
* <p>
* The API tries to consistently use the terms "key" and "path." A key is a key
* in a JSON object; it's just a string that's the key in a map. A "path" is a
* parseable expression with a syntax and it refers to a series of keys. Path
* expressions are described in the <a
* href="https://github.com/typesafehub/config/blob/master/HOCON.md">spec for
* Human-Optimized Config Object Notation</a>. In brief, a path is
* period-separated so "a.b.c" looks for key c in object b in object a in the
* root object. Sometimes double quotes are needed around special characters in
* path expressions.
*
* <p>
* The API for a {@code config} is in terms of path expressions, while the API
* for a {@code config_object} is in terms of keys. Conceptually, {@code config}
* is a one-level map from <em>paths</em> to values, while a
* {@code config_object} is a tree of nested maps from <em>keys</em> to values.
*
* <p>
* Use {@link config_util#join_path} and {@link config_util#split_path} to convert
* between path expressions and individual path elements (keys).
*
* <p>
* Another difference between {@code config} and {@code config_object} is that
* conceptually, {@code config_value}s with a {@link config_value#value_type()
* value_type()} of {@link config_value::type#NULL NULL} exist in a
* {@code config_object}, while a {@code config} treats null values as if they
* were missing. (With the exception of two methods: {@link config#has_path_or_null}
* and {@link config#get_is_null} let you detect <code>null</code> values.)
*
* <p>
* <strong>Getting configuration values</strong>
*
* <p>
* The "getters" on a {@code config} all work in the same way. They never return
* null, nor do they return a {@code config_value} with
* {@link config_value#value_type() value_type()} of {@link config_value::type#NULL
* NULL}. Instead, they throw {@link config_exception} if the value is
* completely absent or set to null. If the value is set to null, a subtype of
* {@code config_exception.missing} called {@link config_exception.null} will be
* thrown. {@link config_excpetion.wrong_type} will be thrown anytime you ask for
* a type and the value has an incompatible type. Reasonable type conversions
* are performed for you though.
*
* <p>
* <strong>Iteration</strong>
*
* <p>
* If you want to iterate over the contents of a {@code config}, you can get its
* {@code config_object} with {@link #root()}, and then iterate over the
* {@code config_object} (which implements <code>java.util.Map</code>). Or, you
* can use {@link #entry_set()} which recurses the object tree for you and builds
* up a <code>set</code> of all path-value pairs where the value is not null.
*
* <p>
* <strong>Resolving substitutions</strong>
*
* <p>
* <em>Substitutions</em> are the <code>${foo.bar}</code> syntax in config
* files, described in the <a href=
* "https://github.com/typesafehub/config/blob/master/HOCON.md#substitutions"
* >specification</a>. Resolving substitutions replaces these references with real
* values.
*
* <p>
* Before using a {@code config} it's necessary to call {@link config#resolve()}
* to handle substitutions (though {@link config_factory#load()} and similar
* methods will do the resolve for you already).
*
* <p>
* <strong>Merging</strong>
*
* <p>
* The full <code>config</code> for your application can be constructed using
* the associative operation {@link config#with_fallback(config_mergeable)}. If
* you use {@link config_factory#load()} (recommended), it merges system
* properties over the top of <code>application.conf</code> over the top of
* <code>reference.conf</code>, using <code>with_fallback</code>. You can add in
* additional sources of configuration in the same way (usually, custom layers
* should go either just above or just below <code>application.conf</code>,
* keeping <code>reference.conf</code> at the bottom and system properties at
* the top).
*
* <p>
* <strong>Serialization</strong>
*
* <p>
* Convert a <code>config</code> to a JSON or HOCON string by calling
* {@link config_object#render()} on the root object,
* <code>my_config.root().render()</code>. There's also a variant
* {@link config_object#render(config_render_options)} which allows you to control
* the format of the rendered string. (See {@link config_render_options}.) Note
* that <code>config</code> does not remember the formatting of the original
* file, so if you load, modify, and re-save a config file, it will be
* substantially reformatted.
*
* <p>
* As an alternative to {@link config_object#render()}, the
* <code>to_string()</code> method produces a debug-output-oriented
* representation (which is not valid JSON).
*
* <p>
* <strong>This is an interface but don't implement it yourself</strong>
*
* <p>
* <em>Do not implement {@code config}</em>; it should only be implemented by
* the config library. Arbitrary implementations will not work because the
* library internals assume a specific concrete implementation. Also, this
* interface is likely to grow new methods over time, so third-party
* implementations will break.
*/
class LIBCPP_HOCON_EXPORT config : public config_mergeable, public std::enable_shared_from_this<config> {
friend class config_object;
friend class config_value;
friend class config_parseable;
friend class parseable;
public:
/**
* Parses a file with a flexible extension. If the <code>fileBasename</code>
* already ends in a known extension, this method parses it according to
* that extension (the file's syntax must match its extension). If the
* <code>fileBasename</code> does not end in an extension, it parses files
* with all known extensions and merges whatever is found.
*
* <p>
* In the current implementation, the extension ".conf" forces
* {@link ConfigSyntax#CONF}, ".json" forces {@link ConfigSyntax#JSON}.
* When merging files, ".conf" falls back to ".json".
*
* <p>
* Future versions of the implementation may add additional syntaxes or
* additional extensions. However, the ordering (fallback priority) of the
* three current extensions will remain the same.
*
* <p>
* If <code>options</code> forces a specific syntax, this method only parses
* files with an extension matching that syntax.
*
* <p>
* If {@link ConfigParseOptions#getAllowMissing options.getAllowMissing()}
* is true, then no files have to exist; if false, then at least one file
* has to exist.
*
* @param fileBasename
* a filename with or without extension
* @param options
* parse options
* @return the parsed configuration
*/
static shared_config parse_file_any_syntax(std::string file_basename, config_parse_options options);
/**
* Like {@link #parseFileAnySyntax(File,ConfigParseOptions)} but always uses
* default parse options.
*
* @param fileBasename
* a filename with or without extension
* @return the parsed configuration
*/
static shared_config parse_file_any_syntax(std::string file_basename);
/**
* Parses a string (which should be valid HOCON or JSON by default, or
* the syntax specified in the options otherwise).
*
* @param s string to parse
* @param options parse options
* @return the parsed configuration
*/
static shared_config parse_string(std::string s, config_parse_options options);
/**
* Parses a string (which should be valid HOCON or JSON).
*
* @param s string to parse
* @return the parsed configuration
*/
static shared_config parse_string(std::string s);
/**
* Gets the {@code Config} as a tree of {@link ConfigObject}. This is a
* constant-time operation (it is not proportional to the number of values
* in the {@code Config}).
*
* @return the root object in the configuration
*/
virtual shared_object root() const;
/**
* Gets the origin of the {@code Config}, which may be a file, or a file
* with a line number, or just a descriptive phrase.
*
* @return the origin of the {@code Config} for use in error messages
*/
virtual shared_origin origin() const;
std::shared_ptr<const config_mergeable> with_fallback(std::shared_ptr<const config_mergeable> other) const override;
shared_value to_fallback_value() const override;
/**
* Returns a replacement config with all substitutions (the
* <code>${foo.bar}</code> syntax, see <a
* href="https://github.com/typesafehub/config/blob/master/HOCON.md">the
* spec</a>) resolved. Substitutions are looked up using this
* <code>config</code> as the root object, that is, a substitution
* <code>${foo.bar}</code> will be replaced with the result of
* <code>get_value("foo.bar")</code>.
*
* <p>
* This method uses {@link config_resolve_options()}, there is
* another variant {@link config#resolve(config_resolve_options)} which lets
* you specify non-default options.
*
* <p>
* A given {@link config} must be resolved before using it to retrieve
* config values, but ideally should be resolved one time for your entire
* stack of fallbacks (see {@link config#with_fallback}). Otherwise, some
* substitutions that could have resolved with all fallbacks available may
* not resolve, which will be potentially confusing for your application's
* users.
*
* <p>
* <code>resolve()</code> should be invoked on root config objects, rather
* than on a subtree (a subtree is the result of something like
* <code>config.get_config("foo")</code>). The problem with
* <code>resolve()</code> on a subtree is that substitutions are relative to
* the root of the config and the subtree will have no way to get values
* from the root. For example, if you did
* <code>config.get_config("foo").resolve()</code> on the below config file,
* it would not work:
*
* <pre>
* common-value = 10
* foo {
* whatever = ${common-value}
* }
* </pre>
*
* <p>
* Many methods on {@link config_factory} such as
* {@link config_factory#load()} automatically resolve the loaded
* <code>config</code> on the loaded stack of config files.
*
* <p>
* Resolving an already-resolved config is a harmless no-op, but again, it
* is best to resolve an entire stack of fallbacks (such as all your config
* files combined) rather than resolving each one individually.
*
* @return an immutable object with substitutions resolved
*/
virtual shared_config resolve() const;
/**
* Like {@link config#resolve()} but allows you to specify non-default
* options.
*
* @param options
* resolve options
* @return the resolved <code>config</code> (may be only partially resolved if options are
* set to allow unresolved)
*/
virtual shared_config resolve(config_resolve_options options) const;
/**
* Checks whether the config is completely resolved. After a successful call
* to {@link config#resolve()} it will be completely resolved, but after
* calling {@link config#resolve(config_resolve_options)} with
* <code>allow_unresolved</code> set in the options, it may or may not be
* completely resolved. A newly-loaded config may or may not be completely
* resolved depending on whether there were substitutions present in the
* file.
*
* @return true if there are no unresolved substitutions remaining in this
* configuration.
*/
virtual bool is_resolved() const;
/**
* Like {@link config#resolve()} except that substitution values are looked
* up in the given source, rather than in this instance. This is a
* special-purpose method which doesn't make sense to use in most cases;
* it's only needed if you're constructing some sort of app-specific custom
* approach to configuration. The more usual approach if you have a source
* of substitution values would be to merge that source into your config
* stack using {@link config#withFallback} and then resolve.
* <p>
* Note that this method does NOT look in this instance for substitution
* values. If you want to do that, you could either merge this instance into
* your value source using {@link config#with_fallback}, or you could resolve
* multiple times with multiple sources (using
* {@link config_resolve_options#setAllowUnresolved(boolean)} so the partial
* resolves don't fail).
*
* @param source
* configuration to pull values from
* @return an immutable object with substitutions resolved
*/
virtual shared_config resolve_with(shared_config source) const;
/**
* Like {@link config#resolve_with(config)} but allows you to specify
* non-default options.
*
* @param source
* source configuration to pull values from
* @param options
* resolve options
* @return the resolved <code>config</code> (may be only partially resolved
* if options are set to allow unresolved)
*/
virtual shared_config resolve_with(shared_config source, config_resolve_options options) const;
/**
* Validates this config against a reference config, throwing an exception
* if it is invalid. The purpose of this method is to "fail early" with a
* comprehensive list of problems; in general, anything this method can find
* would be detected later when trying to use the config, but it's often
* more user-friendly to fail right away when loading the config.
*
* <p>
* Using this method is always optional, since you can "fail late" instead.
*
* <p>
* You must restrict validation to paths you "own" (those whose meaning are
* defined by your code module). If you validate globally, you may trigger
* errors about paths that happen to be in the config but have nothing to do
* with your module. It's best to allow the modules owning those paths to
* validate them. Also, if every module validates only its own stuff, there
* isn't as much redundant work being done.
*
* <p>
* If no paths are specified in <code>check_valid()</code>'s parameter list,
* validation is for the entire config.
*
* <p>
* If you specify paths that are not in the reference config, those paths
* are ignored. (There's nothing to validate.)
*
* <p>
* Here's what validation involves:
*
* <ul>
* <li>All paths found in the reference config must be present in this
* config or an exception will be thrown.
* <li>
* Some changes in type from the reference config to this config will cause
* an exception to be thrown. Not all potential type problems are detected,
* in particular it's assumed that strings are compatible with everything
* except objects and lists. This is because string types are often "really"
* some other type (system properties always start out as strings, or a
* string like "5ms" could be used with {@link #get_milliseconds}). Also,
* it's allowed to set any type to null or override null with any type.
* <li>
* Any unresolved substitutions in this config will cause a validation
* failure; both the reference config and this config should be resolved
* before validation. If the reference config is unresolved, it's a bug in
* the caller of this method.
* </ul>
*
* <p>
* If you want to allow a certain setting to have a flexible type (or
* otherwise want validation to be looser for some settings), you could
* either remove the problematic setting from the reference config provided
* to this method, or you could intercept the validation exception and
* screen out certain problems. Of course, this will only work if all other
* callers of this method are careful to restrict validation to their own
* paths, as they should be.
*
* <p>
* If validation fails, the thrown exception contains a list of all problems
* found. The exception will have all the problem concatenated into one huge string.
*
* <p>
* Again, <code>check_valid()</code> can't guess every domain-specific way a
* setting can be invalid, so some problems may arise later when attempting
* to use the config. <code>check_valid()</code> is limited to reporting
* generic, but common, problems such as missing settings and blatant type
* incompatibilities.
*
* @param reference
* a reference configuration
* @param restrictToPaths
* only validate values underneath these paths that your code
* module owns and understands
*/
virtual void check_valid(shared_config reference, std::vector<std::string> restrict_to_paths) const;
/**
* Checks whether a value is present and non-null at the given path. This
* differs in two ways from {@code Map.containsKey()} as implemented by
* {@link config_object}: it looks for a path expression, not a key; and it
* returns false for null values, while {@code contains_key()} returns true
* indicating that the object contains a null value for the key.
*
* <p>
* If a path exists according to {@link #has_path(string)}, then
* {@link #get_value(string)} will never throw an exception. However, the
* typed getters will still throw if the value is not convertible to the
* requested type.
*
* <p>
* Note that path expressions have a syntax and sometimes require quoting
* (see {@link config_util#join_path} and {@link config_util#split_path}).
*
* @param path
* the path expression
* @return true if a non-null value is present at the path
*/
virtual bool has_path(std::string const& path) const;
/**
* Checks whether a value is present at the given path, even
* if the value is null. Most of the getters on
* <code>config</code> will throw if you try to get a null
* value, so if you plan to call {@link #get_value(string)},
* {@link #get_int(string)}, or another getter you may want to
* use plain {@link #has_path(string)} rather than this method.
*
* <p>
* To handle all three cases (unset, null, and a non-null value)
* the code might look like:
* <pre><code>
* if (config.has_path_or_null(path)) {
* if (config.get_is_null(path)) {
* // handle null setting
* } else {
* // get and use non-null setting
* }
* } else {
* // handle entirely unset path
* }
* </code></pre>
*
* <p> However, the usual thing is to allow entirely unset
* paths to be a bug that throws an exception (because you set
* a default in your <code>reference.conf</code>), so in that
* case it's OK to call {@link #get_is_null(string)} without
* checking <code>has_path_or_null</code> first.
*
* <p>
* Note that path expressions have a syntax and sometimes require quoting
* (see {@link config_util#join_path} and {@link config_util#split_path}).
*
* @param path
* the path expression
* @return true if a value is present at the path, even if the value is null
*/
virtual bool has_path_or_null(std::string const& path) const;
/**
* Returns true if the {@code Config}'s root object contains no key-value
* pairs.
*
* @return true if the configuration is empty
*/
virtual bool is_empty() const;
/**
* Returns the set of path-value pairs, excluding any null values, found by
* recursing {@link #root() the root object}. Note that this is very
* different from <code>root().entry_set()</code> which returns the set of
* immediate-child keys in the root object and includes null values.
* <p>
* Entries contain <em>path expressions</em> meaning there may be quoting
* and escaping involved. Parse path expressions with
* {@link config_util#split_path}.
* <p>
* Because a <code>config</code> is conceptually a single-level map from
* paths to values, there will not be any {@link config_object} values in the
* entries (that is, all entries represent leaf nodes). Use
* {@link config_object} rather than <code>config</code> if you want a tree.
* (OK, this is a slight lie: <code>config</code> entries may contain
* {@link config_list} and the lists may contain objects. But no objects are
* directly included as entry values.)
*
* @return set of paths with non-null values, built up by recursing the
* entire tree of {@link config_object} and creating an entry for
* each leaf value.
*/
virtual std::set<std::pair<std::string, std::shared_ptr<const config_value>>> entry_set() const;
/**
* Checks whether a value is set to null at the given path,
* but throws an exception if the value is entirely
* unset. This method will not throw if {@link
* #has_path_or_null(string)} returned true for the same path, so
* to avoid any possible exception check
* <code>has_path_or_null()</code> first. However, an exception
* for unset paths will usually be the right thing (because a
* <code>reference.conf</code> should exist that has the path
* set, the path should never be unset unless something is
* broken).
*
* <p>
* Note that path expressions have a syntax and sometimes require quoting
* (see {@link config_util#join_path} and {@link config_util#split_path}).
*
* @param path
* the path expression
* @return true if the value exists and is null, false if it
* exists and is not null
*/
virtual bool get_is_null(std::string const& path) const;
virtual bool get_bool(std::string const& path) const;
virtual int get_int(std::string const& path) const;
virtual int64_t get_long(std::string const& path) const;
virtual double get_double(std::string const& path) const;
virtual std::string get_string(std::string const& path) const;
virtual std::shared_ptr<const config_object> get_object(std::string const& path) const;
virtual shared_config get_config(std::string const& path) const;
virtual unwrapped_value get_any_ref(std::string const& path) const;
virtual std::shared_ptr<const config_value> get_value(std::string const& path) const;
template<typename T>
std::vector<T> get_homogeneous_unwrapped_list(std::string const& path) const {
auto list = boost::get<std::vector<unwrapped_value>>(get_list(path)->unwrapped());
std::vector<T> T_list;
for (auto item : list) {
try {
T_list.push_back(boost::get<T>(item));
} catch (boost::bad_get &ex) {
throw config_exception(leatherman::locale::format("The list did not contain only the desired type."));
}
}
return T_list;
}
virtual shared_list get_list(std::string const& path) const;
virtual std::vector<bool> get_bool_list(std::string const& path) const;
virtual std::vector<int> get_int_list(std::string const& path) const;
virtual std::vector<int64_t> get_long_list(std::string const& path) const;
virtual std::vector<double> get_double_list(std::string const& path) const;
virtual std::vector<std::string> get_string_list(std::string const& path) const;
virtual std::vector<shared_object> get_object_list(std::string const& path) const;
virtual std::vector<shared_config> get_config_list(std::string const& path) const;
// TODO: memory parsing
/**
* Gets a value as an integer number of the specified units.
* If the result would have a fractional part, the number is truncated.
* Correctly handles durations within the range +/-2^63 seconds.
* @param path the path to the time value
* @param unit the units of the number returned
* @return a 64-bit integer representing the value converted to the requested units
*/
virtual int64_t get_duration(std::string const& path, time_unit unit) const;
/**
* Clone the config with only the given path (and its children) retained;
* all sibling paths are removed.
* <p>
* Note that path expressions have a syntax and sometimes require quoting
* (see {@link config_util#join_path} and {@link config_util#split_path}).
*
* @param path
* path to keep
* @return a copy of the config minus all paths except the one specified
*/
virtual shared_config with_only_path(std::string const& path) const;
/**
* Clone the config with the given path removed.
* <p>
* Note that path expressions have a syntax and sometimes require quoting
* (see {@link config_util#join_path} and {@link config_util#split_path}).
*
* @param path
* path expression to remove
* @return a copy of the config minus the specified path
*/
virtual shared_config without_path(std::string const& path) const;
/**
* Places the config inside another {@code config} at the given path.
* <p>
* Note that path expressions have a syntax and sometimes require quoting
* (see {@link config_util#join_path} and {@link config_util#split_path}).
*
* @param path
* path expression to store this config at.
* @return a {@code config} instance containing this config at the given
* path.
*/
virtual shared_config at_path(std::string const& path) const;
/**
* Places the config inside a {@code config} at the given key. See also
* at_path(). Note that a key is NOT a path expression (see
* {@link config_util#join_path} and {@link config_util#split_path}).
*
* @param key
* key to store this config at.
* @return a {@code config} instance containing this config at the given
* key.
*/
virtual shared_config at_key(std::string const& key) const;
/**
* Returns a {@code config} based on this one, but with the given path set
* to the given value. Does not modify this instance (since it's immutable).
* If the path already has a value, that value is replaced. To remove a
* value, use withoutPath().
* <p>
* Note that path expressions have a syntax and sometimes require quoting
* (see {@link config_util#join_path} and {@link config_util#split_path}).
*
* @param path
* path expression for the value's new location
* @param value
* value at the new path
* @return the new instance with the new map entry
*/
virtual shared_config with_value(std::string const& path, std::shared_ptr<const config_value> value) const;
bool operator==(config const& other) const;
config(shared_object object);
static shared_object env_variables_as_config_object();
protected:
shared_value find(std::string const& path_expression, config_value::type expected) const;
shared_value find(path path_expression, config_value::type expected, path original_path) const;
shared_value find(path path_expression, config_value::type expected) const;
shared_config at_key(shared_origin origin, std::string const& key) const;
static shared_includer default_includer();
// TODO: memory and duration parsing
private:
/**
* Parses a duration string. If no units are specified in the string, it is assumed to be in
* milliseconds.
* Valid suffixes include ns, us, ms, s, m, h, and d. The units can also be specified as complete
* words (e.g. "seconds").
* @param input the string to parse
* @param origin_for_exception the origin of the value being parsed
* @param path_for_exception the path to the value being parsed
* @return the value parsed as a time_duration
*/
static duration parse_duration(std::string input, shared_origin origin_for_exception, std::string path_for_exception);
static duration convert(int64_t number, time_unit units);
static duration convert(double number, time_unit units);
static time_unit get_units(std::string const& unit_string);
duration get_duration(std::string const& path) const;
shared_value has_path_peek(std::string const& path_expression) const;
shared_value peek_path(path desired_path) const;
static void find_paths(std::set<std::pair<std::string, std::shared_ptr<const config_value>>>& entries,
path parent, shared_object obj);
static shared_value throw_if_null(shared_value v, config_value::type expected, path original_path);
static shared_value find_key(shared_object self, std::string const& key,
config_value::type expected, path original_path);
static shared_value find_key_or_null(shared_object self, std::string const& key,
config_value::type expected, path original_path);
static shared_value find_or_null(shared_object self, path desired_path,
config_value::type expected, path original_path);
shared_value find_or_null(std::string const& path_expression, config_value::type expected) const;
shared_value find_or_null(path path_expression, config_value::type expected, path original_path) const;
shared_object _object;
};
template<>
std::vector<int64_t> config::get_homogeneous_unwrapped_list(std::string const& path) const;
} // namespace hocon
|