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 ninja.leaping.configurate.commented;
018
019import ninja.leaping.configurate.ConfigurationNode;
020import ninja.leaping.configurate.ConfigurationOptions;
021import org.checkerframework.checker.nullness.qual.NonNull;
022import org.checkerframework.checker.nullness.qual.Nullable;
023
024import java.util.List;
025import java.util.Map;
026import java.util.Optional;
027import java.util.function.Consumer;
028
029/**
030 * A configuration node that can have a comment attached to it.
031 */
032public interface CommentedConfigurationNode extends ConfigurationNode {
033
034    static @NonNull CommentedConfigurationNode root() {
035        return root(ConfigurationOptions.defaults());
036    }
037
038    static @NonNull CommentedConfigurationNode root(@NonNull Consumer<? super CommentedConfigurationNode> action) {
039        return root(ConfigurationOptions.defaults(), action);
040    }
041
042    static @NonNull CommentedConfigurationNode root(@NonNull ConfigurationOptions options) {
043        return new SimpleCommentedConfigurationNode(null, null, options);
044    }
045
046    static @NonNull CommentedConfigurationNode root(@NonNull ConfigurationOptions options, @NonNull Consumer<? super CommentedConfigurationNode> action) {
047        CommentedConfigurationNode ret = root(options);
048        action.accept(ret);
049        return ret;
050    }
051
052    /**
053     * Gets the current value for the comment.
054     *
055     * <p>If the comment contains multiple lines, the lines will be split by \n</p>
056     *
057     * @return The configuration's current comment
058     */
059    @NonNull
060    Optional<String> getComment();
061
062    /**
063     * Sets the comment for this configuration node.
064     *
065     * @param comment The comment to set. Line breaks should be represented as LFs (\n)
066     * @return this
067     */
068    @NonNull
069    CommentedConfigurationNode setComment(@Nullable String comment);
070
071    /**
072     * Set a comment on this node if it does not presently have a comment.
073     *
074     * The provided comment must not be null, because setting a null comment would be a no-op
075     *
076     * @param comment The comment to set. Line breaks should be represented as LFs (\n)
077     * @return this
078     */
079    @NonNull
080    default CommentedConfigurationNode setCommentIfAbsent(String comment) {
081        if (!getComment().isPresent()) { // backwards compat
082            setComment(comment);
083        }
084        return this;
085    }
086
087    // Methods from superclass overridden to have correct return types
088    @Nullable @Override CommentedConfigurationNode getParent();
089    @NonNull @Override List<? extends CommentedConfigurationNode> getChildrenList();
090    @NonNull @Override Map<Object, ? extends CommentedConfigurationNode> getChildrenMap();
091    @NonNull @Override CommentedConfigurationNode setValue(@Nullable Object value);
092    @NonNull @Override CommentedConfigurationNode mergeValuesFrom(@NonNull ConfigurationNode other);
093    @NonNull @Override @Deprecated CommentedConfigurationNode getAppendedNode();
094    @NonNull @Override default CommentedConfigurationNode appendListNode() {
095        return getAppendedNode();
096    }
097    @NonNull @Override CommentedConfigurationNode getNode(@NonNull Object... path);
098    @NonNull @Override CommentedConfigurationNode copy();
099
100    @Override
101    default CommentedConfigurationNode act(Consumer<? super ConfigurationNode> action) {
102        action.accept(this);
103        return this;
104    }
105}