tools/aapt2/Resources.proto

/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

// Keep proto2 syntax because we require the distinction between fields that
// are set and unset.
syntax = "proto2";

option java_package = "com.android.aapt";
option optimize_for = LITE_RUNTIME;

package aapt.pb;

// A configuration description that wraps the binary form of the C++ class
// aapt::ConfigDescription, with an added product definition.
// TODO(adamlesinski): Flesh this out to be represented in proto.
message ConfigDescription {
  optional bytes data = 1;
  optional string product = 2;
}

// A string pool that wraps the binary form of the C++ class android::ResStringPool.
message StringPool {
  optional bytes data = 1;
}

// The position of a declared entity within a file.
message SourcePosition {
  optional uint32 line_number = 1;
  optional uint32 column_number = 2;
}

// Developer friendly source file information for an entity in the resource table.
message Source {
  // The index of the string path within the source string pool of a ResourceTable.
  optional uint32 path_idx = 1;
  optional SourcePosition position = 2;
}

// Top level message representing a resource table.
message ResourceTable {
  // The string pool containing source paths referenced throughout the resource table. This does
  // not end up in the final binary ARSC file.
  optional StringPool source_pool = 1;

  // Resource definitions corresponding to an Android package.
  repeated Package package = 2;
}

// Defines resources for an Android package.
message Package {
  // The package ID of this package, in the range [0x00, 0xff].
  // The ID 0x00 is reserved for shared libraries, or when the ID is assigned at run-time.
  // The ID 0x01 is reserved for the 'android' package (framework).
  // The ID range [0x02, 0x7f) is reserved for auto-assignment to shared libraries at run-time.
  // The ID 0x7f is reserved for the application package.
  // IDs > 0x7f are reserved for the application as well and are treated as feature splits.
  optional uint32 package_id = 1;

  // The Java compatible Android package name of the app.
  optional string package_name = 2;

  // The series of types defined by the package.
  repeated Type type = 3;
}

// A set of resources grouped under a common type. Such types include string, layout, xml, dimen,
// attr, etc. This maps to the second part of a resource identifier in Java (R.type.entry).
message Type {
  // The ID of the type. This may be 0, which indicates no ID is set.
  optional uint32 id = 1;

  // The name of the type. This corresponds to the 'type' part of a full resource name of the form
  // package:type/entry. The set of legal type names is listed in Resource.cpp.
  optional string name = 2;

  // The entries defined for this type.
  repeated Entry entry = 3;
}

// The status of a symbol/entry. This contains information like visibility (public/private),
// comments, and whether the entry can be overridden.
message SymbolStatus {
  // The visibility of the resource outside of its package.
  enum Visibility {
    // No visibility was explicitly specified. This is typically treated as private.
    // The distinction is important when two separate R.java files are generated: a public and
    // private one. An unknown visibility, in this case, would cause the resource to be omitted
    // from either R.java.
    UNKNOWN = 0;

    // A resource was explicitly marked as private. This means the resource can not be accessed
    // outside of its package unless the @*package:type/entry notation is used (the asterisk being
    // the private accessor). If two R.java files are generated (private + public), the resource
    // will only be emitted to the private R.java file.
    PRIVATE = 1;

    // A resource was explicitly marked as public. This means the resource can be accessed
    // from any package, and is emitted into all R.java files, public and private.
    PUBLIC = 2;
  }

  optional Visibility visibility = 1;

  // The path at which this entry's visibility was defined (eg. public.xml).
  optional Source source = 2;

  // The comment associated with the <public> tag.
  optional string comment = 3;

  // Whether the symbol can be merged into another resource table without there being an existing
  // definition to override. Used for overlays and set to true when <add-resource> is specified.
  optional bool allow_new = 4;
}

// An entry declaration. An entry has a full resource ID that is the combination of package ID,
// type ID, and its own entry ID. An entry on its own has no value, but values are defined for
// various configurations/variants.
message Entry {
  // The ID of this entry. Together with the package ID and type ID, this forms a full resource ID
  // of the form 0xPPTTEEEE, where PP is the package ID, TT is the type ID, and EEEE is the entry
  // ID.
  optional uint32 id = 1;

  // The name of this entry. This corresponds to the 'entry' part of a full resource name of the
  // form package:type/entry.
  optional string name = 2;

  // The symbol status of this entry, which includes visibility information.
  optional SymbolStatus symbol_status = 3;

  // The set of values defined for this entry, each corresponding to a different
  // configuration/variant.
  repeated ConfigValue config_value = 4;
}

