Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 286 lines (233 sloc) 13.611 kb
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
1 = Introduction =
2
3 The API discovery component of xsbt analyzes the source code of a project and extracts the API. This discovery component operates as a phase during normal compilation. This phase exists in the 'compiler-interface' subproject and is discussed in section 'API Compiler Phase'. The API of a source file is discussed in 'API Specification'.
4
5 The discovery phase provides a representation of the API in the form of a data structure, which is discussed in the section 'API Data Structure'. This data structure is a simple hierarchy of Java classes and enums generated from a definition file. The generated data structure exists in the 'interface' project under the 'xsbti.api' package.
6
7 The file that defines the hierarchy is processed by a small datatype generating subproject called 'datatype'. This subproject defines a basic syntax for creating an immutable data structure hierarchy in Java. The output is in Java in order to use the data structure across Scala versions.
8
833688c @harrah API equality testing. Still includes debugging statements.
authored
9 Finally, the data structure needs to be persisted. This is currently implemented with standard Java serialization, but will likely use SBinary for a custom implementation for efficiency.
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
10
11 = API Specification =
12
13 This section specifies what the API of a source file is. Familiarity with the specification for Scala is assumed. For this specification, let 'classes' include classes, traits, objects, and package objects (2.8+ only).
14
15 Loosely, the API consists of the signatures in a source file. This includes packages and types of classes in a source. The type of a class includes its fully qualified name, type parameters, base classes, and member signatures.
16
833688c @harrah API equality testing. Still includes debugging statements.
authored
17 Equality of APIs is determined by straightforward structural equality except for type parameter definitions and references.
18 * The ID of a type parameter does not affect equality between two type parameters. The mapping between IDs of equal type parameters is recorded, however.
19 * When comparing two type parameter references, the comparison is deferred until initial equality checking (all other equality checking) is done. Then, the IDs are compared according to the mapping determined for type parameters in the initial check.
20
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
21 == Top Level Constructs ==
22 The top level contributions to the API in a source file are packages and top-level classes. Packages in Scala can be nested, but how they are nested is not important for the API of a source file. That only affects scope within that source file [VERIFY]. A top level class is a class that is not enclosed in another class or a method.
23
24 The public API of a source file is then:
25 * The set of fully qualified package names defined in the file. This includes packages without any classes in them or package objects defined for them.
26 * The API of the set of top level classes. The API of a class is defined in 'Class API' below.
27
28 == Definitions ==
29 A definition introduces a new named class or a class member. Class members include vars, vals, defs, and types. A definition has modifiers, including access restrictions. Other attributes of definitions are specific to the type of definition. The access modifiers are treated here separately and the effective modifiers are considered. For example, traits and abstract members are always considered to have the 'abstract' modifier. Synthetic refers to whether a definition was generated by the compiler.
30
31 The API of a definition is
32 * The definition's name, which is fully-qualified if it is a class.
a872ebc @harrah Annotations on definintions and implicit parameters in 2.7
authored
33 * The list of annotations on the definition
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
34 * The state of the following modifiers: abstract, override, final, sealed, implicit, lazy, synthetic
35 * The access restrictions of the definition, one of:
36 * public
37 * protected with qualifier
38 * private with qualifier
39 A qualifier part is either empty, 'this', or the fully qualified name of an enclosing package or class.
40 * The API specific to the definition, described below
41
42 === Field-like API ===
43 A field is a val or a var. Fields contribute setter and getter methods, but the API they contribute cannot be completely defined by these. The presence of a val or var affect the rules for overriding.
44
45 The field-specific API (contributed in addition to the parts common to all definitions) is then:
46 * Whether the field is a val or var.
47 * The type of the field.
48 * The API of associated setters and getters.
49
50 === Type Parameters ===
24e34a0 @waywardmonkeys Spelling fixes.
waywardmonkeys authored
51 Type parameters are not a definition, but they are used by methods, classes, and type members. The important aspects of a type parameter are its position in its defining parameter list and its upper and lower bounds, which are types. The actual name of a type parameter is not important, but it needs to be uniquely referenced within a source file.
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
52
53 The API contributed by a type parameter section is:
54 * The API of each type parameter in the type parameter section, in order. The number of type parameters is implicit here.
55 * The API of a type parameter is:
56 * A unique ID, which is not significant on its own, but is used to refer to this parameter in types. (the ID is relative, not absolute)
57 * The lower bound, a type.
58 * The upper bound, a type.
59
60 === Method API ===
61 A method is a def. A def consists of type parameters, value parameters and a return type. The value parameters come in sections (parameter lists) and the last section may be declared 'implicit'. A value parameter consists of a name (2.8+ only), a type, and whether a default is specified (2.8+ only). Additionally, a value parameter may be repeated or by-name.
62
63 The API specific to a method (contributed in addition to the parts common to all definitions) is:
64 * The API contributed by its type parameter section, described in the Type Parameters section previously.
65 * The return type.
66 * The API contributed by its value parameter lists, in order. The number of lists is implicit in this definition.
67 * The API of a value parameter list is:
68 * Whether the list is marked implicit.
69 * The API of its value parameters, in order. The number of value parameters is implicit here.
70 * The API of a value parameter is:
71 * The parameter name (2.8+ only)
72 * The parameter type. Types are described later
73 * The modifier for the parameter type. This can be either 'no modifier', 'by-name', or 'repeated'.
74 * Whether the parameter has default defined (2.8+ only)
75
76 === Type Member API ===
77 Type members consist of alias types and abstract types. Each can have type parameters.
78
79 The API specific to an alias type (contributed in addition to the parts common to all definitions) is:
80 * The API contributed by its type parameter section, described in the Type Parameters section previously.
81 * The type aliased.
82
83 The API specific to an abstract type (contributed in addition to the parts common to all definitions) is:
84 * The API contributed by its type parameter section, described in the Type Parameters section previously.
85 * The lower bound, a type.
86 * The upper bound, a type.
87
88 === Class API ===
89 A class has a self type, whether it is a trait, class, object, or package object, and a structure. Its structure includes its base classes and its members, both declared and inherited.
90
91 The API specific to a class (contributed in addition to the parts common to all definitions) is:
92 * The self type of the class.
93 * Whether the class is a trait, class, object, or package object.
94 * The structure, which is described by a structural type.
95
96 == Types ==
97
98 Types can be described as simple, annotated, structural, or existential. Within simple types are projections, singletons, type variable references, parameterized types. Types are well described in the Scala specification. They are described here because they are essential to defining the API of a source file.
99
100 The following sections briefly describe the contents of the different types.
101
102 === Projection ===
103 * A prefix, which is a simple type
104 * An ID, which is a String
105
106 === Type Variable Reference ===
107 * The unique ID of the referenced type variable
108
109 === Singleton ===
110 * The path underlying the singleton.
111
112 === Parameterized ===
113 * The type arguments, which is an ordered list of simple types.
114 * The base type, which is a simple type.
115
116 === Annotated ===
117 * A list of annotations
118 * The base type, which is a simple type
119
120 === Structural ===
833688c @harrah API equality testing. Still includes debugging statements.
authored
121 * The base class types, in linearization order.
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
122 * The declared members. These are definitions, described above.
123 * The inherited members. These are definitions, described above.
124
125 === Existential ===
126 * The base type
127 * The clause, which is a type parameter section, described previously
128
3332b07 @harrah Polymorphic types and fix parameterized type arguments to be Type and no...
authored
129 === Polymorphic ===
130 * The base type
131 * The type parameter section, described previously
132
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
133 = API Data Structure =
134
f414574 @harrah Update API definition documentation
authored
135 This section and explains the data structure representing the API of a source file described in the previous section.
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
136
f414574 @harrah Update API definition documentation
authored
137 As mentioned in the introduction, the data structure is defined by the 'definition' file in the 'interface' subproject. Code from the 'datatype' subproject processes this file and generates Java sources in 'src_managed' in the 'interface' subproject. The explanation includes listings from the definition file. These listings are current as of November 24, 2009.
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
138
f414574 @harrah Update API definition documentation
authored
139 The top-level datatype is `Source`. It represents the API in a single source file. Packages are listed separately from definitions for two reasons. First, packages cannot be inferred from definitions because a source file can introduce a package without a top-level definition in that package. A reasonable alternative would have been including Definitions in Packages. However, it is anticipated that the most common operation will be to iterate directly over definitions.
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
140 {{{
141 Source
142 packages : Package*
143 definitions: Definition*
144 }}}
145
146 A package is represented as a simple String. More structure is not required as explained in the API specification section.
147 {{{
148 Package
149 name: String
150 }}}
151
f414574 @harrah Update API definition documentation
authored
152 Definitions are represented by straightforward subclasses of a Definition class. vals and vars are FieldLike subclasses that differ only by their class name. The remaining definition variants all have type parameters and so they share a common parent that provides this information. Class definitions are represented by a single class and the variants (traits, objects, ...) are distinguished by the 'definitionType' field. The 'selfType' field can be an instance of the special Type EmptyType, which indicates that the self type is not different from the normal self type.
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
153 {{{
154 Definition
155 name: String
156 access: Access
157 modifiers: Modifiers
a872ebc @harrah Annotations on definintions and implicit parameters in 2.7
authored
158 annotations: Annotation*
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
159 FieldLike
160 tpe : Type
161 Val
162 Var
163 ParameterizedDefinition
164 typeParameters: TypeParameter*
165 Def
166 valueParameters: ParameterList*
167 returnType: Type
168 ClassLike
169 definitionType: DefinitionType
170 selfType: Type
171 structure: Structure
172 TypeMember
173 TypeAlias
174 tpe: Type
175 TypeDeclaration
176 lowerBound: Type
177 upperBound: Type
f414574 @harrah Update API definition documentation
authored
178 }}}
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
179
f414574 @harrah Update API definition documentation
authored
180 Types are fairly straightforward representations as well. They are intended to correspond closely to the types defined in the Scala specification. Note that function, infix, and tuple types translate to parameterized types and type designators translate to type projections. Compound types and refinements are represented by the Structure class.
181 {{{
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
182 Type
183 SimpleType
184 Projection
185 prefix : SimpleType
186 id : String
187 ParameterRef
188 id: Int
189 Singleton
190 path: Path
191 EmptyType
192 Parameterized
193 baseType : SimpleType
3332b07 @harrah Polymorphic types and fix parameterized type arguments to be Type and no...
authored
194 typeArguments: Type*
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
195 Annotated
196 baseType : SimpleType
197 annotations : Annotation*
198 Structure
199 parents : Type*
200 declarations: Definition*
201 inherited: Definition*
202 Existential
203 baseType : Type
204 clause: TypeParameter*
3332b07 @harrah Polymorphic types and fix parameterized type arguments to be Type and no...
authored
205 Polymorphic
206 baseType : Type
207 clause: TypeParameter*
f414574 @harrah Update API definition documentation
authored
208 }}}
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
209
f414574 @harrah Update API definition documentation
authored
210 There is one point to note about the access hierarchy. It includes a Pkg class, which represents Java's package private access. This is only used for Java sources.
211 {{{
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
212 Access
213 Public
214 Qualified
215 qualifier: Qualifier
216 Protected
217 Private
218 Pkg
219 Qualifier
220 Unqualified
221 ThisQualifier
222 IdQualifier
223 value: String
f414574 @harrah Update API definition documentation
authored
224 }}}
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
225
f414574 @harrah Update API definition documentation
authored
226 Modifiers are straightforward except that abstract is split into abstract and deferred, according to the Scala compiler's internal representation. Abstract applies to traits and abstract classes, while deferred applies to class members.
227 {{{
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
228 Modifiers
229 isAbstract: Boolean
230 isDeferred: Boolean
231 isOverride: Boolean
232 isFinal: Boolean
233 isSealed: Boolean
234 isImplicit: Boolean
235 isLazy: Boolean
236 isSynthetic: Boolean
067917a @retronym Macro def aware recompilation.
retronym authored
237 isMacro: Boolean
f414574 @harrah Update API definition documentation
authored
238 }}}
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
239
f414574 @harrah Update API definition documentation
authored
240 {{{
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
241 ParameterList
242 parameters: MethodParameter*
243 isImplicit: Boolean
244 MethodParameter
245 name: String
246 tpe: Type
247 hasDefault: Boolean
248 modifier: ParameterModifier
249
250 TypeParameter
251 id: Int
252 typeParameters : TypeParameter*
253 variance: Variance
254 lowerBound: Type
255 upperBound: Type
f414574 @harrah Update API definition documentation
authored
256 }}}
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
257
f414574 @harrah Update API definition documentation
authored
258 The representation of annotations does not express the full information that the compiler has about annotations. The arguments to an annotation are constant expressions. This could be represented in this data structure, but this is not currently done. Rather, the arguments are converted to a String in an unspecified manner.
259 {{{
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
260 Annotation
261 base: SimpleType
262 arguments: String*
f414574 @harrah Update API definition documentation
authored
263 }}}
bf7affd @harrah Starting documentation on API of sources files, updating notes a bit
authored
264
265 enum Variance : Contravariant, Covariant, Invariant
266 enum ParameterModifier : Repeated, Plain, ByName
267 enum DefinitionType : Trait, ClassDef, Module, PackageModule
268
269 Path
270 components: PathComponent*
271
272 PathComponent
273 Super
274 qualifier: Path
275 This
276 Id
277 id: String
278 }}}
279
280 = API Compiler Phase =
281
282 = Data Structure Generator =
283
833688c @harrah API equality testing. Still includes debugging statements.
authored
284 = API Data Structure Persistence =
285
286 The data structure is persisted by standard Java serialization on Source. This is done for simplicity and will be changed to use a more efficient encoding.
Something went wrong with that request. Please try again.