/*
 * The contents of this file are subject to the terms of the Common Development and
 * Distribution License (the License). You may not use this file except in compliance with the
 * License.
 *
 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
 * specific language governing permission and limitations under the License.
 *
 * When distributing Covered Software, include this CDDL Header Notice in each file and include
 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
 * Header, with the fields enclosed by brackets [] replaced by your own identifying
 * information: "Portions copyright [year] [name of copyright owner]".
 *
 * Copyright 2014 ForgeRock AS.
 */

package org.forgerock.maven.plugins.xcite;

import java.util.StringTokenizer;
import java.util.regex.Pattern;

/**
 * A citation references part of a text file to quote.
 *
 * <p>
 *
 * The string representation includes the path to the file to cite,
 * and optionally start and end markers to frame the text to quote.
 *
 * <p>
 *
 * For example, {@code [/path/to/script.sh:# start:# end]}
 *
 * <p>
 *
 * Notice that the example has a UNIX-style path, {@code /path/to/script.sh},
 * a start marker, {@code # start}, and an end marker, {@code # end}.
 * The file, {@code script.sh}, could have text to quote between the markers.
 * For example, {@code script.sh} might have the following content:
 *
 * <pre>
 * #!/bin/bash
 *
 * # start
 * wall &lt;&lt;EOM
 *     Hello world
 * EOM
 * # end
 *
 * exit
 * </pre>
 *
 * In this case the quote would be the following:
 *
 * <pre>
 * wall &lt;&lt;EOM
 *     Hello world
 * EOM
 * </pre>
 *
 * Start and end markers depend on the language of the source text.
 * Markers should make sense to people who mark up the source text,
 * and so they should be composed of visible characters.
 * Markers must not include the delimiter character
 * that is used to separate the path and the markers.
 *
 * <p>
 *
 * Markers either both be on the same line as the text to quote,
 * or should be on separate lines from the text to quote.
 * In other words, you can prepare a text to quote a single line
 * either by adding a start marker on the line before
 * and an end marker on the line after,
 * or by prepending a start marker to the line before the text to quote
 * and appending an end marker after.
 *
 * <p>
 *
 * The following example shows markers on separate lines.
 *
 * <pre>
 * #start
 * This is the text to quote.
 * #end
 * </pre>
 *
 * <p>
 *
 * The following example shows markers on the same line as the text to quote.
 *
 * <pre>
 * #start This is the text to quote. #end
 * </pre>
 *
 * More formally, the citation string representation is as follows.
 *
 * <pre>
 *
 * citation     = "[" path delimiter start-marker delimiter end-marker "]"
 * citation     / "[" path delimiter start-marker "]"
 * citation     / "[" path "]"
 *
 * path         = File.getPath()                ; Depends on the OS,
 *                                              ; does not include delimiter
 *
 * delimiter    = ":" / "%"                     ; Default: ":"
 *
 * start-marker = 1*(VCHAR excluding delimiter) ; Depends on source language
 *
 * end-marker   = 1*(VCHAR excluding delimiter) ; Depends on source language
 *
 * </pre>
 *
 * Most systems allow file names that can cause problems with this scheme.
 * Working around the problem is an exercise for the reader.
 */
public class Citation {

    /**
     * Initial wrapper to open the citation string representation.
     */
    private static final String OPEN  = "[";

    /**
     * Final wrapper to close the citation string representation.
     */
    private static final String CLOSE = "]";

    private String path;        // Pathname for the file to quote
    private char   delimiter;   // Delimiter for path, markers
    private String start;       // Start marker
    private String end;         // End marker

    /**
     * Construct a citation from a path alone.
     *
     * <p>
     *
     * The path cannot be null.
     *
     * @param path      The pathname string for the file to quote. Not null.
     * @throws IllegalArgumentException Path is broken somehow.
     */
    public Citation(final String path) {
        build(path, ':', null, null);
    }

    /**
     * Construct a citation from a path, delimiter, and start marker,
     * when the start marker and the end marker are the same.
     *
     * <p>
     *
     * The path cannot be null.
     *
     * <p>
     *
     * The start marker cannot contain the delimiter.
     *
     * @param path      The pathname string for the file to quote. Not null.
     * @param delimiter The delimiter for path, markers.
     * @param start     The start marker. If null or "", only path is useful.
     * @throws IllegalArgumentException Path or marker is broken somehow.
     */
    public Citation(final String path, final char delimiter, final String start) {
        build(path, delimiter, start, null);
    }

    /**
     * Construct a citation from a path, delimiter, start marker, and end marker.
     *
     * <p>
     *
     * The path cannot be null.
     *
     * <p>
     *
     * The markers cannot contain the delimiter.
     *
     * @param path      The pathname string for the file to quote. Not null.
     * @param delimiter The delimiter for path, markers.
     * @param start     The start marker. If null or "", only path is useful.
     * @param end       The end marker. If null or "", {@code start} is both.
     * @throws IllegalArgumentException Path or marker is broken somehow.
     */
    public Citation(final String path, final char delimiter,
                    final String start, final String end) {
        build(path, delimiter, start, end);
    }

    /**
     * Builder for constructing an instance.
     *
     * @param path      The pathname string for the file to quote. Not null.
     * @param delimiter The delimiter for path, markers.
     * @param start     The start marker. If null or "", only path is useful.
     * @param end       The end marker. If null or "", {@code start} is both.
     * @throws IllegalArgumentException Path or marker is broken somehow.
     */
    private void build(final String path, final char delimiter,
                       final String start, final String end) {
        setPath(path);
        setDelimiter(delimiter);
        setStart(start);
        setEnd(end);
    }

