michael@0: /*
michael@0:  * Copyright (C) 2010 The Android Open Source Project
michael@0:  *
michael@0:  * Licensed under the Apache License, Version 2.0 (the "License");
michael@0:  * you may not use this file except in compliance with the License.
michael@0:  * You may obtain a copy of the License at
michael@0:  *
michael@0:  *      http://www.apache.org/licenses/LICENSE-2.0
michael@0:  *
michael@0:  * Unless required by applicable law or agreed to in writing, software
michael@0:  * distributed under the License is distributed on an "AS IS" BASIS,
michael@0:  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
michael@0:  * See the License for the specific language governing permissions and
michael@0:  * limitations under the License.
michael@0:  */
michael@0: 
michael@0: #ifndef _UTILS_TOKENIZER_H
michael@0: #define _UTILS_TOKENIZER_H
michael@0: 
michael@0: #include <assert.h>
michael@0: #include <utils/Errors.h>
michael@0: #include <utils/FileMap.h>
michael@0: #include <utils/String8.h>
michael@0: 
michael@0: namespace android {
michael@0: 
michael@0: /**
michael@0:  * A simple tokenizer for loading and parsing ASCII text files line by line.
michael@0:  */
michael@0: class Tokenizer {
michael@0:     Tokenizer(const String8& filename, FileMap* fileMap, char* buffer,
michael@0:             bool ownBuffer, size_t length);
michael@0: 
michael@0: public:
michael@0:     ~Tokenizer();
michael@0: 
michael@0:     /**
michael@0:      * Opens a file and maps it into memory.
michael@0:      *
michael@0:      * Returns NO_ERROR and a tokenizer for the file, if successful.
michael@0:      * Otherwise returns an error and sets outTokenizer to NULL.
michael@0:      */
michael@0:     static status_t open(const String8& filename, Tokenizer** outTokenizer);
michael@0: 
michael@0:     /**
michael@0:      * Prepares to tokenize the contents of a string.
michael@0:      *
michael@0:      * Returns NO_ERROR and a tokenizer for the string, if successful.
michael@0:      * Otherwise returns an error and sets outTokenizer to NULL.
michael@0:      */
michael@0:     static status_t fromContents(const String8& filename,
michael@0:             const char* contents, Tokenizer** outTokenizer);
michael@0: 
michael@0:     /**
michael@0:      * Returns true if at the end of the file.
michael@0:      */
michael@0:     inline bool isEof() const { return mCurrent == getEnd(); }
michael@0: 
michael@0:     /**
michael@0:      * Returns true if at the end of the line or end of the file.
michael@0:      */
michael@0:     inline bool isEol() const { return isEof() || *mCurrent == '\n'; }
michael@0: 
michael@0:     /**
michael@0:      * Gets the name of the file.
michael@0:      */
michael@0:     inline String8 getFilename() const { return mFilename; }
michael@0: 
michael@0:     /**
michael@0:      * Gets a 1-based line number index for the current position.
michael@0:      */
michael@0:     inline int32_t getLineNumber() const { return mLineNumber; }
michael@0: 
michael@0:     /**
michael@0:      * Formats a location string consisting of the filename and current line number.
michael@0:      * Returns a string like "MyFile.txt:33".
michael@0:      */
michael@0:     String8 getLocation() const;
michael@0: 
michael@0:     /**
michael@0:      * Gets the character at the current position.
michael@0:      * Returns null at end of file.
michael@0:      */
michael@0:     inline char peekChar() const { return isEof() ? '\0' : *mCurrent; }
michael@0: 
michael@0:     /**
michael@0:      * Gets the remainder of the current line as a string, excluding the newline character.
michael@0:      */
michael@0:     String8 peekRemainderOfLine() const;
michael@0: 
michael@0:     /**
michael@0:      * Gets the character at the current position and advances past it.
michael@0:      * Returns null at end of file.
michael@0:      */
michael@0:     inline char nextChar() { return isEof() ? '\0' : *(mCurrent++); }
michael@0: 
michael@0:     /**
michael@0:      * Gets the next token on this line stopping at the specified delimiters
michael@0:      * or the end of the line whichever comes first and advances past it.
michael@0:      * Also stops at embedded nulls.
michael@0:      * Returns the token or an empty string if the current character is a delimiter
michael@0:      * or is at the end of the line.
michael@0:      */
michael@0:     String8 nextToken(const char* delimiters);
michael@0: 
michael@0:     /**
michael@0:      * Advances to the next line.
michael@0:      * Does nothing if already at the end of the file.
michael@0:      */
michael@0:     void nextLine();
michael@0: 
michael@0:     /**
michael@0:      * Skips over the specified delimiters in the line.
michael@0:      * Also skips embedded nulls.
michael@0:      */
michael@0:     void skipDelimiters(const char* delimiters);
michael@0: 
michael@0: private:
michael@0:     Tokenizer(const Tokenizer& other); // not copyable
michael@0: 
michael@0:     String8 mFilename;
michael@0:     FileMap* mFileMap;
michael@0:     char* mBuffer;
michael@0:     bool mOwnBuffer;
michael@0:     size_t mLength;
michael@0: 
michael@0:     const char* mCurrent;
michael@0:     int32_t mLineNumber;
michael@0: 
michael@0:     inline const char* getEnd() const { return mBuffer + mLength; }
michael@0: 
michael@0: };
michael@0: 
michael@0: } // namespace android
michael@0: 
michael@0: #endif // _UTILS_TOKENIZER_H