spec: allow import to merge service definitions (#504)

* spec: allow import to merge service definitions * rename to import_service, and disallow service constructor * rename to import service * Update spec/Candid.md Co-authored-by: Claudio Russo <[email protected]> --------- Co-authored-by: Claudio Russo <[email protected]>
dfinity · Dec 15, 2023 · 491969f · 491969f
1 parent eca7f4c
commit 491969f
Showing 1 changed file with 12 additions and 6 deletions.
diff --git a/spec/Candid.md b/spec/Candid.md
@@ -1,8 +1,8 @@
 # Candid Specification
 
-Version: 0.1.6
+Version: 0.1.7
 
-Date: August 29, 2023
+Date: Dec 12, 2024
 
 ## Motivation
 
@@ -64,7 +64,7 @@ The purpose of an IDL is defining the signature, and thereby the *type* of an ac
 This is a summary of the grammar proposed:
 ```
 <prog>  ::= <def>;* <actor>?
-<def>   ::= type <id> = <datatype> | import <text>
+<def>   ::= type <id> = <datatype> | import service? <text>
 <actor> ::= service <id>? : (<tuptype> ->)? (<actortype> | <id>) ;?
 
 <actortype> ::= { <methtype>;* }
@@ -519,20 +519,26 @@ type B = A;  // error: cyclic type definition
 In order to allow splitting interface definitions up into multiple files or share common definitions between multiple interfaces, *import* declarations are provided.
 
 ```
-<def>   ::= ... | import <text>
+<def>   ::= ... | import service? <text>
 ```
 
-An import refers to another interface file by URL. The semantics is that of textual inclusion, except that definitions from the imported file must not refer to definitions from the importing file.
+An import refers to another interface file by URL. The type definitions from the imported file are textually included in the importing file. The definitions from the imported file must not refer to definitions from the importing file.
+
+`import` ignores the main service definition from the imported file, while `import service` includes the main service from the imported file and merges the service definition with the main service in the importing file. There are two constraints with the main service definition in the imported file:
+
+* The main service cannot be a service constructor.
+* The methods from the imported file must not have the same method name as the importing file.
 
 ##### Example
 
 File `A.did`:
 ```
 type A = service { f : () -> () };
+service : A
 ```
 File `B.did`:
 ```
-import "A.did"
+import "A.did";  // Cannot use `import service` because of method name duplication
 service B : A ;
 ```