001/*
002 * ============================================================================
003 * Copyright © 2002-2023 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 *
007 * Licensed to the public under the agreements of the GNU Lesser General Public
008 * License, version 3.0 (the "License"). You may obtain a copy of the License at
009 *
010 *      http://www.gnu.org/licenses/lgpl.html
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
014 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
015 * License for the specific language governing permissions and limitations
016 * under the License.
017 */
018
019package org.tquadrat.foundation.util.stringconverter;
020
021import static java.lang.String.format;
022import static org.apiguardian.api.API.Status.STABLE;
023import static org.tquadrat.foundation.lang.Objects.isNull;
024import static org.tquadrat.foundation.lang.Objects.nonNull;
025
026import java.io.Serial;
027import java.util.regex.Pattern;
028import java.util.regex.PatternSyntaxException;
029
030import org.apiguardian.api.API;
031import org.tquadrat.foundation.annotation.ClassVersion;
032import org.tquadrat.foundation.lang.StringConverter;
033
034/**
035 *  An implementation of
036 *  {@link StringConverter}
037 *  for regular expressions that are stored as
038 *  {@link Pattern}
039 *  values.
040 *
041 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
042 *  @version $Id: PatternStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $
043 *  @since 0.0.6
044 *
045 *  @UMLGraph.link
046 */
047@ClassVersion( sourceVersion = "$Id: PatternStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $" )
048@API( status = STABLE, since = "0.0.6" )
049public final class PatternStringConverter implements StringConverter<Pattern>
050{
051        /*-----------*\
052    ====** Constants **========================================================
053        \*-----------*/
054    /**
055     *  The error message about an invalid regular expression: {@value}.
056     */
057    public static final String MSG_InvalidExpression = "'%1$s' is not a valid regular expression";
058
059        /*------------------------*\
060    ====** Static Initialisations **===========================================
061        \*------------------------*/
062    /**
063     *  The serial version UID for objects of this class: {@value}.
064     *
065     *  @hidden
066     */
067    @Serial
068    private static final long serialVersionUID = 1L;
069
070    /**
071     *  An instance of this class.
072     */
073    public static final PatternStringConverter INSTANCE = new PatternStringConverter();
074
075        /*--------------*\
076    ====** Constructors **=====================================================
077        \*--------------*/
078    /**
079     *  Creates a new instance of {@code PatternStringConverter}.
080     */
081    public PatternStringConverter() {}
082
083        /*---------*\
084    ====** Methods **==========================================================
085        \*---------*/
086    /**
087     *  {@inheritDoc}
088     */
089    @Override
090    public final Pattern fromString( final CharSequence source ) throws IllegalArgumentException
091    {
092        Pattern retValue = null;
093        if( nonNull( source ) )
094        {
095            try
096            {
097                retValue = Pattern.compile( source.toString() );
098            }
099            catch( final PatternSyntaxException e )
100            {
101                throw new IllegalArgumentException( format( MSG_InvalidExpression, source ), e );
102            }
103        }
104
105        //---* Done *----------------------------------------------------------
106        return retValue;
107    }   //  fromString()
108
109    /**
110     *  This method is used by the
111     *  {@link java.util.ServiceLoader}
112     *  to obtain the instance for this
113     *  {@link org.tquadrat.foundation.lang.StringConverter}
114     *  implementation.
115     *
116     *  @return The instance for this {@code StringConverter} implementation.
117     */
118    public static final PatternStringConverter provider() { return INSTANCE; }
119
120    /**
121     *  {@inheritDoc}
122     */
123    @Override
124    public final String toString( final Pattern source )
125    {
126        final var retValue = isNull( source ) ? null : source.pattern();
127
128        //---* Done *----------------------------------------------------------
129        return retValue;
130    }   //  toString()
131}
132//  class PatternStringConverter
133
134/*
135 *  End of File
136 */