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.checkerframework.checker.nullness.qual.Nullable;
020
021/**
022 * Intermediate interface for different types of commented configuration nodes.
023 *
024 * @param <N> self type
025 * @since 4.0.0
026 */
027public interface CommentedConfigurationNodeIntermediary<N extends CommentedConfigurationNodeIntermediary<N>> extends ScopedConfigurationNode<N> {
028
029    /**
030     * Gets the current value for the comment.
031     *
032     * <p>If the comment contains multiple lines, the lines will be split
033     * by \n</p>
034     *
035     * @return the configuration's current comment
036     * @since 4.0.0
037     */
038    @Nullable String comment();
039
040    /**
041     * Sets the comment for this configuration node.
042     *
043     * @param comment the comment to set. Line breaks should be represented as
044     *                LFs (\n)
045     * @return this node
046     * @since 4.0.0
047     */
048    N comment(@Nullable String comment);
049
050    /**
051     * Set a comment on this node if it does not presently have a comment.
052     *
053     * <p>The provided comment must not be null, because setting a null comment
054     * would be a no-op</p>
055     *
056     * @param comment the comment to set. Line breaks should be represented as
057     *                LFs (\n)
058     * @return this node
059     * @since 4.0.0
060     */
061    N commentIfAbsent(String comment);
062
063}