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.javacomposer.internal;
020
021import static java.lang.String.format;
022import static org.apiguardian.api.API.Status.INTERNAL;
023import static org.tquadrat.foundation.lang.Objects.requireNonNullArgument;
024
025import java.util.Optional;
026
027import org.apiguardian.api.API;
028import org.tquadrat.foundation.annotation.ClassVersion;
029
030/**
031 *  A helper class holding the debug output that is added to the generated
032 *  code. This allows a quick reference to the source code that was responsible
033 *  for the generation of the respective element.
034 *
035 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
036 *  @version $Id: DebugOutput.java 1063 2023-09-26 15:14:16Z tquadrat $
037 *  @since 0.0.6
038 *
039 *  @UMLGraph.link
040 */
041@ClassVersion( sourceVersion = "$Id: DebugOutput.java 1063 2023-09-26 15:14:16Z tquadrat $" )
042@API( status = INTERNAL, since = "0.0.6" )
043public final class DebugOutput
044{
045        /*------------*\
046    ====** Attributes **=======================================================
047        \*------------*/
048    /**
049     *  The text for the debug output.
050     */
051    private final String m_Text;
052
053        /*--------------*\
054    ====** Constructors **=====================================================
055        \*--------------*/
056    /**
057     *  Creates a new {@code DebugOutput} instance.
058     *
059     *  @param  stackTraceElement   The stack trace element for the caller's
060     *      caller.
061     */
062    @SuppressWarnings( "OptionalUsedAsFieldOrParameterType" )
063    public DebugOutput( final Optional<StackTraceElement> stackTraceElement )
064    {
065        m_Text = requireNonNullArgument( stackTraceElement, "stackTraceElement" )
066            .map( ste -> format( "%1$s:%2$d", ste.getFileName(), ste.getLineNumber() ) )
067            .orElse( "Unknown Location" );
068    }   //  DebugOutput()
069
070        /*---------*\
071    ====** Methods **==========================================================
072        \*---------*/
073    /**
074     *  Returns the text for the debug output.
075     *
076     *  @return The comment.
077     */
078    public final String asComment() { return format( " /* [%s] */ ", m_Text ); }
079
080    /**
081     *  Returns the text for the debug output.
082     *
083     *  @return The text.
084     */
085    public final String asLiteral() { return format( " [%s] ", m_Text ); }
086
087    /**
088     *  {@inheritDoc}
089     */
090    @Override
091    public final String toString() { return asLiteral(); }
092}
093//  class DebugOutput
094
095/*
096 *  End of File
097 */