Alex Ruiz | e3b4b9f | 2011-06-07 23:41:09 +0000 | [diff] [blame] | 1 | // Protocol Buffers - Google's data interchange format |
| 2 | // Copyright 2008 Google Inc. All rights reserved. |
| 3 | // http://code.google.com/p/protobuf/ |
| 4 | // |
| 5 | // Redistribution and use in source and binary forms, with or without |
| 6 | // modification, are permitted provided that the following conditions are |
| 7 | // met: |
| 8 | // |
| 9 | // * Redistributions of source code must retain the above copyright |
| 10 | // notice, this list of conditions and the following disclaimer. |
| 11 | // * Redistributions in binary form must reproduce the above |
| 12 | // copyright notice, this list of conditions and the following disclaimer |
| 13 | // in the documentation and/or other materials provided with the |
| 14 | // distribution. |
| 15 | // * Neither the name of Google Inc. nor the names of its |
| 16 | // contributors may be used to endorse or promote products derived from |
| 17 | // this software without specific prior written permission. |
| 18 | // |
| 19 | // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 20 | // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 21 | // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| 22 | // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
| 23 | // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| 24 | // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| 25 | // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| 26 | // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| 27 | // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| 28 | // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
| 29 | // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 30 | |
| 31 | // Author: kenton@google.com (Kenton Varda) |
| 32 | // Based on original Protocol Buffers design by |
| 33 | // Sanjay Ghemawat, Jeff Dean, and others. |
| 34 | // |
| 35 | // The messages in this file describe the definitions found in .proto files. |
| 36 | // A valid .proto file can be translated directly to a FileDescriptorProto |
| 37 | // without any other information (e.g. without reading its imports). |
Alex Ruiz | 3477c91 | 2011-11-16 17:31:53 -0800 | [diff] [blame] | 38 | syntax = "proto2"; |
Alex Ruiz | e3b4b9f | 2011-06-07 23:41:09 +0000 | [diff] [blame] | 39 | |
| 40 | |
| 41 | package google.protobuf; |
| 42 | option java_package = "com.google.protobuf"; |
| 43 | option java_outer_classname = "DescriptorProtos"; |
| 44 | |
| 45 | // descriptor.proto must be optimized for speed because reflection-based |
| 46 | // algorithms don't work during bootstrapping. |
| 47 | option optimize_for = SPEED; |
| 48 | |
| 49 | // The protocol compiler can output a FileDescriptorSet containing the .proto |
| 50 | // files it parses. |
| 51 | message FileDescriptorSet { |
| 52 | repeated FileDescriptorProto file = 1; |
| 53 | } |
| 54 | |
| 55 | // Describes a complete .proto file. |
| 56 | message FileDescriptorProto { |
| 57 | optional string name = 1; // file name, relative to root of source tree |
| 58 | optional string package = 2; // e.g. "foo", "foo.bar", etc. |
| 59 | |
| 60 | // Names of files imported by this file. |
| 61 | repeated string dependency = 3; |
| 62 | |
| 63 | // All top-level definitions in this file. |
| 64 | repeated DescriptorProto message_type = 4; |
| 65 | repeated EnumDescriptorProto enum_type = 5; |
| 66 | repeated ServiceDescriptorProto service = 6; |
| 67 | repeated FieldDescriptorProto extension = 7; |
| 68 | |
| 69 | optional FileOptions options = 8; |
| 70 | |
| 71 | // This field contains optional information about the original source code. |
| 72 | // You may safely remove this entire field whithout harming runtime |
| 73 | // functionality of the descriptors -- the information is needed only by |
| 74 | // development tools. |
| 75 | optional SourceCodeInfo source_code_info = 9; |
| 76 | } |
| 77 | |
| 78 | // Describes a message type. |
| 79 | message DescriptorProto { |
| 80 | optional string name = 1; |
| 81 | |
| 82 | repeated FieldDescriptorProto field = 2; |
| 83 | repeated FieldDescriptorProto extension = 6; |
| 84 | |
| 85 | repeated DescriptorProto nested_type = 3; |
| 86 | repeated EnumDescriptorProto enum_type = 4; |
| 87 | |
| 88 | message ExtensionRange { |
| 89 | optional int32 start = 1; |
| 90 | optional int32 end = 2; |
| 91 | } |
| 92 | repeated ExtensionRange extension_range = 5; |
| 93 | |
| 94 | optional MessageOptions options = 7; |
| 95 | } |
| 96 | |
| 97 | // Describes a field within a message. |
| 98 | message FieldDescriptorProto { |
| 99 | enum Type { |
| 100 | // 0 is reserved for errors. |
| 101 | // Order is weird for historical reasons. |
| 102 | TYPE_DOUBLE = 1; |
| 103 | TYPE_FLOAT = 2; |
| 104 | TYPE_INT64 = 3; // Not ZigZag encoded. Negative numbers |
| 105 | // take 10 bytes. Use TYPE_SINT64 if negative |
| 106 | // values are likely. |
| 107 | TYPE_UINT64 = 4; |
| 108 | TYPE_INT32 = 5; // Not ZigZag encoded. Negative numbers |
| 109 | // take 10 bytes. Use TYPE_SINT32 if negative |
| 110 | // values are likely. |
| 111 | TYPE_FIXED64 = 6; |
| 112 | TYPE_FIXED32 = 7; |
| 113 | TYPE_BOOL = 8; |
| 114 | TYPE_STRING = 9; |
| 115 | TYPE_GROUP = 10; // Tag-delimited aggregate. |
| 116 | TYPE_MESSAGE = 11; // Length-delimited aggregate. |
| 117 | |
| 118 | // New in version 2. |
| 119 | TYPE_BYTES = 12; |
| 120 | TYPE_UINT32 = 13; |
| 121 | TYPE_ENUM = 14; |
| 122 | TYPE_SFIXED32 = 15; |
| 123 | TYPE_SFIXED64 = 16; |
| 124 | TYPE_SINT32 = 17; // Uses ZigZag encoding. |
| 125 | TYPE_SINT64 = 18; // Uses ZigZag encoding. |
| 126 | }; |
| 127 | |
| 128 | enum Label { |
| 129 | // 0 is reserved for errors |
| 130 | LABEL_OPTIONAL = 1; |
| 131 | LABEL_REQUIRED = 2; |
| 132 | LABEL_REPEATED = 3; |
| 133 | // TODO(sanjay): Should we add LABEL_MAP? |
| 134 | }; |
| 135 | |
| 136 | optional string name = 1; |
| 137 | optional int32 number = 3; |
| 138 | optional Label label = 4; |
| 139 | |
| 140 | // If type_name is set, this need not be set. If both this and type_name |
| 141 | // are set, this must be either TYPE_ENUM or TYPE_MESSAGE. |
| 142 | optional Type type = 5; |
| 143 | |
| 144 | // For message and enum types, this is the name of the type. If the name |
| 145 | // starts with a '.', it is fully-qualified. Otherwise, C++-like scoping |
| 146 | // rules are used to find the type (i.e. first the nested types within this |
| 147 | // message are searched, then within the parent, on up to the root |
| 148 | // namespace). |
| 149 | optional string type_name = 6; |
| 150 | |
| 151 | // For extensions, this is the name of the type being extended. It is |
| 152 | // resolved in the same manner as type_name. |
| 153 | optional string extendee = 2; |
| 154 | |
| 155 | // For numeric types, contains the original text representation of the value. |
| 156 | // For booleans, "true" or "false". |
| 157 | // For strings, contains the default text contents (not escaped in any way). |
| 158 | // For bytes, contains the C escaped value. All bytes >= 128 are escaped. |
| 159 | // TODO(kenton): Base-64 encode? |
| 160 | optional string default_value = 7; |
| 161 | |
| 162 | optional FieldOptions options = 8; |
| 163 | } |
| 164 | |
| 165 | // Describes an enum type. |
| 166 | message EnumDescriptorProto { |
| 167 | optional string name = 1; |
| 168 | |
| 169 | repeated EnumValueDescriptorProto value = 2; |
| 170 | |
| 171 | optional EnumOptions options = 3; |
| 172 | } |
| 173 | |
| 174 | // Describes a value within an enum. |
| 175 | message EnumValueDescriptorProto { |
| 176 | optional string name = 1; |
| 177 | optional int32 number = 2; |
| 178 | |
| 179 | optional EnumValueOptions options = 3; |
| 180 | } |
| 181 | |
| 182 | // Describes a service. |
| 183 | message ServiceDescriptorProto { |
| 184 | optional string name = 1; |
| 185 | repeated MethodDescriptorProto method = 2; |
| 186 | |
| 187 | optional ServiceOptions options = 3; |
| 188 | } |
| 189 | |
| 190 | // Describes a method of a service. |
| 191 | message MethodDescriptorProto { |
| 192 | optional string name = 1; |
| 193 | |
| 194 | // Input and output type names. These are resolved in the same way as |
| 195 | // FieldDescriptorProto.type_name, but must refer to a message type. |
| 196 | optional string input_type = 2; |
| 197 | optional string output_type = 3; |
| 198 | |
| 199 | optional MethodOptions options = 4; |
| 200 | } |
| 201 | |
| 202 | // =================================================================== |
| 203 | // Options |
| 204 | |
| 205 | // Each of the definitions above may have "options" attached. These are |
| 206 | // just annotations which may cause code to be generated slightly differently |
| 207 | // or may contain hints for code that manipulates protocol messages. |
| 208 | // |
| 209 | // Clients may define custom options as extensions of the *Options messages. |
| 210 | // These extensions may not yet be known at parsing time, so the parser cannot |
| 211 | // store the values in them. Instead it stores them in a field in the *Options |
| 212 | // message called uninterpreted_option. This field must have the same name |
| 213 | // across all *Options messages. We then use this field to populate the |
| 214 | // extensions when we build a descriptor, at which point all protos have been |
| 215 | // parsed and so all extensions are known. |
| 216 | // |
| 217 | // Extension numbers for custom options may be chosen as follows: |
| 218 | // * For options which will only be used within a single application or |
| 219 | // organization, or for experimental options, use field numbers 50000 |
| 220 | // through 99999. It is up to you to ensure that you do not use the |
| 221 | // same number for multiple options. |
| 222 | // * For options which will be published and used publicly by multiple |
| 223 | // independent entities, e-mail protobuf-global-extension-registry@google.com |
| 224 | // to reserve extension numbers. Simply provide your project name (e.g. |
| 225 | // Object-C plugin) and your porject website (if available) -- there's no need |
| 226 | // to explain how you intend to use them. Usually you only need one extension |
| 227 | // number. You can declare multiple options with only one extension number by |
| 228 | // putting them in a sub-message. See the Custom Options section of the docs |
| 229 | // for examples: |
| 230 | // http://code.google.com/apis/protocolbuffers/docs/proto.html#options |
| 231 | // If this turns out to be popular, a web service will be set up |
| 232 | // to automatically assign option numbers. |
| 233 | |
| 234 | |
| 235 | message FileOptions { |
| 236 | |
| 237 | // Sets the Java package where classes generated from this .proto will be |
| 238 | // placed. By default, the proto package is used, but this is often |
| 239 | // inappropriate because proto packages do not normally start with backwards |
| 240 | // domain names. |
| 241 | optional string java_package = 1; |
| 242 | |
| 243 | |
| 244 | // If set, all the classes from the .proto file are wrapped in a single |
| 245 | // outer class with the given name. This applies to both Proto1 |
| 246 | // (equivalent to the old "--one_java_file" option) and Proto2 (where |
| 247 | // a .proto always translates to a single class, but you may want to |
| 248 | // explicitly choose the class name). |
| 249 | optional string java_outer_classname = 8; |
| 250 | |
| 251 | // If set true, then the Java code generator will generate a separate .java |
| 252 | // file for each top-level message, enum, and service defined in the .proto |
| 253 | // file. Thus, these types will *not* be nested inside the outer class |
| 254 | // named by java_outer_classname. However, the outer class will still be |
| 255 | // generated to contain the file's getDescriptor() method as well as any |
| 256 | // top-level extensions defined in the file. |
| 257 | optional bool java_multiple_files = 10 [default=false]; |
| 258 | |
| 259 | // If set true, then the Java code generator will generate equals() and |
| 260 | // hashCode() methods for all messages defined in the .proto file. This is |
| 261 | // purely a speed optimization, as the AbstractMessage base class includes |
| 262 | // reflection-based implementations of these methods. |
| 263 | optional bool java_generate_equals_and_hash = 20 [default=false]; |
| 264 | |
| 265 | // Generated classes can be optimized for speed or code size. |
| 266 | enum OptimizeMode { |
| 267 | SPEED = 1; // Generate complete code for parsing, serialization, |
| 268 | // etc. |
| 269 | CODE_SIZE = 2; // Use ReflectionOps to implement these methods. |
| 270 | LITE_RUNTIME = 3; // Generate code using MessageLite and the lite runtime. |
| 271 | } |
| 272 | optional OptimizeMode optimize_for = 9 [default=SPEED]; |
| 273 | |
| 274 | |
| 275 | |
| 276 | |
| 277 | // Should generic services be generated in each language? "Generic" services |
| 278 | // are not specific to any particular RPC system. They are generated by the |
| 279 | // main code generators in each language (without additional plugins). |
| 280 | // Generic services were the only kind of service generation supported by |
| 281 | // early versions of proto2. |
| 282 | // |
| 283 | // Generic services are now considered deprecated in favor of using plugins |
| 284 | // that generate code specific to your particular RPC system. Therefore, |
| 285 | // these default to false. Old code which depends on generic services should |
| 286 | // explicitly set them to true. |
| 287 | optional bool cc_generic_services = 16 [default=false]; |
| 288 | optional bool java_generic_services = 17 [default=false]; |
| 289 | optional bool py_generic_services = 18 [default=false]; |
| 290 | |
| 291 | // The parser stores options it doesn't recognize here. See above. |
| 292 | repeated UninterpretedOption uninterpreted_option = 999; |
| 293 | |
| 294 | // Clients can define custom options in extensions of this message. See above. |
| 295 | extensions 1000 to max; |
| 296 | } |
| 297 | |
| 298 | message MessageOptions { |
| 299 | // Set true to use the old proto1 MessageSet wire format for extensions. |
| 300 | // This is provided for backwards-compatibility with the MessageSet wire |
| 301 | // format. You should not use this for any other reason: It's less |
| 302 | // efficient, has fewer features, and is more complicated. |
| 303 | // |
| 304 | // The message must be defined exactly as follows: |
| 305 | // message Foo { |
| 306 | // option message_set_wire_format = true; |
| 307 | // extensions 4 to max; |
| 308 | // } |
| 309 | // Note that the message cannot have any defined fields; MessageSets only |
| 310 | // have extensions. |
| 311 | // |
| 312 | // All extensions of your type must be singular messages; e.g. they cannot |
| 313 | // be int32s, enums, or repeated messages. |
| 314 | // |
| 315 | // Because this is an option, the above two restrictions are not enforced by |
| 316 | // the protocol compiler. |
| 317 | optional bool message_set_wire_format = 1 [default=false]; |
| 318 | |
| 319 | // Disables the generation of the standard "descriptor()" accessor, which can |
| 320 | // conflict with a field of the same name. This is meant to make migration |
| 321 | // from proto1 easier; new code should avoid fields named "descriptor". |
| 322 | optional bool no_standard_descriptor_accessor = 2 [default=false]; |
| 323 | |
| 324 | // The parser stores options it doesn't recognize here. See above. |
| 325 | repeated UninterpretedOption uninterpreted_option = 999; |
| 326 | |
| 327 | // Clients can define custom options in extensions of this message. See above. |
| 328 | extensions 1000 to max; |
| 329 | } |
| 330 | |
| 331 | message FieldOptions { |
| 332 | // The ctype option instructs the C++ code generator to use a different |
| 333 | // representation of the field than it normally would. See the specific |
| 334 | // options below. This option is not yet implemented in the open source |
| 335 | // release -- sorry, we'll try to include it in a future version! |
| 336 | optional CType ctype = 1 [default = STRING]; |
| 337 | enum CType { |
| 338 | // Default mode. |
| 339 | STRING = 0; |
| 340 | |
| 341 | CORD = 1; |
| 342 | |
| 343 | STRING_PIECE = 2; |
| 344 | } |
| 345 | // The packed option can be enabled for repeated primitive fields to enable |
| 346 | // a more efficient representation on the wire. Rather than repeatedly |
| 347 | // writing the tag and type for each element, the entire array is encoded as |
| 348 | // a single length-delimited blob. |
| 349 | optional bool packed = 2; |
| 350 | |
| 351 | |
| 352 | // Is this field deprecated? |
| 353 | // Depending on the target platform, this can emit Deprecated annotations |
| 354 | // for accessors, or it will be completely ignored; in the very least, this |
| 355 | // is a formalization for deprecating fields. |
| 356 | optional bool deprecated = 3 [default=false]; |
| 357 | |
| 358 | // EXPERIMENTAL. DO NOT USE. |
| 359 | // For "map" fields, the name of the field in the enclosed type that |
| 360 | // is the key for this map. For example, suppose we have: |
| 361 | // message Item { |
| 362 | // required string name = 1; |
| 363 | // required string value = 2; |
| 364 | // } |
| 365 | // message Config { |
| 366 | // repeated Item items = 1 [experimental_map_key="name"]; |
| 367 | // } |
| 368 | // In this situation, the map key for Item will be set to "name". |
| 369 | // TODO: Fully-implement this, then remove the "experimental_" prefix. |
| 370 | optional string experimental_map_key = 9; |
| 371 | |
| 372 | // The parser stores options it doesn't recognize here. See above. |
| 373 | repeated UninterpretedOption uninterpreted_option = 999; |
| 374 | |
| 375 | // Clients can define custom options in extensions of this message. See above. |
| 376 | extensions 1000 to max; |
| 377 | } |
| 378 | |
| 379 | message EnumOptions { |
| 380 | |
| 381 | // The parser stores options it doesn't recognize here. See above. |
| 382 | repeated UninterpretedOption uninterpreted_option = 999; |
| 383 | |
| 384 | // Clients can define custom options in extensions of this message. See above. |
| 385 | extensions 1000 to max; |
| 386 | } |
| 387 | |
| 388 | message EnumValueOptions { |
| 389 | // The parser stores options it doesn't recognize here. See above. |
| 390 | repeated UninterpretedOption uninterpreted_option = 999; |
| 391 | |
| 392 | // Clients can define custom options in extensions of this message. See above. |
| 393 | extensions 1000 to max; |
| 394 | } |
| 395 | |
| 396 | message ServiceOptions { |
| 397 | |
| 398 | // Note: Field numbers 1 through 32 are reserved for Google's internal RPC |
| 399 | // framework. We apologize for hoarding these numbers to ourselves, but |
| 400 | // we were already using them long before we decided to release Protocol |
| 401 | // Buffers. |
| 402 | |
| 403 | // The parser stores options it doesn't recognize here. See above. |
| 404 | repeated UninterpretedOption uninterpreted_option = 999; |
| 405 | |
| 406 | // Clients can define custom options in extensions of this message. See above. |
| 407 | extensions 1000 to max; |
| 408 | } |
| 409 | |
| 410 | message MethodOptions { |
| 411 | |
| 412 | // Note: Field numbers 1 through 32 are reserved for Google's internal RPC |
| 413 | // framework. We apologize for hoarding these numbers to ourselves, but |
| 414 | // we were already using them long before we decided to release Protocol |
| 415 | // Buffers. |
| 416 | |
| 417 | // The parser stores options it doesn't recognize here. See above. |
| 418 | repeated UninterpretedOption uninterpreted_option = 999; |
| 419 | |
| 420 | // Clients can define custom options in extensions of this message. See above. |
| 421 | extensions 1000 to max; |
| 422 | } |
| 423 | |
| 424 | // A message representing a option the parser does not recognize. This only |
| 425 | // appears in options protos created by the compiler::Parser class. |
| 426 | // DescriptorPool resolves these when building Descriptor objects. Therefore, |
| 427 | // options protos in descriptor objects (e.g. returned by Descriptor::options(), |
| 428 | // or produced by Descriptor::CopyTo()) will never have UninterpretedOptions |
| 429 | // in them. |
| 430 | message UninterpretedOption { |
| 431 | // The name of the uninterpreted option. Each string represents a segment in |
| 432 | // a dot-separated name. is_extension is true iff a segment represents an |
| 433 | // extension (denoted with parentheses in options specs in .proto files). |
| 434 | // E.g.,{ ["foo", false], ["bar.baz", true], ["qux", false] } represents |
| 435 | // "foo.(bar.baz).qux". |
| 436 | message NamePart { |
| 437 | required string name_part = 1; |
| 438 | required bool is_extension = 2; |
| 439 | } |
| 440 | repeated NamePart name = 2; |
| 441 | |
| 442 | // The value of the uninterpreted option, in whatever type the tokenizer |
| 443 | // identified it as during parsing. Exactly one of these should be set. |
| 444 | optional string identifier_value = 3; |
| 445 | optional uint64 positive_int_value = 4; |
| 446 | optional int64 negative_int_value = 5; |
| 447 | optional double double_value = 6; |
| 448 | optional bytes string_value = 7; |
| 449 | optional string aggregate_value = 8; |
| 450 | } |
| 451 | |
| 452 | // =================================================================== |
| 453 | // Optional source code info |
| 454 | |
| 455 | // Encapsulates information about the original source file from which a |
| 456 | // FileDescriptorProto was generated. |
| 457 | message SourceCodeInfo { |
| 458 | // A Location identifies a piece of source code in a .proto file which |
| 459 | // corresponds to a particular definition. This information is intended |
| 460 | // to be useful to IDEs, code indexers, documentation generators, and similar |
| 461 | // tools. |
| 462 | // |
| 463 | // For example, say we have a file like: |
| 464 | // message Foo { |
| 465 | // optional string foo = 1; |
| 466 | // } |
| 467 | // Let's look at just the field definition: |
| 468 | // optional string foo = 1; |
| 469 | // ^ ^^ ^^ ^ ^^^ |
| 470 | // a bc de f ghi |
| 471 | // We have the following locations: |
| 472 | // span path represents |
| 473 | // [a,i) [ 4, 0, 2, 0 ] The whole field definition. |
| 474 | // [a,b) [ 4, 0, 2, 0, 4 ] The label (optional). |
| 475 | // [c,d) [ 4, 0, 2, 0, 5 ] The type (string). |
| 476 | // [e,f) [ 4, 0, 2, 0, 1 ] The name (foo). |
| 477 | // [g,h) [ 4, 0, 2, 0, 3 ] The number (1). |
| 478 | // |
| 479 | // Notes: |
| 480 | // - A location may refer to a repeated field itself (i.e. not to any |
| 481 | // particular index within it). This is used whenever a set of elements are |
| 482 | // logically enclosed in a single code segment. For example, an entire |
| 483 | // extend block (possibly containing multiple extension definitions) will |
| 484 | // have an outer location whose path refers to the "extensions" repeated |
| 485 | // field without an index. |
| 486 | // - Multiple locations may have the same path. This happens when a single |
| 487 | // logical declaration is spread out across multiple places. The most |
| 488 | // obvious example is the "extend" block again -- there may be multiple |
| 489 | // extend blocks in the same scope, each of which will have the same path. |
| 490 | // - A location's span is not always a subset of its parent's span. For |
| 491 | // example, the "extendee" of an extension declaration appears at the |
| 492 | // beginning of the "extend" block and is shared by all extensions within |
| 493 | // the block. |
| 494 | // - Just because a location's span is a subset of some other location's span |
| 495 | // does not mean that it is a descendent. For example, a "group" defines |
| 496 | // both a type and a field in a single declaration. Thus, the locations |
| 497 | // corresponding to the type and field and their components will overlap. |
| 498 | // - Code which tries to interpret locations should probably be designed to |
| 499 | // ignore those that it doesn't understand, as more types of locations could |
| 500 | // be recorded in the future. |
| 501 | repeated Location location = 1; |
| 502 | message Location { |
| 503 | // Identifies which part of the FileDescriptorProto was defined at this |
| 504 | // location. |
| 505 | // |
| 506 | // Each element is a field number or an index. They form a path from |
| 507 | // the root FileDescriptorProto to the place where the definition. For |
| 508 | // example, this path: |
| 509 | // [ 4, 3, 2, 7, 1 ] |
| 510 | // refers to: |
| 511 | // file.message_type(3) // 4, 3 |
| 512 | // .field(7) // 2, 7 |
| 513 | // .name() // 1 |
| 514 | // This is because FileDescriptorProto.message_type has field number 4: |
| 515 | // repeated DescriptorProto message_type = 4; |
| 516 | // and DescriptorProto.field has field number 2: |
| 517 | // repeated FieldDescriptorProto field = 2; |
| 518 | // and FieldDescriptorProto.name has field number 1: |
| 519 | // optional string name = 1; |
| 520 | // |
| 521 | // Thus, the above path gives the location of a field name. If we removed |
| 522 | // the last element: |
| 523 | // [ 4, 3, 2, 7 ] |
| 524 | // this path refers to the whole field declaration (from the beginning |
| 525 | // of the label to the terminating semicolon). |
| 526 | repeated int32 path = 1 [packed=true]; |
| 527 | |
| 528 | // Always has exactly three or four elements: start line, start column, |
| 529 | // end line (optional, otherwise assumed same as start line), end column. |
| 530 | // These are packed into a single field for efficiency. Note that line |
| 531 | // and column numbers are zero-based -- typically you will want to add |
| 532 | // 1 to each before displaying to a user. |
| 533 | repeated int32 span = 2 [packed=true]; |
| 534 | |
| 535 | // TODO(kenton): Record comments appearing before and after the |
| 536 | // declaration. |
| 537 | } |
| 538 | } |