    /**
     * Returns the value of the path.
     *
     * @return The value of the path.
     */
    public String getPath() {
        return this.path;
    }

    /**
     * Sets the pathname string for the file to quote.
     *
     * @param path The pathname string for the file to quote.
     * @throws IllegalArgumentException Path cannot be null.
     */
    public void setPath(final String path) {
        if (path == null) {
            throw new IllegalArgumentException("Path cannot be null.");
        } else {
            this.path = path;
        }
    }

    /**
     * Returns the value of the delimiter.
     *
     * @return The value of the delimiter.
     */
    public char getDelimiter() {
        return this.delimiter;
    }

    /**
     * Sets the value of the delimiter.
     *
     * @param delimiter The delimiter for path, markers.
     */
    public void setDelimiter(char delimiter) {
        if (delimiter == ':' || delimiter == '%') {
            this.delimiter = delimiter;
        } else {
            this.delimiter = ':';
        }
    }

    /**
     * Returns the value of the start marker, which can be empty.
     *
     * @return The value of the start marker, which can be empty.
     */
    public String getStart() {
        return this.start;
    }

    /**
     * Sets the value of the start marker, which must not contain the delimiter.
     *
     * @param start The value of the start marker.
     * @throws IllegalArgumentException Start marker contains the delimiter.
     */
    public void setStart(String start) {
        if (isNullOrEmpty(start)) {
            this.start = "";
        } else if (!start.contains(Character.toString(getDelimiter()))) {
            this.start = start;
        } else {
            throw new IllegalArgumentException("Start marker: " + start
                    + " contains delimiter: " + getDelimiter());
        }
    }

    /**
     * Returns the value of the start marker, which can be empty.
     *
     * @return The value of the start marker, which can be empty.
     */
    public String getEnd() {
        return this.end;
    }

    /**
     * Sets the value of the end marker, which must not contain the delimiter.
     *
     * @param end The value of the end marker.
     * @throws IllegalArgumentException End marker contains the delimiter.
     */
    public void setEnd(String end) {
        if (isNullOrEmpty(end)) {
            this.end = getStart();
        } else if (!end.contains(Character.toString(getDelimiter()))) {
            this.end = end;
        } else {
            throw new IllegalArgumentException("End marker: " + end
                    + " contains delimiter: " + getDelimiter());
        }
    }

    /**
     * Returns true if the string is null or the string is empty.
     *
     * @param string The string.
     * @return Whether the string is null or empty.
     */
    private static boolean isNullOrEmpty(final String string) {
        return (string == null || string.isEmpty());
    }

    /**
     * Returns the string representation of this citation.
     *
     * @return The string representation of this citation.
     */
    public String toString() {
        String start =
                (isNullOrEmpty(getStart()) ? "" : getDelimiter() + getStart());

        String end;
        if (isNullOrEmpty(getStart()) || isNullOrEmpty(getEnd())) {
            end = "";
        } else {
            end = getDelimiter() + getEnd();
        }

        return OPEN + getPath() + start + end + CLOSE;
    }

    /**
     * Returns a Citation from the string representation.
     *
     * @param citation  The string representation.
     * @param delimiter One of ":" or "%".
     * @return A Citation corresponding to the string representation,
     *         or null if the string representation does not parse.
     */
    public static Citation valueOf(final String citation, final String delimiter) {

        // No null delimiters.
        if (delimiter == null) {
            return null;
        }

        // No illegal delimiters.
        if (!(delimiter.equals(":") || delimiter.equals("%"))) {
            return null;
        }

        // OPEN marks the start of the citation string.
        if (!citation.startsWith(OPEN)) {
            return null;
        }

        // CLOSE marks the end of the citation string.
        if (!citation.endsWith(CLOSE)) {
            return null;
        }

        // Remove the OPEN & CLOSE wrappers.
        String unwrapped = citation
                .replaceFirst(Pattern.quote(OPEN), "")
                .replaceFirst(Pattern.quote(CLOSE), "");

        // Starting with a delimiter means path is null.
        if (unwrapped.startsWith(delimiter)) {
            return null;
        }

        // Delimiters should delimit actual values, not empty strings.
        if (unwrapped.contains(delimiter + delimiter)) {
            return null;
        }

        // Tokenize using the delimiter, as values do not contain the delimiter.
        StringTokenizer st = new StringTokenizer(unwrapped, delimiter);
        String path  = null;
        String start = null;
        String end   = null;

        if (st.hasMoreTokens()) {    // path
            path = st.nextToken();
        }
        if (st.hasMoreTokens()) {    // start
            start = st.nextToken();
        }
        if (st.hasMoreTokens()) {    // end
            end = st.nextToken();
        }
        if (st.hasMoreTokens()) {
            return null;
        }

        // Path must not be null.
        if (isNullOrEmpty(path)) {
            return null;
        }

        return new Citation(path, ':', start, end);
    }

    /**
     * Returns a Citation from the string representation,
     * assuming the default delimiter, {@code :}.
     *
     * @param citation The string representation.
     * @return A Citation corresponding to the string representation,
     *         or null if the string representation does not parse.
     */
    public static Citation valueOf(final String citation) {
        return valueOf(citation, ":");
    }
}