001    /*
002     * Jpkg - Java library and tools for operating system package creation.
003     *
004     * Copyright (c) 2007 Three Rings Design, Inc.
005     * All rights reserved.
006     *
007     * Redistribution and use in source and binary forms, with or without
008     * modification, are permitted provided that the following conditions
009     * are met:
010     * 1. Redistributions of source code must retain the above copyright
011     *    notice, this list of conditions and the following disclaimer.
012     * 2. Redistributions in binary form must reproduce the above copyright
013     *    notice, this list of conditions and the following disclaimer in the
014     *    documentation and/or other materials provided with the distribution.
015     * 3. Neither the name of the copyright owner nor the names of contributors
016     *    may be used to endorse or promote products derived from this software
017     *    without specific prior written permission.
018     *
019     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
020     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
021     * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
022     * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
023     * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
024     * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
025     * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
026     * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
027     * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
028     * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
029     * POSSIBILITY OF SUCH DAMAGE.
030     */
031    package com.threerings.jpkg.debian;
032    
033    /**
034     * Holds and parses the Debian package description.
035     * @see <a href="http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Description">Debian Policy Manual</a>
036     */
037    public class PackageDescription
038        implements ControlFileData
039    {
040        /**
041         * Construct a new PackageDescription with the supplied text for the brief initial part of the
042         * description. This is recommended to be under 80 characters. If the string contains any
043         * new lines or tabs, a ControlDataInvalidException will be thrown.
044         * @throws ControlDataInvalidException
045         */
046        public PackageDescription (String description)
047            throws ControlDataInvalidException
048        {
049            _shortDesc = validateWhitespace(description);
050            _extendedDesc = new StringBuilder();
051        }
052    
053        // from ControlFileData
054        public String getField ()
055        {
056            return "Description";
057        }
058    
059        // from ControlFileData
060        public String getFieldValue ()
061        {
062            if (_extendedDesc.length() > 0) {
063                return _shortDesc + "\n" + _extendedDesc.toString();
064    
065            } else {
066                return _shortDesc;
067            }
068        }
069    
070        /**
071         * Append a line of text to the extended package description. This line will be word wrapped by
072         * any Debian tool displaying the package description.
073         * If the line contains any new lines or tabs, a ControlDataInvalidException will be thrown.
074         */
075        public void addParagraph (String line)
076            throws ControlDataInvalidException
077        {
078            validateWhitespace(line);
079            addNewLineIfNeeded();
080            // new paragraphs must begin with a blank space.
081            _extendedDesc.append(' ').append(line);
082        }
083    
084        /**
085         * Append a line of text to the extended package description. This line will be NOT be word
086         * wrapped by any Debian tool displaying the package description.
087         * If the line contains any new lines or tabs, a ControlDataInvalidException will be thrown.
088         */
089        public void addVerbatimParagraph (String line)
090            throws ControlDataInvalidException
091        {
092            validateWhitespace(line);
093            addNewLineIfNeeded();
094            // new verbatim lines must begin with two blank spaces.
095            _extendedDesc.append(' ').append(' ').append(line);
096        }
097    
098        /**
099         * Append a blank new line to the extended description.
100         */
101        public void addBlankLine ()
102        {
103            addNewLineIfNeeded();
104            _extendedDesc.append(" .");
105        }
106    
107        /**
108         * Validates that the supplied string does not contain spaces or tabs.
109         */
110        private String validateWhitespace (String text)
111            throws ControlDataInvalidException
112        {
113            if (text.contains("\n") || text.contains("\t")) {
114                throw new ControlDataInvalidException(
115                    "Description text cannot contain newlines or tabs. text=[" + text + "].");
116            }
117            return text;
118        }
119    
120        /**
121         * Adds a new line character to the extended description if needed.
122         */
123        private void addNewLineIfNeeded ()
124        {
125            if (_extendedDesc.length() > 0) {
126                _extendedDesc.append("\n");
127            }
128        }
129    
130        /** The package short description, should be less than 80 characters. */
131        private final String _shortDesc;
132    
133        /** The package extended description. */
134        private final StringBuilder _extendedDesc;
135    }