1 /* 2 * Copyright (C) 2015 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 AAPT_RESOURCEUTILS_H 18 #define AAPT_RESOURCEUTILS_H 19 20 #include <functional> 21 #include <memory> 22 23 #include "androidfw/ResourceTypes.h" 24 #include "androidfw/StringPiece.h" 25 26 #include "NameMangler.h" 27 #include "Resource.h" 28 #include "ResourceValues.h" 29 #include "StringPool.h" 30 31 namespace aapt { 32 namespace ResourceUtils { 33 34 /** 35 * Returns true if the string was parsed as a resource name 36 * ([*][package:]type/name), with 37 * `out_resource` set to the parsed resource name and `out_private` set to true 38 * if a '*' prefix was present. 39 */ 40 bool ParseResourceName(const android::StringPiece& str, ResourceNameRef* out_resource, 41 bool* out_private = nullptr); 42 43 /* 44 * Returns true if the string was parsed as a reference 45 * (@[+][package:]type/name), with 46 * `out_reference` set to the parsed reference. 47 * 48 * If '+' was present in the reference, `out_create` is set to true. 49 * If '*' was present in the reference, `out_private` is set to true. 50 */ 51 bool ParseReference(const android::StringPiece& str, ResourceNameRef* out_reference, 52 bool* out_create = nullptr, bool* out_private = nullptr); 53 54 /* 55 * Returns true if the string is in the form of a resource reference 56 * (@[+][package:]type/name). 57 */ 58 bool IsReference(const android::StringPiece& str); 59 60 /* 61 * Returns true if the string was parsed as an attribute reference 62 * (?[package:][type/]name), 63 * with `out_reference` set to the parsed reference. 64 */ 65 bool ParseAttributeReference(const android::StringPiece& str, ResourceNameRef* out_reference); 66 67 /** 68 * Returns true if the string is in the form of an attribute 69 * reference(?[package:][type/]name). 70 */ 71 bool IsAttributeReference(const android::StringPiece& str); 72 73 /** 74 * Convert an android::ResTable::resource_name to an aapt::ResourceName struct. 75 */ 76 Maybe<ResourceName> ToResourceName( 77 const android::ResTable::resource_name& name); 78 79 /** 80 * Returns a boolean value if the string is equal to TRUE, true, True, FALSE, 81 * false, or False. 82 */ 83 Maybe<bool> ParseBool(const android::StringPiece& str); 84 85 /** 86 * Returns a uint32_t if the string is an integer. 87 */ 88 Maybe<uint32_t> ParseInt(const android::StringPiece& str); 89 90 /** 91 * Returns an ID if it the string represented a valid ID. 92 */ 93 Maybe<ResourceId> ParseResourceId(const android::StringPiece& str); 94 95 /** 96 * Parses an SDK version, which can be an integer, or a letter from A-Z. 97 */ 98 Maybe<int> ParseSdkVersion(const android::StringPiece& str); 99 100 /* 101 * Returns a Reference, or None Maybe instance if the string `str` was parsed as 102 * a 103 * valid reference to a style. 104 * The format for a style parent is slightly more flexible than a normal 105 * reference: 106 * 107 * @[package:]style/<entry> or 108 * ?[package:]style/<entry> or 109 * <package>:[style/]<entry> 110 */ 111 Maybe<Reference> ParseStyleParentReference(const android::StringPiece& str, std::string* out_error); 112 113 /* 114 * Returns a Reference if the string `str` was parsed as a valid XML attribute 115 * name. 116 * The valid format for an XML attribute name is: 117 * 118 * package:entry 119 */ 120 Maybe<Reference> ParseXmlAttributeName(const android::StringPiece& str); 121 122 /* 123 * Returns a Reference object if the string was parsed as a resource or 124 * attribute reference, 125 * ( @[+][package:]type/name | ?[package:]type/name ) setting outCreate to true 126 * if 127 * the '+' was present in the string. 128 */ 129 std::unique_ptr<Reference> TryParseReference(const android::StringPiece& str, 130 bool* out_create = nullptr); 131 132 /* 133 * Returns a BinaryPrimitve object representing @null or @empty if the string 134 * was parsed as one. 135 */ 136 std::unique_ptr<Item> TryParseNullOrEmpty(const android::StringPiece& str); 137 138 // Returns a Reference representing @null. 139 // Due to runtime compatibility issues, this is encoded as a reference with ID 0. 140 // The runtime will convert this to TYPE_NULL. 141 std::unique_ptr<Reference> MakeNull(); 142 143 // Returns a BinaryPrimitive representing @empty. This is encoded as a Res_value with 144 // type Res_value::TYPE_NULL and data Res_value::DATA_NULL_EMPTY. 145 std::unique_ptr<BinaryPrimitive> MakeEmpty(); 146 147 /* 148 * Returns a BinaryPrimitve object representing a color if the string was parsed 149 * as one. 150 */ 151 std::unique_ptr<BinaryPrimitive> TryParseColor(const android::StringPiece& str); 152 153 /* 154 * Returns a BinaryPrimitve object representing a boolean if the string was 155 * parsed as one. 156 */ 157 std::unique_ptr<BinaryPrimitive> TryParseBool(const android::StringPiece& str); 158 159 // Returns a boolean BinaryPrimitive. 160 std::unique_ptr<BinaryPrimitive> MakeBool(bool val); 161 162 /* 163 * Returns a BinaryPrimitve object representing an integer if the string was 164 * parsed as one. 165 */ 166 std::unique_ptr<BinaryPrimitive> TryParseInt(const android::StringPiece& str); 167 168 // Returns an integer BinaryPrimitive. 169 std::unique_ptr<BinaryPrimitive> MakeInt(uint32_t value); 170 171 /* 172 * Returns a BinaryPrimitve object representing a floating point number 173 * (float, dimension, etc) if the string was parsed as one. 174 */ 175 std::unique_ptr<BinaryPrimitive> TryParseFloat(const android::StringPiece& str); 176 177 /* 178 * Returns a BinaryPrimitve object representing an enum symbol if the string was 179 * parsed as one. 180 */ 181 std::unique_ptr<BinaryPrimitive> TryParseEnumSymbol(const Attribute* enum_attr, 182 const android::StringPiece& str); 183 184 /* 185 * Returns a BinaryPrimitve object representing a flag symbol if the string was 186 * parsed as one. 187 */ 188 std::unique_ptr<BinaryPrimitive> TryParseFlagSymbol(const Attribute* enum_attr, 189 const android::StringPiece& str); 190 /* 191 * Try to convert a string to an Item for the given attribute. The attribute 192 * will 193 * restrict what values the string can be converted to. 194 * The callback function on_create_reference is called when the parsed item is a 195 * reference to an ID that must be created (@+id/foo). 196 */ 197 std::unique_ptr<Item> TryParseItemForAttribute( 198 const android::StringPiece& value, const Attribute* attr, 199 const std::function<void(const ResourceName&)>& on_create_reference = {}); 200 201 std::unique_ptr<Item> TryParseItemForAttribute( 202 const android::StringPiece& value, uint32_t type_mask, 203 const std::function<void(const ResourceName&)>& on_create_reference = {}); 204 205 uint32_t AndroidTypeToAttributeTypeMask(uint16_t type); 206 207 /** 208 * Returns a string path suitable for use within an APK. The path will look 209 * like: 210 * 211 * res/type[-config]/<name>.<ext> 212 * 213 * Then name may be mangled if a NameMangler is supplied (can be nullptr) and 214 * the package 215 * requires mangling. 216 */ 217 std::string BuildResourceFileName(const ResourceFile& res_file, 218 const NameMangler* mangler = nullptr); 219 220 // Parses the binary form of a resource value. `type` is used as a hint to know when a value is 221 // an ID versus a False boolean value, etc. `config` is for sorting strings in the string pool. 222 std::unique_ptr<Item> ParseBinaryResValue(const ResourceType& type, const ConfigDescription& config, 223 const android::ResStringPool& src_pool, 224 const android::Res_value& res_value, 225 StringPool* dst_pool); 226 227 // A string flattened from an XML hierarchy, which maintains tags and untranslatable sections 228 // in parallel data structures. 229 struct FlattenedXmlString { 230 std::string text; 231 std::vector<UntranslatableSection> untranslatable_sections; 232 std::vector<Span> spans; 233 }; 234 235 // Flattens an XML hierarchy into a FlattenedXmlString, formatting the text, escaping characters, 236 // and removing whitespace, all while keeping the untranslatable sections and spans in sync with the 237 // transformations. 238 // 239 // Specifically, the StringBuilder will handle escaped characters like \t, \n, \\, \', etc. 240 // Single quotes *must* be escaped, unless within a pair of double-quotes. 241 // Pairs of double-quotes disable whitespace stripping of the enclosed text. 242 // Unicode escape codes (\u0049) are interpreted and the represented Unicode character is inserted. 243 // 244 // A NOTE ON WHITESPACE: 245 // 246 // When preserve_spaces is false, and when text is not enclosed within double-quotes, 247 // StringBuilder replaces a series of whitespace with a single space character. This happens at the 248 // start and end of the string as well, so leading and trailing whitespace is possible. 249 // 250 // When a Span is started or stopped, the whitespace counter is reset, meaning if whitespace 251 // is encountered directly after the span, it will be emitted. This leads to situations like the 252 // following: "This <b> is </b> spaced" -> "This is spaced". Without spans, this would be properly 253 // compressed: "This is spaced" -> "This is spaced". 254 // 255 // Untranslatable sections do not have the same problem: 256 // "This <xliff:g> is </xliff:g> not spaced" -> "This is not spaced". 257 // 258 // NOTE: This is all the way it is because AAPT1 did it this way. Maintaining backwards 259 // compatibility is important. 260 // 261 class StringBuilder { 262 public: 263 using SpanHandle = size_t; 264 using UntranslatableHandle = size_t; 265 266 // Creates a StringBuilder. If preserve_spaces is true, whitespace removal is not performed, and 267 // single quotations can be used without escaping them. 268 explicit StringBuilder(bool preserve_spaces = false); 269 270 // Appends a chunk of text. 271 StringBuilder& AppendText(const std::string& text); 272 273 // Starts a Span (tag) with the given name. The name is expected to be of the form: 274 // "tag_name;attr1=value;attr2=value;" 275 // Which is how Spans are encoded in the ResStringPool. 276 // To end the span, pass back the SpanHandle received from this method to the EndSpan() method. 277 SpanHandle StartSpan(const std::string& name); 278 279 // Ends a Span (tag). Pass in the matching SpanHandle previously obtained from StartSpan(). 280 void EndSpan(SpanHandle handle); 281 282 // Starts an Untranslatable section. 283 // To end the section, pass back the UntranslatableHandle received from this method to 284 // the EndUntranslatable() method. 285 UntranslatableHandle StartUntranslatable(); 286 287 // Ends an Untranslatable section. Pass in the matching UntranslatableHandle previously obtained 288 // from StartUntranslatable(). 289 void EndUntranslatable(UntranslatableHandle handle); 290 291 // Returns the flattened XML string, with all spans and untranslatable sections encoded as 292 // parallel data structures. 293 FlattenedXmlString GetFlattenedString() const; 294 295 // Returns just the flattened XML text, with no spans or untranslatable sections. 296 std::string to_string() const; 297 298 // Returns true if there was no error. 299 explicit operator bool() const; 300 301 std::string GetError() const; 302 303 private: 304 DISALLOW_COPY_AND_ASSIGN(StringBuilder); 305 306 void ResetTextState(); 307 308 std::string error_; 309 FlattenedXmlString xml_string_; 310 uint32_t utf16_len_ = 0u; 311 bool preserve_spaces_; 312 bool quote_; 313 bool last_codepoint_was_space_ = false; 314 }; 315 316 } // namespace ResourceUtils 317 } // namespace aapt 318 319 #endif /* AAPT_RESOURCEUTILS_H */ 320