001/*
002 * ============================================================================
003 *  Copyright © 2002-2024 by Thomas Thrien.
004 *  All Rights Reserved.
005 * ============================================================================
006 *  Licensed to the public under the agreements of the GNU Lesser General Public
007 *  License, version 3.0 (the "License"). You may obtain a copy of the License at
008 *
009 *       http://www.gnu.org/licenses/lgpl.html
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, WITHOUT
013 *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
014 *  License for the specific language governing permissions and limitations
015 *  under the License.
016 */
017
018package org.tquadrat.foundation.inifile.internal;
019
020import static java.lang.Integer.signum;
021import static java.lang.String.format;
022import static org.apiguardian.api.API.Status.INTERNAL;
023import static org.apiguardian.api.API.Status.MAINTAINED;
024import static org.apiguardian.api.API.Status.STABLE;
025import static org.tquadrat.foundation.inifile.internal.INIFileImpl.breakString;
026import static org.tquadrat.foundation.inifile.internal.INIFileImpl.splitComment;
027import static org.tquadrat.foundation.lang.CommonConstants.EMPTY_STRING;
028import static org.tquadrat.foundation.lang.Objects.hash;
029import static org.tquadrat.foundation.lang.Objects.isNull;
030import static org.tquadrat.foundation.lang.Objects.requireNonNullArgument;
031import static org.tquadrat.foundation.lang.Objects.requireNotBlankArgument;
032import static org.tquadrat.foundation.lang.Objects.requireValidArgument;
033import static org.tquadrat.foundation.util.StringUtils.isNotEmptyOrBlank;
034
035import java.util.StringJoiner;
036import java.util.function.Predicate;
037
038import org.apiguardian.api.API;
039import org.tquadrat.foundation.annotation.ClassVersion;
040import org.tquadrat.foundation.lang.Objects;
041
042/**
043 *  The container for the value of an INI file.
044 *
045 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
046 *  @version $Id: Value.java 1134 2024-05-20 16:53:16Z tquadrat $
047 *
048 *  @UMLGraph.link
049 *  @since 0.1.0
050 */
051@SuppressWarnings( "NewClassNamingConvention" )
052@ClassVersion( sourceVersion = "$Id: Value.java 1134 2024-05-20 16:53:16Z tquadrat $" )
053@API( status = INTERNAL, since = "0.1.0" )
054public final class Value implements Comparable<Value>
055{
056        /*------------*\
057    ====** Attributes **=======================================================
058        \*------------*/
059    /**
060     *  The comment for this value.
061     */
062    @SuppressWarnings( "StringBufferField" )
063    private final StringBuilder m_Comment = new StringBuilder();
064
065    /**
066     *  The reference to the parent group.
067     */
068    @SuppressWarnings( "UseOfConcreteClass" )
069    private final Group m_Group;
070
071    /**
072     *  The key.
073     */
074    private final String m_Key;
075
076    /**
077     *  The value itself.
078     */
079    private String m_Value;
080
081        /*--------------*\
082    ====** Constructors **=====================================================
083        \*--------------*/
084    /**
085     *  Creates a new instance of {@code Value}.
086     *
087     *  @param  parent  The parent group.
088     *  @param  key The key.
089     */
090    @SuppressWarnings( "UseOfConcreteClass" )
091    public Value( final Group parent, final String key )
092    {
093        m_Group = requireNonNullArgument( parent, "parent" );
094        m_Key = requireValidArgument( key, "key", Value::checkKeyCandidate );
095    }   //  Value()
096
097    /**
098     *  Creates a new instance of {@code Value}.
099     *
100     *  @param  parent  The parent group.
101     *  @param  key The key.
102     *  @param  value   The value.
103     */
104    @SuppressWarnings( "UseOfConcreteClass" )
105    public Value( final Group parent, final String key, final String value )
106    {
107        this( parent, key );
108        setValue( value );
109    }   //  Value()
110
111        /*---------*\
112    ====** Methods **==========================================================
113        \*---------*/
114    /**
115     *  Adds a comment to the value.
116     *
117     *  @param  comment The comment.
118     */
119    public final void addComment( final String comment )
120    {
121        if( isNotEmptyOrBlank( comment ) ) m_Comment.append( comment );
122    }   //  addComment()
123
124    /**
125     *  <p>{@summary An implementation of
126     *  {@link Predicate }
127     *  to be used with
128     *  {@link org.tquadrat.foundation.lang.Objects#requireValidArgument(Object,String,Predicate)}
129     *  when checking the keys for new values.}</p>
130     *  <p>The candidate may not begin with a hash symbol ('#') or an opening
131     *  bracket ('['), and it may not contain newline characters, tab
132     *  characters or equal signs.</p>
133     *  <p>You should avoid hash symbols and opening brackets completely, even
134     *  inside or at the end of the key, as well as closing brackets (']'),
135     *  despite they are technically valid.</p>
136     *
137     *  @param  candidate   The key to check.
138     *  @return {@code true} if the value is a valid key, {@code false}
139     *      otherwise.
140     *  @throws org.tquadrat.foundation.exception.NullArgumentException The
141     *      candidate is {@code null}.
142     *  @throws org.tquadrat.foundation.exception.EmptyArgumentException    The
143     *      candidate is the empty string.
144     *  @throws org.tquadrat.foundation.exception.BlankArgumentException    The
145     *      candidate consists of whitespace only.
146     *
147     *  @since 0.4.4
148     */
149    @API( status = INTERNAL, since = "0.4.4" )
150    public static final boolean checkKeyCandidate( final String candidate )
151    {
152        var retValue = requireNotBlankArgument( candidate, "candidate" ).indexOf( '=' ) < 0;
153        if( retValue ) retValue = candidate.indexOf( '\n' ) < 0;
154        if( retValue ) retValue = candidate.indexOf( '\t' ) < 0;
155        if( retValue ) retValue = !candidate.trim().startsWith( "#" );
156        if( retValue ) retValue = !candidate.trim().startsWith( "[" );
157
158        //---* Done *----------------------------------------------------------
159        return retValue;
160    }   //  checkKeyCandidate()
161
162    /**
163     *  {@inheritDoc}
164     *
165     *  @since 0.4.2
166     */
167    @SuppressWarnings( "CompareToUsesNonFinalVariable" )
168    @API( status = MAINTAINED, since = "0.4.2" )
169    @Override
170    public int compareTo( final Value o )
171    {
172        var retValue = m_Group.compareTo( o.m_Group );
173        if( retValue == 0) retValue = signum( m_Key.compareTo( o.m_Key ) );
174        if( retValue == 0) retValue = signum( m_Value.compareTo( o.m_Value ) );
175
176        //---* Done *----------------------------------------------------------
177        return retValue;
178    }   //  compareTo()
179
180    /**
181     *  {@inheritDoc}
182     */
183    @SuppressWarnings( {"EqualsOnSuspiciousObject", "NonFinalFieldReferenceInEquals"} )
184    @Override
185    public final boolean equals( final Object o )
186    {
187        var retValue = (this == o);
188        if( !retValue && o instanceof final Value other )
189        {
190            retValue = m_Comment.equals( other.m_Comment )
191                && m_Group.equals( other.m_Group )
192                && m_Key.equals( other.m_Key )
193                && Objects.equals( m_Value, other.m_Value );
194        }
195
196        //---* Done *----------------------------------------------------------
197        return retValue;
198    }   //  equals()
199
200    /**
201     *  Returns the current value.
202     *
203     *  @return The current value; can be {@code null}.
204     */
205    public final String getValue() { return m_Value; }
206
207    /**
208     *  {@inheritDoc}
209     */
210    @SuppressWarnings( "NonFinalFieldReferencedInHashCode" )
211    @Override
212    public final int hashCode() { return hash( m_Comment, m_Group, m_Key, m_Value ); }
213
214    /**
215     *  <p>{@summary Sets a comment to the group.}</p>
216     *  <p>Any previously existing comment will be overwritten.</p>
217     *
218     *  @param  comment The comment.
219     *
220     *  @since 0.4.2
221     */
222    @API( status = STABLE, since = "0.4.3" )
223    public final void setComment( final String comment )
224    {
225        m_Comment.setLength( 0 );
226        addComment( comment );
227    }   //  setComment()
228
229    /**
230     *  Sets a new value.
231     *
232     *  @param  value   The new value; can be {@code null}.
233     */
234    public final void setValue( final String value ) { m_Value = value; }
235
236    /**
237     *  {@inheritDoc}
238     */
239    @Override
240    public final String toString()
241    {
242        final var buffer = new StringJoiner( "\n", EMPTY_STRING, "\n" );
243        if( !m_Comment.isEmpty() )
244        {
245            buffer.add( EMPTY_STRING );
246            splitComment( m_Comment ).forEach( buffer::add );
247        }
248        final var value = isNull( m_Value )
249            ? EMPTY_STRING
250            : m_Value.endsWith( " " )
251                ? m_Value.substring( 0, m_Value.length() - 1 ).concat( "\\s" )
252                : m_Value;
253        breakString( format( "%s = %s", m_Key, isNull( m_Value ) ? EMPTY_STRING : value ) )
254            .forEach( buffer::add );
255        final var retValue = buffer.toString();
256
257        //---* Done *----------------------------------------------------------
258        return retValue;
259    }   //  toString()
260}
261//  class Value
262
263/*
264 *  End of File
265 */