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}