// A Configuration/Value pair.
message ConfigValue {
  optional ConfigDescription config = 1;
  optional Value value = 2;
}

// The generic meta-data for every value in a resource table.
message Value {
  // Where the value was defined.
  optional Source source = 1;

  // Any comment associated with the value.
  optional string comment = 2;

  // Whether the value can be overridden.
  optional bool weak = 3;

  // If the value is an Item, this is set.
  optional Item item = 4;

  // If the value is a CompoundValue, this is set.
  optional CompoundValue compound_value = 5;
}

// An Item is an abstract type. It represents a value that can appear inline in many places, such
// as XML attribute values or on the right hand side of style attribute definitions. The concrete
// type is one of the types below. Only one can be set.
message Item {
  optional Reference ref = 1;
  optional String str = 2;
  optional RawString raw_str = 3;
  optional StyledString styled_str = 4;
  optional FileReference file = 5;
  optional Id id = 6;
  optional Primitive prim = 7;
}

// A CompoundValue is an abstract type. It represents a value that is a made of other values.
// These can only usually appear as top-level resources. The concrete type is one of the types
// below. Only one can be set.
message CompoundValue {
  optional Attribute attr = 1;
  optional Style style = 2;
  optional Styleable styleable = 3;
  optional Array array = 4;
  optional Plural plural = 5;
}

// A value that is a reference to another resource. This reference can be by name or resource ID.
message Reference {
  enum Type {
    // A plain reference (@package:type/entry).
    REFERENCE = 0;

    // A reference to a theme attribute (?package:type/entry).
    ATTRIBUTE = 1;
  }

  optional Type type = 1;

  // The resource ID (0xPPTTEEEE) of the resource being referred.
  optional uint32 id = 2;

  // The optional resource name.
  optional string name = 3;

  // Whether this reference is referencing a private resource (@*package:type/entry).
  optional bool private = 4;
}

// A value that represents an ID. This is just a placeholder, as ID values are used to occupy a
// resource ID (0xPPTTEEEE) as a unique identifier. Their value is unimportant.
message Id {
}

// A value that is a string.
message String {
  optional string value = 1;
}

// A value that is a raw string, which is unescaped/uninterpreted. This is typically used to
// represent the value of a style attribute before the attribute is compiled and the set of
// allowed values is known.
message RawString {
  optional string value = 1;
}

// A string with styling information, like html tags that specify boldness, italics, etc.
message StyledString {
  // The raw text of the string.
  optional string value = 1;

  // A Span marks a region of the string text that is styled.
  message Span {
    // The name of the tag, and its attributes, encoded as follows:
    // tag_name;attr1=value1;attr2=value2;[...]
    optional string tag = 1;

    // The first character position this span applies to, in UTF-16 offset.
    optional uint32 first_char = 2;

    // The last character position this span applies to, in UTF-16 offset.
    optional uint32 last_char = 3;
  }

  repeated Span span = 2;
}

// A value that is a reference to an external entity, like an XML file or a PNG.
message FileReference {
  // Path to a file within the APK (typically res/type-config/entry.ext).
  optional string path = 1;
}

// A value that represents a primitive data type (float, int, boolean, etc.).
// Corresponds to the fields (type/data) of the C struct android::Res_value.
message Primitive {
  optional uint32 type = 1;
  optional uint32 data = 2;
}

// A value that represents an XML attribute and what values it accepts.
message Attribute {
  // A Symbol used to represent an enum or a flag.
  message Symbol {
    // Where the enum/flag item was defined.
    optional Source source = 1;

    // Any comments associated with the enum or flag.
    optional string comment = 2;

    // The name of the enum/flag as a reference. Enums/flag items are generated as ID resource
    // values.
    optional Reference name = 3;

    // The value of the enum/flag.
    optional uint32 value = 4;
  }

  // Bitmask of formats allowed for an attribute.
  enum FormatFlags {
    ANY = 0x0000ffff;    // Allows any type except ENUM and FLAGS.
    REFERENCE = 0x01;    // Allows Reference values.
    STRING = 0x02;       // Allows String/StyledString values.
    INTEGER = 0x04;      // Allows any integer BinaryPrimitive values.
    BOOLEAN = 0x08;      // Allows any boolean BinaryPrimitive values.
    COLOR = 0x010;       // Allows any color BinaryPrimitive values.
    FLOAT = 0x020;       // Allows any float BinaryPrimitive values.
    DIMENSION = 0x040;   // Allows any dimension BinaryPrimitive values.
    FRACTION = 0x080;    // Allows any fraction BinaryPrimitive values.
    ENUM = 0x00010000;   // Allows enums that are defined in the Attribute's symbols.
                         // ENUM and FLAGS cannot BOTH be set.
    FLAGS = 0x00020000;  // Allows flags that are defined in the Attribute's symbols.
                         // ENUM and FLAGS cannot BOTH be set.
  }

  // A bitmask of types that this XML attribute accepts. Corresponds to the flags in the
  // enum FormatFlags.
  optional uint32 format_flags = 1;

  // The smallest integer allowed for this XML attribute. Only makes sense if the format includes
  // FormatFlags::INTEGER.
  optional int32 min_int = 2;

  // The largest integer allowed for this XML attribute. Only makes sense if the format includes
  // FormatFlags::INTEGER.
  optional int32 max_int = 3;

  // The set of enums/flags defined in this attribute. Only makes sense if the format includes
  // either FormatFlags::ENUM or FormatFlags::FLAGS. Having both is an error.
  repeated Symbol symbol = 4;
}

