1# Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors
2# Licensed under the MIT License:
3#
4# Permission is hereby granted, free of charge, to any person obtaining a copy
5# of this software and associated documentation files (the "Software"), to deal
6# in the Software without restriction, including without limitation the rights
7# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8# copies of the Software, and to permit persons to whom the Software is
9# furnished to do so, subject to the following conditions:
10#
11# The above copyright notice and this permission notice shall be included in
12# all copies or substantial portions of the Software.
13#
14# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
20# THE SOFTWARE.
21
22@0xc56be168dcbbc3c6;
23# The structures in this file correspond to the AST of the Cap'n Proto schema language.
24#
25# This file is intended to be used internally by capnpc.  Mostly, it is useful because it is more
26# convenient than defining data classes in C++, particularly where variant types (unions) are
27# needed.  Over time, this file may change in backwards-incompatible ways.
28
29using Cxx = import "/capnp/c++.capnp";
30
31$Cxx.namespace("capnp::compiler");
32
33# TODO(someday):  Here's a case where parameterized types might be nice, but note that it would
34#   need to support primitive parameters...
35struct LocatedText {
36  value @0 :Text;
37  startByte @1 :UInt32;
38  endByte @2 :UInt32;
39}
40
41struct LocatedInteger {
42  value @0 :UInt64;
43  startByte @1 :UInt32;
44  endByte @2 :UInt32;
45}
46
47struct LocatedFloat {
48  value @0 :Float64;
49  startByte @1 :UInt32;
50  endByte @2 :UInt32;
51}
52
53struct Expression {
54  # An expression. May evaluate to a type, a value, or a declaration (i.e. some named thing which
55  # is neither a type nor a value, like an annotation declaration).
56
57  union {
58    unknown @0 :Void;  # e.g. parse error; downstream should ignore
59    positiveInt @1 :UInt64;
60    negativeInt @2 :UInt64;
61    float @3 :Float64;
62    string @4 :Text;
63    binary @10 :Data;
64
65    relativeName @5 :LocatedText;
66    # Just an identifier.
67
68    absoluteName @15 :LocatedText;
69    # An identifier with leading '.'.
70
71    import @16 :LocatedText;
72    # An import directive.
73
74    embed @17 :LocatedText;
75    # An embed directive.
76
77    list @6 :List(Expression);
78    # Bracketed list; members are never named.
79
80    tuple @7 :List(Param);
81    # Parenthesized list, possibly with named members.
82    #
83    # Note that a parenthesized list with one unnamed member is just a parenthesized expression,
84    # not a tuple, and so will never be represented as a tuple.
85
86    application :group {
87      # Application of a function to some parameters, e.g. "foo(bar, baz)".
88
89      function @11 :Expression;
90      params @12 :List(Param);
91    }
92
93    member :group {
94      # A named member of an aggregate, e.g. "foo.bar".
95
96      parent @13 :Expression;
97      name @14 :LocatedText;
98    }
99
100    # TODO(someday): Basic arithmetic?
101  }
102
103  struct Param {
104    union {
105      unnamed @0 :Void;          # Just a value.
106      named @1 :LocatedText;     # "name = value"
107    }
108    value @2 :Expression;
109  }
110
111  startByte @8 :UInt32;
112  endByte @9 :UInt32;
113}
114
115struct Declaration {
116  # A declaration statement.
117
118  name @0 :LocatedText;
119
120  id :union {
121    unspecified @1 :Void;
122    uid @2 :LocatedInteger;
123    ordinal @3 :LocatedInteger;  # limited to 16 bits
124  }
125
126  parameters @57 :List(BrandParameter);
127  # If this node is parameterized (generic), the list of parameters. Empty for non-generic types.
128
129  struct BrandParameter {
130    name @0 :Text;
131    startByte @1 :UInt32;
132    endByte @2 :UInt32;
133  }
134
135  nestedDecls @4 :List(Declaration);
136
137  annotations @5 :List(AnnotationApplication);
138  struct AnnotationApplication {
139    name @0 :Expression;
140
141    value :union {
142      none @1 :Void;   # None specified; implies void value.
143      expression @2 :Expression;
144    }
145  }
146
147  startByte @6 :UInt32;
148  endByte @7 :UInt32;
149
150  docComment @8 :Text;
151
152  union {
153    file @9 :Void;
154
155    using :group {
156      target @10 :Expression;
157    }
158
159    const :group {
160      type @11 :Expression;
161      value @12 :Expression;
162    }
163
164    enum @13 :Void;
165    enumerant @14 :Void;
166
167    struct @15 :Void;
168    field :group {
169      type @16 :Expression;
170      defaultValue :union {
171        none @17 :Void;
172        value @18 :Expression;
173      }
174    }
175    union @19 :Void;
176    group @20 :Void;
177
178    interface :group {
179      superclasses @21 :List(Expression);
180    }
181    method :group {
182      params @22 :ParamList;
183      results :union {
184        none @23 :Void;
185        explicit @24 :ParamList;
186      }
187    }
188
189    annotation :group {
190      type @25 :Expression;
191
192      targetsFile @26 :Bool;
193      targetsConst @27 :Bool;
194      targetsEnum @28 :Bool;
195      targetsEnumerant @29 :Bool;
196      targetsStruct @30 :Bool;
197      targetsField @31 :Bool;
198      targetsUnion @32 :Bool;
199      targetsGroup @33 :Bool;
200      targetsInterface @34 :Bool;
201      targetsMethod @35 :Bool;
202      targetsParam @36 :Bool;
203      targetsAnnotation @37 :Bool;
204    }
205
206    nakedId @38 :LocatedInteger;
207    nakedAnnotation @39 :AnnotationApplication;
208    # A floating UID or annotation (allowed at the file top level).
209
210    # The following declaration types are not produced by the parser, but are declared here
211    # so that the compiler can handle symbol name lookups more uniformly.
212    #
213    # New union members added here will magically become visible in the global scope.
214    # E.g. "builtinFoo" becomes visible as "Foo".
215    builtinVoid @40 :Void;
216    builtinBool @41 :Void;
217    builtinInt8 @42 :Void;
218    builtinInt16 @43 :Void;
219    builtinInt32 @44 :Void;
220    builtinInt64 @45 :Void;
221    builtinUInt8 @46 :Void;
222    builtinUInt16 @47 :Void;
223    builtinUInt32 @48 :Void;
224    builtinUInt64 @49 :Void;
225    builtinFloat32 @50 :Void;
226    builtinFloat64 @51 :Void;
227    builtinText @52 :Void;
228    builtinData @53 :Void;
229    builtinList @54 :Void $builtinParams([(name = "Element")]);
230    builtinObject @55 :Void;  # only for "renamed to AnyPointer" error message
231    builtinAnyPointer @56 :Void;
232    builtinAnyStruct @58 :Void;
233    builtinAnyList @59 :Void;
234    builtinCapability @60 :Void;
235  }
236
237  annotation builtinParams @0x94099c3f9eb32d6b (field) :List(BrandParameter);
238
239  struct ParamList {
240    # A list of method parameters or method returns.
241
242    union {
243      namedList @0 :List(Param);
244
245      type @1 :Expression;
246      # Specified some other struct type instead of a named list.
247
248      stream @4 :Void;
249      # The keyword "stream".
250    }
251
252    startByte @2 :UInt32;
253    endByte @3 :UInt32;
254  }
255  struct Param {
256    name @0 :LocatedText;  # If null, param failed to parse.
257    type @1 :Expression;
258    annotations @2 :List(AnnotationApplication);
259    defaultValue :union {
260      none @3 :Void;
261      value @4 :Expression;
262    }
263
264    startByte @5 :UInt32;
265    endByte @6 :UInt32;
266  }
267}
268
269struct ParsedFile {
270  root @0 :Declaration;
271}
272