001    /*
002     *  Copyright 2009-2013 Stephen Colebourne
003     *
004     *  Licensed under the Apache License, Version 2.0 (the "License");
005     *  you may not use this file except in compliance with the License.
006     *  You may obtain a copy of the License at
007     *
008     *      http://www.apache.org/licenses/LICENSE-2.0
009     *
010     *  Unless required by applicable law or agreed to in writing, software
011     *  distributed under the License is distributed on an "AS IS" BASIS,
012     *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     *  See the License for the specific language governing permissions and
014     *  limitations under the License.
015     */
016    package org.joda.money.format;
017    
018    /**
019     * Parses part of a textual input string of monetary information.
020     * <p>
021     * The parser is expected to start parsing at the specified text position
022     * and match against whatever it represents.
023     * The parsed result must be stored in the context.
024     * The context also provides the current parse position which must be updated.
025     * <p>
026     * This interface must be implemented with care to ensure other classes operate correctly.
027     * All instantiable implementations must be thread-safe, and should generally
028     * be final and immutable.
029     */
030    public interface MoneyParser {
031    
032        /**
033         * Parses monetary information using a textual representation.
034         * <p>
035         * The text and parse index are stored in the context.
036         * The parsed data and updated index is also stored in the context.
037         * <p>
038         * Implementations should avoid throwing exceptions and use the error index
039         * in the context instead to record the problem.
040         * The context can be assumed to not be in error on entry to this method.
041         * <p>
042         * The context is not a thread-safe object and a new instance will be created
043         * for each parse. The context must not be stored in an instance variable
044         * or shared with any other threads.
045         * 
046         * @param context  the context to use and parse into, not null
047         */
048        void parse(MoneyParseContext context);
049    
050    }