cannam@132: # Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors
cannam@132: # Licensed under the MIT License:
cannam@132: #
cannam@132: # Permission is hereby granted, free of charge, to any person obtaining a copy
cannam@132: # of this software and associated documentation files (the "Software"), to deal
cannam@132: # in the Software without restriction, including without limitation the rights
cannam@132: # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
cannam@132: # copies of the Software, and to permit persons to whom the Software is
cannam@132: # furnished to do so, subject to the following conditions:
cannam@132: #
cannam@132: # The above copyright notice and this permission notice shall be included in
cannam@132: # all copies or substantial portions of the Software.
cannam@132: #
cannam@132: # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
cannam@132: # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
cannam@132: # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
cannam@132: # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
cannam@132: # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
cannam@132: # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
cannam@132: # THE SOFTWARE.
cannam@132: 
cannam@132: using Cxx = import "/capnp/c++.capnp";
cannam@132: 
cannam@132: @0xa93fc509624c72d9;
cannam@132: $Cxx.namespace("capnp::schema");
cannam@132: 
cannam@132: using Id = UInt64;
cannam@132: # The globally-unique ID of a file, type, or annotation.
cannam@132: 
cannam@132: struct Node {
cannam@132:   id @0 :Id;
cannam@132: 
cannam@132:   displayName @1 :Text;
cannam@132:   # Name to present to humans to identify this Node.  You should not attempt to parse this.  Its
cannam@132:   # format could change.  It is not guaranteed to be unique.
cannam@132:   #
cannam@132:   # (On Zooko's triangle, this is the node's nickname.)
cannam@132: 
cannam@132:   displayNamePrefixLength @2 :UInt32;
cannam@132:   # If you want a shorter version of `displayName` (just naming this node, without its surrounding
cannam@132:   # scope), chop off this many characters from the beginning of `displayName`.
cannam@132: 
cannam@132:   scopeId @3 :Id;
cannam@132:   # ID of the lexical parent node.  Typically, the scope node will have a NestedNode pointing back
cannam@132:   # at this node, but robust code should avoid relying on this (and, in fact, group nodes are not
cannam@132:   # listed in the outer struct's nestedNodes, since they are listed in the fields).  `scopeId` is
cannam@132:   # zero if the node has no parent, which is normally only the case with files, but should be
cannam@132:   # allowed for any kind of node (in order to make runtime type generation easier).
cannam@132: 
cannam@132:   parameters @32 :List(Parameter);
cannam@132:   # If this node is parameterized (generic), the list of parameters. Empty for non-generic types.
cannam@132: 
cannam@132:   isGeneric @33 :Bool;
cannam@132:   # True if this node is generic, meaning that it or one of its parent scopes has a non-empty
cannam@132:   # `parameters`.
cannam@132: 
cannam@132:   struct Parameter {
cannam@132:     # Information about one of the node's parameters.
cannam@132: 
cannam@132:     name @0 :Text;
cannam@132:   }
cannam@132: 
cannam@132:   nestedNodes @4 :List(NestedNode);
cannam@132:   # List of nodes nested within this node, along with the names under which they were declared.
cannam@132: 
cannam@132:   struct NestedNode {
cannam@132:     name @0 :Text;
cannam@132:     # Unqualified symbol name.  Unlike Node.displayName, this *can* be used programmatically.
cannam@132:     #
cannam@132:     # (On Zooko's triangle, this is the node's petname according to its parent scope.)
cannam@132: 
cannam@132:     id @1 :Id;
cannam@132:     # ID of the nested node.  Typically, the target node's scopeId points back to this node, but
cannam@132:     # robust code should avoid relying on this.
cannam@132:   }
cannam@132: 
cannam@132:   annotations @5 :List(Annotation);
cannam@132:   # Annotations applied to this node.
cannam@132: 
cannam@132:   union {
cannam@132:     # Info specific to each kind of node.
cannam@132: 
cannam@132:     file @6 :Void;
cannam@132: 
cannam@132:     struct :group {
cannam@132:       dataWordCount @7 :UInt16;
cannam@132:       # Size of the data section, in words.
cannam@132: 
cannam@132:       pointerCount @8 :UInt16;
cannam@132:       # Size of the pointer section, in pointers (which are one word each).
cannam@132: 
cannam@132:       preferredListEncoding @9 :ElementSize;
cannam@132:       # The preferred element size to use when encoding a list of this struct.  If this is anything
cannam@132:       # other than `inlineComposite` then the struct is one word or less in size and is a candidate
cannam@132:       # for list packing optimization.
cannam@132: 
cannam@132:       isGroup @10 :Bool;
cannam@132:       # If true, then this "struct" node is actually not an independent node, but merely represents
cannam@132:       # some named union or group within a particular parent struct.  This node's scopeId refers
cannam@132:       # to the parent struct, which may itself be a union/group in yet another struct.
cannam@132:       #
cannam@132:       # All group nodes share the same dataWordCount and pointerCount as the top-level
cannam@132:       # struct, and their fields live in the same ordinal and offset spaces as all other fields in
cannam@132:       # the struct.
cannam@132:       #
cannam@132:       # Note that a named union is considered a special kind of group -- in fact, a named union
cannam@132:       # is exactly equivalent to a group that contains nothing but an unnamed union.
cannam@132: 
cannam@132:       discriminantCount @11 :UInt16;
cannam@132:       # Number of fields in this struct which are members of an anonymous union, and thus may
cannam@132:       # overlap.  If this is non-zero, then a 16-bit discriminant is present indicating which
cannam@132:       # of the overlapping fields is active.  This can never be 1 -- if it is non-zero, it must be
cannam@132:       # two or more.
cannam@132:       #
cannam@132:       # Note that the fields of an unnamed union are considered fields of the scope containing the
cannam@132:       # union -- an unnamed union is not its own group.  So, a top-level struct may contain a
cannam@132:       # non-zero discriminant count.  Named unions, on the other hand, are equivalent to groups
cannam@132:       # containing unnamed unions.  So, a named union has its own independent schema node, with
cannam@132:       # `isGroup` = true.
cannam@132: 
cannam@132:       discriminantOffset @12 :UInt32;
cannam@132:       # If `discriminantCount` is non-zero, this is the offset of the union discriminant, in
cannam@132:       # multiples of 16 bits.
cannam@132: 
cannam@132:       fields @13 :List(Field);
cannam@132:       # Fields defined within this scope (either the struct's top-level fields, or the fields of
cannam@132:       # a particular group; see `isGroup`).
cannam@132:       #
cannam@132:       # The fields are sorted by ordinal number, but note that because groups share the same
cannam@132:       # ordinal space, the field's index in this list is not necessarily exactly its ordinal.
cannam@132:       # On the other hand, the field's position in this list does remain the same even as the
cannam@132:       # protocol evolves, since it is not possible to insert or remove an earlier ordinal.
cannam@132:       # Therefore, for most use cases, if you want to identify a field by number, it may make the
cannam@132:       # most sense to use the field's index in this list rather than its ordinal.
cannam@132:     }
cannam@132: 
cannam@132:     enum :group {
cannam@132:       enumerants@14 :List(Enumerant);
cannam@132:       # Enumerants ordered by numeric value (ordinal).
cannam@132:     }
cannam@132: 
cannam@132:     interface :group {
cannam@132:       methods @15 :List(Method);
cannam@132:       # Methods ordered by ordinal.
cannam@132: 
cannam@132:       superclasses @31 :List(Superclass);
cannam@132:       # Superclasses of this interface.
cannam@132:     }
cannam@132: 
cannam@132:     const :group {
cannam@132:       type @16 :Type;
cannam@132:       value @17 :Value;
cannam@132:     }
cannam@132: 
cannam@132:     annotation :group {
cannam@132:       type @18 :Type;
cannam@132: 
cannam@132:       targetsFile @19 :Bool;
cannam@132:       targetsConst @20 :Bool;
cannam@132:       targetsEnum @21 :Bool;
cannam@132:       targetsEnumerant @22 :Bool;
cannam@132:       targetsStruct @23 :Bool;
cannam@132:       targetsField @24 :Bool;
cannam@132:       targetsUnion @25 :Bool;
cannam@132:       targetsGroup @26 :Bool;
cannam@132:       targetsInterface @27 :Bool;
cannam@132:       targetsMethod @28 :Bool;
cannam@132:       targetsParam @29 :Bool;
cannam@132:       targetsAnnotation @30 :Bool;
cannam@132:     }
cannam@132:   }
cannam@132: }
cannam@132: 
cannam@132: struct Field {
cannam@132:   # Schema for a field of a struct.
cannam@132: 
cannam@132:   name @0 :Text;
cannam@132: 
cannam@132:   codeOrder @1 :UInt16;
cannam@132:   # Indicates where this member appeared in the code, relative to other members.
cannam@132:   # Code ordering may have semantic relevance -- programmers tend to place related fields
cannam@132:   # together.  So, using code ordering makes sense in human-readable formats where ordering is
cannam@132:   # otherwise irrelevant, like JSON.  The values of codeOrder are tightly-packed, so the maximum
cannam@132:   # value is count(members) - 1.  Fields that are members of a union are only ordered relative to
cannam@132:   # the other members of that union, so the maximum value there is count(union.members).
cannam@132: 
cannam@132:   annotations @2 :List(Annotation);
cannam@132: 
cannam@132:   const noDiscriminant :UInt16 = 0xffff;
cannam@132: 
cannam@132:   discriminantValue @3 :UInt16 = Field.noDiscriminant;
cannam@132:   # If the field is in a union, this is the value which the union's discriminant should take when
cannam@132:   # the field is active.  If the field is not in a union, this is 0xffff.
cannam@132: 
cannam@132:   union {
cannam@132:     slot :group {
cannam@132:       # A regular, non-group, non-fixed-list field.
cannam@132: 
cannam@132:       offset @4 :UInt32;
cannam@132:       # Offset, in units of the field's size, from the beginning of the section in which the field
cannam@132:       # resides.  E.g. for a UInt32 field, multiply this by 4 to get the byte offset from the
cannam@132:       # beginning of the data section.
cannam@132: 
cannam@132:       type @5 :Type;
cannam@132:       defaultValue @6 :Value;
cannam@132: 
cannam@132:       hadExplicitDefault @10 :Bool;
cannam@132:       # Whether the default value was specified explicitly.  Non-explicit default values are always
cannam@132:       # zero or empty values.  Usually, whether the default value was explicit shouldn't matter.
cannam@132:       # The main use case for this flag is for structs representing method parameters:
cannam@132:       # explicitly-defaulted parameters may be allowed to be omitted when calling the method.
cannam@132:     }
cannam@132: 
cannam@132:     group :group {
cannam@132:       # A group.
cannam@132: 
cannam@132:       typeId @7 :Id;
cannam@132:       # The ID of the group's node.
cannam@132:     }
cannam@132:   }
cannam@132: 
cannam@132:   ordinal :union {
cannam@132:     implicit @8 :Void;
cannam@132:     explicit @9 :UInt16;
cannam@132:     # The original ordinal number given to the field.  You probably should NOT use this; if you need
cannam@132:     # a numeric identifier for a field, use its position within the field array for its scope.
cannam@132:     # The ordinal is given here mainly just so that the original schema text can be reproduced given
cannam@132:     # the compiled version -- i.e. so that `capnp compile -ocapnp` can do its job.
cannam@132:   }
cannam@132: }
cannam@132: 
cannam@132: struct Enumerant {
cannam@132:   # Schema for member of an enum.
cannam@132: 
cannam@132:   name @0 :Text;
cannam@132: 
cannam@132:   codeOrder @1 :UInt16;
cannam@132:   # Specifies order in which the enumerants were declared in the code.
cannam@132:   # Like Struct.Field.codeOrder.
cannam@132: 
cannam@132:   annotations @2 :List(Annotation);
cannam@132: }
cannam@132: 
cannam@132: struct Superclass {
cannam@132:   id @0 :Id;
cannam@132:   brand @1 :Brand;
cannam@132: }
cannam@132: 
cannam@132: struct Method {
cannam@132:   # Schema for method of an interface.
cannam@132: 
cannam@132:   name @0 :Text;
cannam@132: 
cannam@132:   codeOrder @1 :UInt16;
cannam@132:   # Specifies order in which the methods were declared in the code.
cannam@132:   # Like Struct.Field.codeOrder.
cannam@132: 
cannam@132:   implicitParameters @7 :List(Node.Parameter);
cannam@132:   # The parameters listed in [] (typically, type / generic parameters), whose bindings are intended
cannam@132:   # to be inferred rather than specified explicitly, although not all languages support this.
cannam@132: 
cannam@132:   paramStructType @2 :Id;
cannam@132:   # ID of the parameter struct type.  If a named parameter list was specified in the method
cannam@132:   # declaration (rather than a single struct parameter type) then a corresponding struct type is
cannam@132:   # auto-generated.  Such an auto-generated type will not be listed in the interface's
cannam@132:   # `nestedNodes` and its `scopeId` will be zero -- it is completely detached from the namespace.
cannam@132:   # (Awkwardly, it does of course inherit generic parameters from the method's scope, which makes
cannam@132:   # this a situation where you can't just climb the scope chain to find where a particular
cannam@132:   # generic parameter was introduced. Making the `scopeId` zero was a mistake.)
cannam@132: 
cannam@132:   paramBrand @5 :Brand;
cannam@132:   # Brand of param struct type.
cannam@132: 
cannam@132:   resultStructType @3 :Id;
cannam@132:   # ID of the return struct type; similar to `paramStructType`.
cannam@132: 
cannam@132:   resultBrand @6 :Brand;
cannam@132:   # Brand of result struct type.
cannam@132: 
cannam@132:   annotations @4 :List(Annotation);
cannam@132: }
cannam@132: 
cannam@132: struct Type {
cannam@132:   # Represents a type expression.
cannam@132: 
cannam@132:   union {
cannam@132:     # The ordinals intentionally match those of Value.
cannam@132: 
cannam@132:     void @0 :Void;
cannam@132:     bool @1 :Void;
cannam@132:     int8 @2 :Void;
cannam@132:     int16 @3 :Void;
cannam@132:     int32 @4 :Void;
cannam@132:     int64 @5 :Void;
cannam@132:     uint8 @6 :Void;
cannam@132:     uint16 @7 :Void;
cannam@132:     uint32 @8 :Void;
cannam@132:     uint64 @9 :Void;
cannam@132:     float32 @10 :Void;
cannam@132:     float64 @11 :Void;
cannam@132:     text @12 :Void;
cannam@132:     data @13 :Void;
cannam@132: 
cannam@132:     list :group {
cannam@132:       elementType @14 :Type;
cannam@132:     }
cannam@132: 
cannam@132:     enum :group {
cannam@132:       typeId @15 :Id;
cannam@132:       brand @21 :Brand;
cannam@132:     }
cannam@132:     struct :group {
cannam@132:       typeId @16 :Id;
cannam@132:       brand @22 :Brand;
cannam@132:     }
cannam@132:     interface :group {
cannam@132:       typeId @17 :Id;
cannam@132:       brand @23 :Brand;
cannam@132:     }
cannam@132: 
cannam@132:     anyPointer :union {
cannam@132:       unconstrained :union {
cannam@132:         # A regular AnyPointer.
cannam@132:         #
cannam@132:         # The name "unconstained" means as opposed to constraining it to match a type parameter.
cannam@132:         # In retrospect this name is probably a poor choice given that it may still be constrained
cannam@132:         # to be a struct, list, or capability.
cannam@132: 
cannam@132:         anyKind @18 :Void;       # truly AnyPointer
cannam@132:         struct @25 :Void;        # AnyStruct
cannam@132:         list @26 :Void;          # AnyList
cannam@132:         capability @27 :Void;    # Capability
cannam@132:       }
cannam@132: 
cannam@132:       parameter :group {
cannam@132:         # This is actually a reference to a type parameter defined within this scope.
cannam@132: 
cannam@132:         scopeId @19 :Id;
cannam@132:         # ID of the generic type whose parameter we're referencing. This should be a parent of the
cannam@132:         # current scope.
cannam@132: 
cannam@132:         parameterIndex @20 :UInt16;
cannam@132:         # Index of the parameter within the generic type's parameter list.
cannam@132:       }
cannam@132: 
cannam@132:       implicitMethodParameter :group {
cannam@132:         # This is actually a reference to an implicit (generic) parameter of a method. The only
cannam@132:         # legal context for this type to appear is inside Method.paramBrand or Method.resultBrand.
cannam@132: 
cannam@132:         parameterIndex @24 :UInt16;
cannam@132:       }
cannam@132:     }
cannam@132:   }
cannam@132: }
cannam@132: 
cannam@132: struct Brand {
cannam@132:   # Specifies bindings for parameters of generics. Since these bindings turn a generic into a
cannam@132:   # non-generic, we call it the "brand".
cannam@132: 
cannam@132:   scopes @0 :List(Scope);
cannam@132:   # For each of the target type and each of its parent scopes, a parameterization may be included
cannam@132:   # in this list. If no parameterization is included for a particular relevant scope, then either
cannam@132:   # that scope has no parameters or all parameters should be considered to be `AnyPointer`.
cannam@132: 
cannam@132:   struct Scope {
cannam@132:     scopeId @0 :Id;
cannam@132:     # ID of the scope to which these params apply.
cannam@132: 
cannam@132:     union {
cannam@132:       bind @1 :List(Binding);
cannam@132:       # List of parameter bindings.
cannam@132: 
cannam@132:       inherit @2 :Void;
cannam@132:       # The place where this Brand appears is actually within this scope or a sub-scope,
cannam@132:       # and the bindings for this scope should be inherited from the reference point.
cannam@132:     }
cannam@132:   }
cannam@132: 
cannam@132:   struct Binding {
cannam@132:     union {
cannam@132:       unbound @0 :Void;
cannam@132:       type @1 :Type;
cannam@132: 
cannam@132:       # TODO(someday): Allow non-type parameters? Unsure if useful.
cannam@132:     }
cannam@132:   }
cannam@132: }
cannam@132: 
cannam@132: struct Value {
cannam@132:   # Represents a value, e.g. a field default value, constant value, or annotation value.
cannam@132: 
cannam@132:   union {
cannam@132:     # The ordinals intentionally match those of Type.
cannam@132: 
cannam@132:     void @0 :Void;
cannam@132:     bool @1 :Bool;
cannam@132:     int8 @2 :Int8;
cannam@132:     int16 @3 :Int16;
cannam@132:     int32 @4 :Int32;
cannam@132:     int64 @5 :Int64;
cannam@132:     uint8 @6 :UInt8;
cannam@132:     uint16 @7 :UInt16;
cannam@132:     uint32 @8 :UInt32;
cannam@132:     uint64 @9 :UInt64;
cannam@132:     float32 @10 :Float32;
cannam@132:     float64 @11 :Float64;
cannam@132:     text @12 :Text;
cannam@132:     data @13 :Data;
cannam@132: 
cannam@132:     list @14 :AnyPointer;
cannam@132: 
cannam@132:     enum @15 :UInt16;
cannam@132:     struct @16 :AnyPointer;
cannam@132: 
cannam@132:     interface @17 :Void;
cannam@132:     # The only interface value that can be represented statically is "null", whose methods always
cannam@132:     # throw exceptions.
cannam@132: 
cannam@132:     anyPointer @18 :AnyPointer;
cannam@132:   }
cannam@132: }
cannam@132: 
cannam@132: struct Annotation {
cannam@132:   # Describes an annotation applied to a declaration.  Note AnnotationNode describes the
cannam@132:   # annotation's declaration, while this describes a use of the annotation.
cannam@132: 
cannam@132:   id @0 :Id;
cannam@132:   # ID of the annotation node.
cannam@132: 
cannam@132:   brand @2 :Brand;
cannam@132:   # Brand of the annotation.
cannam@132:   #
cannam@132:   # Note that the annotation itself is not allowed to be parameterized, but its scope might be.
cannam@132: 
cannam@132:   value @1 :Value;
cannam@132: }
cannam@132: 
cannam@132: enum ElementSize {
cannam@132:   # Possible element sizes for encoded lists.  These correspond exactly to the possible values of
cannam@132:   # the 3-bit element size component of a list pointer.
cannam@132: 
cannam@132:   empty @0;    # aka "void", but that's a keyword.
cannam@132:   bit @1;
cannam@132:   byte @2;
cannam@132:   twoBytes @3;
cannam@132:   fourBytes @4;
cannam@132:   eightBytes @5;
cannam@132:   pointer @6;
cannam@132:   inlineComposite @7;
cannam@132: }
cannam@132: 
cannam@132: struct CodeGeneratorRequest {
cannam@132:   nodes @0 :List(Node);
cannam@132:   # All nodes parsed by the compiler, including for the files on the command line and their
cannam@132:   # imports.
cannam@132: 
cannam@132:   requestedFiles @1 :List(RequestedFile);
cannam@132:   # Files which were listed on the command line.
cannam@132: 
cannam@132:   struct RequestedFile {
cannam@132:     id @0 :Id;
cannam@132:     # ID of the file.
cannam@132: 
cannam@132:     filename @1 :Text;
cannam@132:     # Name of the file as it appeared on the command-line (minus the src-prefix).  You may use
cannam@132:     # this to decide where to write the output.
cannam@132: 
cannam@132:     imports @2 :List(Import);
cannam@132:     # List of all imported paths seen in this file.
cannam@132: 
cannam@132:     struct Import {
cannam@132:       id @0 :Id;
cannam@132:       # ID of the imported file.
cannam@132: 
cannam@132:       name @1 :Text;
cannam@132:       # Name which *this* file used to refer to the foreign file.  This may be a relative name.
cannam@132:       # This information is provided because it might be useful for code generation, e.g. to
cannam@132:       # generate #include directives in C++.  We don't put this in Node.file because this
cannam@132:       # information is only meaningful at compile time anyway.
cannam@132:       #
cannam@132:       # (On Zooko's triangle, this is the import's petname according to the importing file.)
cannam@132:     }
cannam@132:   }
cannam@132: }