1 /*
2  * Copyright (C) 2010 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef _UTILS_PROPERTY_MAP_H
18 #define _UTILS_PROPERTY_MAP_H
19 
20 #include <utils/KeyedVector.h>
21 #include <utils/String8.h>
22 #include <utils/Errors.h>
23 #include <utils/Tokenizer.h>
24 
25 namespace android {
26 
27 /*
28  * Provides a mechanism for passing around string-based property key / value pairs
29  * and loading them from property files.
30  *
31  * The property files have the following simple structure:
32  *
33  * # Comment
34  * key = value
35  *
36  * Keys and values are any sequence of printable ASCII characters.
37  * The '=' separates the key from the value.
38  * The key and value may not contain whitespace.
39  *
40  * The '\' character is reserved for escape sequences and is not currently supported.
41  * The '"" character is reserved for quoting and is not currently supported.
42  * Files that contain the '\' or '"' character will fail to parse.
43  *
44  * The file must not contain duplicate keys.
45  *
46  * TODO Support escape sequences and quoted values when needed.
47  */
48 class PropertyMap {
49 public:
50     /* Creates an empty property map. */
51     PropertyMap();
52     ~PropertyMap();
53 
54     /* Clears the property map. */
55     void clear();
56 
57     /* Adds a property.
58      * Replaces the property with the same key if it is already present.
59      */
60     void addProperty(const String8& key, const String8& value);
61 
62     /* Returns true if the property map contains the specified key. */
63     bool hasProperty(const String8& key) const;
64 
65     /* Gets the value of a property and parses it.
66      * Returns true and sets outValue if the key was found and its value was parsed successfully.
67      * Otherwise returns false and does not modify outValue.  (Also logs a warning.)
68      */
69     bool tryGetProperty(const String8& key, String8& outValue) const;
70     bool tryGetProperty(const String8& key, bool& outValue) const;
71     bool tryGetProperty(const String8& key, int32_t& outValue) const;
72     bool tryGetProperty(const String8& key, float& outValue) const;
73 
74     /* Adds all values from the specified property map. */
75     void addAll(const PropertyMap* map);
76 
77     /* Gets the underlying property map. */
getProperties()78     inline const KeyedVector<String8, String8>& getProperties() const { return mProperties; }
79 
80     /* Loads a property map from a file. */
81     static status_t load(const String8& filename, PropertyMap** outMap);
82 
83 private:
84     class Parser {
85         PropertyMap* mMap;
86         Tokenizer* mTokenizer;
87 
88     public:
89         Parser(PropertyMap* map, Tokenizer* tokenizer);
90         ~Parser();
91         status_t parse();
92 
93     private:
94         status_t parseType();
95         status_t parseKey();
96         status_t parseKeyProperty();
97         status_t parseModifier(const String8& token, int32_t* outMetaState);
98         status_t parseCharacterLiteral(char16_t* outCharacter);
99     };
100 
101     KeyedVector<String8, String8> mProperties;
102 };
103 
104 } // namespace android
105 
106 #endif // _UTILS_PROPERTY_MAP_H
107