mojo/public/interfaces/bindings/mojom_descriptors.mojom

// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

[DartPackage="mojo.bindings.types",
JavaPackage="org.chromium.mojo.bindings.types"]
module mojo.bindings.types;

import "mojom_types.mojom";

/**
* A MojomDescriptor contains descriptions of a collection of related Mojom
* types and constants. The types may be fully resolved or only partially
* resolved. (See mojom_types.mojom for a discussion of what that means.)
*
* A MojomDescritpor allows the names and other declaration data found in a
* .mojom file to optionally be stored along with the type information. Because
* names used in a source file may be considered private information, different
* implementations of |MojomDescriptor| will have different policies regarding
* the storing of names.
*
* A Mojom Descriptor is useful in various contexts depending on
* whether or not the types are fully resolved and how much of the names and
* other declaration data is stored.
*
* For example the front end of a Mojom compiler may use a MojomDescriptor
* to help express the result of parsing a single .mojom file. In this case
* we would expect that the MojomDescriptor would be only partially resolved
* because some of the type references in the .mojom file will use identifiers
* that are defined in other .mojom files. We would also expect that a
* MojomDescriptor used in this manner would contain full declaration data
* since this will be needed by later stages of the compiler.
*
* A later stage of the Mojom compiler may combine multiple partially resolved
* MojomDescriptors into one fully-resolved MojomDescriptor that could then
* be used by code generators. Again we would expect full declaration data to
* be stored here.
*
* As another example a MojomDescriptor might be used by an IDE in order to
* help a developer write client code that calls a given Mojo service. Such a
* MojomDescriptor would probably be fully-resolved and may or may not store
* full declaration data.
*
* As a final example, a MojomDescriptor may be used at run time to parse and
* understand a serialized Mojo message. Such a MojomDescriptor may choose
* to not store any declaration data.
*
* As discussed in mojom_types.mojom, a resolved TypeReference refers to the
* user-defined type that it represents via a string called |type_key|.
* A MojomDescriptor contains the mapping from type_keys to user defined types.
* Similarly a resolved ConstantReference refers to the user-defined constant
* that it represents via a string called |constant_key| and a MojomDescriptor
* also contains a mapping from constant_keys to user-defined constants.
*/

// A description of a related set of Mojom types and constants.
struct MojomDescriptor {
  // All the resolved user-defined types known to this descriptor. The keys are
  // the |type_key|s.
  map<string, UserDefinedType> resolved_identifiers;

  // All the resolved declared constants known to this descriptor. The keys are
  // the |constant_key|s.
  map<string, DeclaredConstant> resolved_constants;

  // All of the keys known to this descriptor, organized by type.
  KeysByType? keys_by_type;

  // A list of all of the unresolved type references occurring in this
  // MojomDescriptor. This descriptor is fully resolved just in case this
  // list and |unresolved_constant_references| are empty.
  array<TypeReference> unresolved_type_references;

  // A list of all of the unresolved constant references occurring in this
  // MojomDescriptor. This descriptor is fully resolved just in case this
  // list and |unresolved_type_references| are empty.
  array<ConstantReference> unresolved_constant_references;
};

// Represents a user-defined type referenced
// via its identifier from another Mojom object.
union UserDefinedType {
  MojomEnum enum_type;
  MojomStruct struct_type;
  MojomUnion union_type;
  MojomInterface interface_type;
};

// A KeysByType struct organizes by type all of the type and constant keys known
// to an associated MojomDescriptor.
struct KeysByType {
  // All the type_keys known to the owning MojomDescriptor, organized by
  // type;
  array<string>? interfaces;
  array<string>? structs;
  array<string>? unions;
  array<string>? top_level_enums;
  array<string>? embedded_enums;

  // All the constant_keys known to the owning MojomDescriptor.
  array<string>? top_level_constants;
  array<string>? embedded_constants;
};