// A value that represents a style.
message Style {
  // An XML attribute/value pair defined in the style.
  message Entry {
    // Where the entry was defined.
    optional Source source = 1;

    // Any comments associated with the entry.
    optional string comment = 2;

    // A reference to the XML attribute.
    optional Reference key = 3;

    // The Item defined for this XML attribute.
    optional Item item = 4;
  }

  // The optinal style from which this style inherits attributes.
  optional Reference parent = 1;

  // The source file information of the parent inheritance declaration.
  optional Source parent_source = 2;

  // The set of XML attribute/value pairs for this style.
  repeated Entry entry = 3;
}

// A value that represents a <declare-styleable> XML resource. These are not real resources and
// only end up as Java fields in the generated R.java. They do not end up in the binary ARSC file.
message Styleable {
  // An attribute defined for this styleable.
  message Entry {
    // Where the attribute was defined within the <declare-styleable> block.
    optional Source source = 1;

    // Any comments associated with the declaration.
    optional string comment = 2;

    // The reference to the attribute.
    optional Reference attr = 3;
  }

  // The set of attribute declarations.
  repeated Entry entry = 1;
}

// A value that represents an array of resource values.
message Array {
  // A single element of the array.
  message Element {
    // Where the element was defined.
    optional Source source = 1;

    // Any comments associated with the element.
    optional string comment = 2;

    // The value assigned to this element.
    optional Item item = 3;
  }

  // The list of array elements.
  repeated Element element = 1;
}

// A value that represents a string and its many variations based on plurality.
message Plural {
  // The arity of the plural.
  enum Arity {
    ZERO = 0;
    ONE = 1;
    TWO = 2;
    FEW = 3;
    MANY = 4;
    OTHER = 5;
  }

  // The plural value for a given arity.
  message Entry {
    // Where the plural was defined.
    optional Source source = 1;

    // Any comments associated with the plural.
    optional string comment = 2;

    // The arity of the plural.
    optional Arity arity = 3;

    // The value assigned to this plural.
    optional Item item = 4;
  }

  // The set of arity/plural mappings.
  repeated Entry entry = 1;
}

// Defines an abstract XmlNode that must be either an XmlElement, or
// a text node represented by a string.
message XmlNode {
  // If set, this node is an element/tag.
  optional XmlElement element = 1;

  // If set, this node is a chunk of text.
  optional string text = 2;

  // Source line and column info.
  optional SourcePosition source = 3;
}

// An <element> in an XML document.
message XmlElement {
  // Namespaces defined on this element.
  repeated XmlNamespace namespace_declaration = 1;

  // The namespace URI of this element.
  optional string namespace_uri = 2;

  // The name of this element.
  optional string name = 3;

  // The attributes of this element.
  repeated XmlAttribute attribute = 4;

  // The children of this element.
  repeated XmlNode child = 5;
}

// A namespace declaration on an XmlElement (xmlns:android="http://...").
message XmlNamespace {
  optional string prefix = 1;
  optional string uri = 2;

  // Source line and column info.
  optional SourcePosition source = 3;
}

// An attribute defined on an XmlElement (android:text="...").
message XmlAttribute {
  optional string namespace_uri = 1;
  optional string name = 2;
  optional string value = 3;

  // Source line and column info.
  optional SourcePosition source = 4;

  // The resource ID (0xPPTTEEEE) of the attribute.
  optional uint32 resource_id = 5;

  // The interpreted/compiled version of the `value` string.
  optional Item compiled_item = 6;
}