    001    /*
    002     * SideKickParser.java
    003     * :tabSize=8:indentSize=8:noTabs=false:
    004     * :folding=explicit:collapseFolds=1:
    005     *
    006     * Copyright 2003 Slava Pestov
    007     *           2005 Robert McKinnon
    008     *
    009     * This program is free software; you can redistribute it and/or
    010     * modify it under the terms of the GNU General Public License
    011     * as published by the Free Software Foundation; either version 2
    012     * of the License, or any later version.
    013     *
    014     * This program is distributed in the hope that it will be useful,
    015     * but WITHOUT ANY WARRANTY; without even the implied warranty of
    016     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    017     * GNU General Public License for more details.
    018     *
    019     * You should have received a copy of the GNU General Public License
    020     * along with this program; if not, write to the Free Software
    021     * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
    022     */
    023
    024    package sidekick;
    025
    026    //{{{ Imports
    027    import org.gjt.sp.jedit.*;
    028    import errorlist.DefaultErrorSource;
    029    import org.gjt.sp.util.Log;
    030
    031    //}}}
    032
    033    /**
    034     * An abstract base class for plugin-provided parser implementations.<p>
    035     *
    036     * Plugins can provide SideKick parsers by defining entries in their
    037     * <code>services.xml</code> files like so:
    038     *
    039     * <pre><SERVICE CLASS="sidekick.SideKickParser" NAME="<i>name</i>">
    040     *    new <i>MyParser<i>();
    041     *</SERVICE></pre>
    042     *
    043     * See <code>org.gjt.sp.jedit.ServiceManager</code> for details.<p>
    044     *
    045     * Note that each <code>SideKickParser</code> subclass has a name which is
    046     * used to key a property <code>sidekick.parser.<i>name</i>.label</code>.<p>
    047     *
    048     * To associate a parser with some edit modes, define properties like this:
    049     * <pre>mode.scheme.sidekick.parser=lisp
    050     *mode.lisp.sidekick.parser=lisp</pre>
    051     *
    052     * @version $Id: SideKickParser.java,v 1.20 2006/06/05 06:10:38 ezust Exp $
    053     * @author Slava Pestov
    054     */
    055    public abstract class SideKickParser
    056    {
    057            public static final String SERVICE = "sidekick.SideKickParser";
    058
    059            //{{{ SideKickParser constructor
    060            /**
    061             * The parser constructor.
    062             *
    063             */
    064            public SideKickParser(String name)
    065            {
    066                    this.name = name;
    067            } //}}}
    068
    069            //{{{ getName() method
    070            /**
    071             * Returns the parser's name.
    072             */
    073            public final String getName()
    074            {
    075                    return name;
    076            } //}}}
    077
    078            //{{{ stop() method
    079            /**
    080             * Stops the parse request currently in progress. It is up to the
    081             * parser to implement this.
    082             * @since SideKick 0.3
    083             */
    084            public void stop()
    085            {
    086            } //}}}
    087
    088            //{{{ activate() method
    089            /**
    090             * This method is called when a buffer using this parser is selected
    091             * in the specified view.
    092             * @param view The view
    093             * @since SideKick 0.2
    094             * @deprecated Use the form taking an <code>EditPane</code> instead.
    095             */
    096            public void activate(View view)
    097            {
    098            } //}}}
    099
    100            //{{{ deactivate() method
    101            /**
    102             * This method is called when a buffer using this parser is no longer
    103             * selected in the specified view.
    104             * @param view The view
    105             * @since SideKick 0.2
    106             * @deprecated Use the form taking an <code>EditPane</code> instead.
    107             */
    108            public void deactivate(View view)
    109            {
    110            } //}}}
    111
    112            //{{{ activate() method
    113            /**
    114             * This method is called when a buffer using this parser is selected
    115             * in the specified view.
    116             * @param editPane The edit pane
    117             * @since SideKick 0.3.1
    118             */
    119            public void activate(EditPane editPane)
    120            {
    121                    activate(editPane.getView());
    122                    Log.log(Log.DEBUG,this,getName() + ": activated for " + editPane.getBuffer());
    123            } //}}}
    124
    125            //{{{ deactivate() method
    126            /**
    127             * This method is called when a buffer using this parser is no longer
    128             * selected in the specified view.
    129             * @param editPane The edit pane
    130             * @since SideKick 0.3.1
    131             */
    132            public void deactivate(EditPane editPane)
    133            {
    134                    deactivate(editPane.getView());
    135                    Log.log(Log.DEBUG,this,getName() + ": deactivated");
    136            } //}}}
    137
    138            //{{{ parse() method
    139            /**
    140             * Parses the given text and returns a tree model.
    141             *
    142             * @param buffer The buffer to parse.
    143             * @param errorSource An error source to add errors to.
    144             *
    145             * @return A new instance of the <code>SideKickParsedData</code> class.
    146             */
    147            public abstract SideKickParsedData parse(Buffer buffer,
    148                    DefaultErrorSource errorSource);
    149            //}}}
    150
    151            //{{{ supportsCompletion() method
    152            /**
    153             * Returns if the parser supports code completion.
    154             *
    155             * Returns false by default.
    156             */
    157            public boolean supportsCompletion()
    158            {
    159                    return false;
    160            } //}}}
    161
    162            //{{{ canHandleBackspace() method
    163            /**
    164         * <p>
    165             * Returns true if the parser can handle
    166         * the backspace key being typed when
    167         * the completion popup is open,
    168         * else false if not.
    169         * </p><p>
    170         * If false, the completion popup is
    171         * closed when backspace is typed.
    172             * </p><p>
    173         * If true, the
    174         * {@link SideKickCompletion#handleKeystroke(int, char)}
    175         * method must be overidden to handle receiving
    176         * the backspace character, '\b', as a value
    177         * for the keyChar parameter.
    178         * </p><p>
    179             * Returns false by default.
    180         * </p>
    181         * @since SideKick 0.3.4
    182             */
    183            public boolean canHandleBackspace()
    184            {
    185                    return false;
    186            } //}}}
    187
    188            //{{{ canCompleteAnywhere() method
    189            /**
    190             * Returns if completion popups should be shown after any period of
    191             * inactivity. Otherwise, they are only shown if explicitly requested
    192             * by the user.
    193             *
    194             * Returns true by default.
    195             */
    196            public boolean canCompleteAnywhere()
    197            {
    198                    return true;
    199            } //}}}
    200
    201            //{{{ getInstantCompletionTriggers() method
    202            /**
    203             * Returns a list of characters which trigger completion immediately.
    204             *
    205             * Returns null by default.
    206             *
    207             */
    208            public String getInstantCompletionTriggers()
    209            {
    210                    return null;
    211            } //}}}
    212
    213            //{{{ getParseTriggers() method
    214            /**
    215             * Returns a list of characters which trigger a buffer re-parse.
    216             *
    217             * Returns null by default.
    218             * @since SideKick 0.3
    219             *
    220             */
    221            public String getParseTriggers()
    222            {
    223                    return null;
    224            } //}}}
    225
    226            //{{{ complete() method
    227            /**
    228             * Returns completions suitable for insertion at the specified position.
    229             *
    230             * Returns null by default.
    231             *
    232             * @param editPane The edit pane involved.
    233             * @param caret The caret position.
    234             */
    235            public SideKickCompletion complete(EditPane editPane, int caret)
    236            {
    237                    return null;
    238            } //}}}
    239
    240            protected String name;
    241    }