001    /*
002     *   Copyright (c) 2009 The JOMC Project
003     *   Copyright (c) 2005 Christian Schulte <cs@jomc.org>
004     *   All rights reserved.
005     *
006     *   Redistribution and use in source and binary forms, with or without
007     *   modification, are permitted provided that the following conditions
008     *   are met:
009     *
010     *     o Redistributions of source code must retain the above copyright
011     *       notice, this list of conditions and the following disclaimer.
012     *
013     *     o Redistributions in binary form must reproduce the above copyright
014     *       notice, this list of conditions and the following disclaimer in
015     *       the documentation and/or other materials provided with the
016     *       distribution.
017     *
018     *   THIS SOFTWARE IS PROVIDED BY THE JOMC PROJECT AND CONTRIBUTORS "AS IS"
019     *   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
020     *   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
021     *   PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE JOMC PROJECT OR
022     *   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
023     *   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
024     *   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
025     *   OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
026     *   WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
027     *   OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
028     *   ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
029     *
030     *   $Id: SectionEditor.java 641 2009-10-02 16:35:24Z schulte2005 $
031     *
032     */
033    package org.jomc.util;
034    
035    import java.io.IOException;
036    import java.text.MessageFormat;
037    import java.util.ResourceBundle;
038    import java.util.Stack;
039    
040    /**
041     * Interface to section based editing.
042     * <p>Section based editing is a two phase process of parsing the editor's input into a corresponding hierarchy of
043     * {@code Section} instances, followed by rendering the parsed sections to produce the output of the editor. Method
044     * {@code editLine} returns {@code null} during parsing and the output of the editor on end of input, rendered by
045     * calling method {@code getOutput}. Parsing is backed by methods {@code getSection} and {@code isSectionFinished}.</p>
046     *
047     * @author <a href="mailto:cs@jomc.org">Christian Schulte</a>
048     * @version $Id: SectionEditor.java 641 2009-10-02 16:35:24Z schulte2005 $
049     *
050     * @see #edit(java.lang.String)
051     */
052    public class SectionEditor extends LineEditor
053    {
054    
055        /** Marker indicating the start of a section. */
056        private static final String DEFAULT_SECTION_START = "SECTION-START[";
057    
058        /** Marker indicating the end of a section. */
059        private static final String DEFAULT_SECTION_END = "SECTION-END";
060    
061        /** Stack of sections. */
062        private Stack<Section> stack;
063    
064        /** Creates a new {@code SectionEditor} instance. */
065        public SectionEditor()
066        {
067            super();
068        }
069    
070        /**
071         * Creates a new {@code SectionEditor} instance taking a string to use for separating lines.
072         *
073         * @param lineSeparator String to use for separating lines.
074         */
075        public SectionEditor( final String lineSeparator )
076        {
077            super( lineSeparator );
078        }
079    
080        /**
081         * Creates a new {@code SectionEditor} instance taking an editor to chain.
082         *
083         * @param editor The editor to chain.
084         */
085        public SectionEditor( final LineEditor editor )
086        {
087            super( editor );
088        }
089    
090        /**
091         * Creates a new {@code SectionEditor} instance taking an editor to chain and a string to use for separating lines.
092         *
093         * @param editor The editor to chain.
094         * @param lineSeparator String to use for separating lines.
095         */
096        public SectionEditor( final LineEditor editor, final String lineSeparator )
097        {
098            super( editor, lineSeparator );
099        }
100    
101        @Override
102        protected final String editLine( final String line ) throws IOException
103        {
104            if ( this.stack == null )
105            {
106                final Section root = new Section();
107                root.setMode( Section.MODE_HEAD );
108                this.stack = new Stack<Section>();
109                this.stack.push( root );
110            }
111    
112            Section current = this.stack.peek();
113            String replacement = null;
114    
115            if ( line != null )
116            {
117                final Section child = this.getSection( line );
118    
119                if ( child != null )
120                {
121                    child.setStartingLine( line );
122                    child.setMode( Section.MODE_HEAD );
123    
124                    if ( current.getMode() == Section.MODE_TAIL && current.getTailContent().length() > 0 )
125                    {
126                        final Section s = new Section();
127                        s.getHeadContent().append( current.getTailContent() );
128                        current.getTailContent().setLength( 0 );
129                        current.getSections().add( s );
130                        current = s;
131                        this.stack.push( current );
132                    }
133    
134                    current.getSections().add( child );
135                    current.setMode( Section.MODE_TAIL );
136                    this.stack.push( child );
137                }
138                else if ( this.isSectionFinished( line ) )
139                {
140                    this.stack.pop().setEndingLine( line );
141                    if ( this.stack.peek().getName() == null && this.stack.size() > 1 )
142                    {
143                        this.stack.pop();
144                    }
145                }
146                else
147                {
148                    switch ( current.getMode() )
149                    {
150                        case Section.MODE_HEAD:
151                            current.getHeadContent().append( line ).append( this.getLineSeparator() );
152                            break;
153    
154                        case Section.MODE_TAIL:
155                            current.getTailContent().append( line ).append( this.getLineSeparator() );
156                            break;
157    
158                        default:
159                            throw new AssertionError( current.getMode() );
160    
161                    }
162                }
163            }
164            else
165            {
166                final Section root = this.stack.pop();
167    
168                if ( !this.stack.isEmpty() )
169                {
170                    this.stack = null;
171                    throw new IOException( this.getMessage( "unexpectedEndOfSection", new Object[]
172                        {
173                            root.getName() == null ? "/" : root.getName()
174                        } ) );
175    
176                }
177    
178                replacement = this.getOutput( root );
179                this.stack = null;
180            }
181    
182            return replacement;
183        }
184    
185        /**
186         * Parses the given line to mark the start of a new section.
187         *
188         * @param line The line to parse.
189         *
190         * @return The section starting at {@code line} or {@code null} if {@code line} does not mark the start of a
191         * section.
192         */
193        protected Section getSection( final String line )
194        {
195            Section s = null;
196    
197            if ( line != null )
198            {
199                final int startIndex = line.indexOf( DEFAULT_SECTION_START );
200                if ( startIndex != -1 )
201                {
202                    final String name = line.substring( startIndex + DEFAULT_SECTION_START.length(),
203                                                        line.indexOf( ']', startIndex + DEFAULT_SECTION_START.length() ) );
204    
205                    s = new Section();
206                    s.setName( name );
207                }
208            }
209    
210            return s;
211        }
212    
213        /**
214         * Parses the given line to mark the end of a section.
215         *
216         * @param line The line to parse.
217         *
218         * @return {@code true} if {@code line} marks the end of a section; {@code false} if {@code line} does not mark the
219         * end of a section.
220         */
221        protected boolean isSectionFinished( final String line )
222        {
223            return line != null && line.indexOf( DEFAULT_SECTION_END ) != -1;
224        }
225    
226        /**
227         * Edits a section.
228         * <p>This method does not change any content by default. Overriding classes may use this method for editing
229         * sections prior to rendering.</p>
230         *
231         * @param section The section to edit.
232         *
233         * @throws NullPointerException if {@code section} is {@code null}.
234         * @throws IOException if editing fails.
235         */
236        protected void editSection( final Section section ) throws IOException
237        {
238            if ( section == null )
239            {
240                throw new NullPointerException( "section" );
241            }
242        }
243    
244        /**
245         * Edits a section recursively.
246         *
247         * @param section The section to edit recursively.
248         *
249         * @throws NullPointerException if {@code section} is {@code null}.
250         * @throws IOException if editing fails.
251         */
252        private void editSections( final Section section ) throws IOException
253        {
254            if ( section == null )
255            {
256                throw new NullPointerException( "section" );
257            }
258    
259            this.editSection( section );
260            for ( Section child : section.getSections() )
261            {
262                this.editSections( child );
263            }
264        }
265    
266        /**
267         * Gets the output of the editor.
268         * <p>This method calls method {@code editSection()} for each section of the editor prior to rendering the sections
269         * to produce the output of the editor.</p>
270         *
271         * @param section The section to start rendering the editor's output with.
272         *
273         * @return The output of the editor.
274         *
275         * @throws NullPointerException if {@code section} is {@code null}.
276         * @throws IOException if editing or rendering fails.
277         */
278        protected String getOutput( final Section section ) throws IOException
279        {
280            if ( section == null )
281            {
282                throw new NullPointerException( "section" );
283            }
284    
285            this.editSections( section );
286            return this.renderSections( section, new StringBuilder() ).toString();
287        }
288    
289        /**
290         * Appends the content of a given section to a given buffer.
291         *
292         * @param section The section to render.
293         * @param buffer The buffer to append the content of {@code section} to.
294         *
295         * @return {@code buffer} with content of {@code section} appended.
296         */
297        private StringBuilder renderSections( final Section section, final StringBuilder buffer )
298        {
299            if ( section.getStartingLine() != null )
300            {
301                buffer.append( section.getStartingLine() ).append( this.getLineSeparator() );
302            }
303    
304            buffer.append( section.getHeadContent() );
305    
306            for ( Section child : section.getSections() )
307            {
308                this.renderSections( child, buffer );
309            }
310    
311            buffer.append( section.getTailContent() );
312    
313            if ( section.getEndingLine() != null )
314            {
315                buffer.append( section.getEndingLine() ).append( this.getLineSeparator() );
316            }
317    
318            return buffer;
319        }
320    
321        private String getMessage( final String key, final Object arguments )
322        {
323            return new MessageFormat( ResourceBundle.getBundle( SectionEditor.class.getName().
324                replace( '.', '/' ) ).getString( key ) ).format( arguments );
325    
326        }
327    
328    }