1 #pragma once
2 
3 #include "types.hpp"
4 #include <string>
5 #include <memory>
6 #include "export.h"
7 
8 namespace hocon {
9     /**
10      * Implement this interface and provide an instance to
11      * {@link config_parse_options#set_includer config_parse_options.set_includer()} to
12      * customize handling of {@code include} statements in config files. You may
13      * also want to implement {@link config_includer_file} and {@link config_includer_URL}, or not.
14      */
15     class LIBCPP_HOCON_EXPORT config_includer {
16     public:
17         /**
18          * Returns a new includer that falls back to the given includer. This is how
19          * you can obtain the default includer; it will be provided as a fallback.
20          * It's up to your includer to chain to it if you want to. You might want to
21          * merge any files found by the fallback includer with any objects you load
22          * yourself.
23          *
24          * It's important to handle the case where you already have the fallback
25          * with a "return this", i.e. this method should not create a new object if
26          * the fallback is the same one you already have. The same fallback may be
27          * added repeatedly.
28          *
29          * @param fallback the previous includer for chaining
30          * @return a new includer
31          */
32         virtual shared_includer with_fallback(shared_includer fallback) const = 0;
33 
34         /**
35          * Parses another item to be included. The returned object typically would
36          * not have substitutions resolved. You can throw a config_exception here to
37          * abort parsing, or return an empty object, but may not return null.
38          *
39          * This method is used for a "heuristic" include statement that does not
40          * specify file, or URL resource. If the include statement does
41          * specify, then the same class implementing {@link config_includer} must
42          * also implement {@link config_includer_file} or {@link config_includer_URL} as needed, or a
43          * default includer will be used.
44          *
45          * @param context
46          *            some info about the include context
47          * @param what
48          *            the include statement's argument
49          * @return a non-null config_object
50          */
51         virtual shared_object include(shared_include_context context, std::string what) const = 0;
52     };
53 }  // namespace hocon
54