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