001/*
002 * Configurate
003 * Copyright (C) zml and Configurate contributors
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *    http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.spongepowered.configurate;
018
019import org.spongepowered.configurate.util.CheckedConsumer;
020
021/**
022 * A configuration node that can have a comment attached to it.
023 *
024 * <p>All other standard data is supported.</p>
025 *
026 * @since 4.0.0
027 */
028public interface CommentedConfigurationNode extends CommentedConfigurationNodeIntermediary<CommentedConfigurationNode> {
029
030    /**
031     * Create a new factory providing {@link CommentedConfigurationNode} instances.
032     *
033     * <p>The returned factory will create nodes with default options.</p>
034     *
035     * @return a new factory
036     * @since 4.0.0
037     */
038    static ConfigurationNodeFactory<CommentedConfigurationNode> factory() {
039        return CommentedConfigurationNode::root;
040    }
041
042    /**
043     * Create a new empty root node.
044     *
045     * <p>This node will use the {@link ConfigurationOptions#defaults() default options}</p>
046     *
047     * <p>A root node is always attached, and has no parent and an
048     * empty path.</p>
049     *
050     * @return a new empty node
051     * @since 4.0.0
052     */
053    static CommentedConfigurationNode root() {
054        return root(ConfigurationOptions.defaults());
055    }
056
057    /**
058     * Create a new root node with the provided initializer.
059     *
060     * <p>This node will use the {@link ConfigurationOptions#defaults() default options}</p>
061     *
062     * <p>A root node is always attached, and has no parent and an
063     * empty path.</p>
064     *
065     * @param <E> thrown type
066     * @param action action to be applied to the newly created node
067     * @return a new initialized node
068     * @throws E when thrown from inner action
069     * @since 4.0.0
070     */
071    static <E extends Exception> CommentedConfigurationNode root(final CheckedConsumer<? super CommentedConfigurationNode, E> action) throws E {
072        return root().act(action);
073    }
074
075    /**
076     * Create a new empty root node with the provided options.
077     *
078     * <p>A root node is always attached, and has no parent and an
079     * empty path.</p>
080     *
081     * @param options options to apply
082     * @return a new empty node
083     * @since 4.0.0
084     */
085    static CommentedConfigurationNode root(final ConfigurationOptions options) {
086        return new CommentedConfigurationNodeImpl(null, null, options);
087    }
088
089    /**
090     * Create a new root node with the provided options and initializer.
091     *
092     * <p>A root node is always attached, and has no parent and an
093     * empty path.</p>
094     *
095     * @param <E> thrown type
096     * @param options options to apply
097     * @param action action to be applied to the newly created node
098     * @return a new initialized node
099     * @throws E when thrown from inner action
100     * @since 4.0.0
101     */
102    static <E extends Exception> CommentedConfigurationNode root(final ConfigurationOptions options,
103            final CheckedConsumer<? super CommentedConfigurationNode, E> action) throws E {
104        return root(options).act(action);
105    }
106
107}