From 7edfd61a21d78933f5271a5931045291f8911933 Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Mon, 25 Mar 2019 10:11:06 -0700 Subject: [PATCH 1/9] Add section on uniquely identifier interface definitions Signed-off-by: Jacob Perron --- articles/143_legacy_interface_definition.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/articles/143_legacy_interface_definition.md b/articles/143_legacy_interface_definition.md index 70c67d9b7..f67b3e647 100644 --- a/articles/143_legacy_interface_definition.md +++ b/articles/143_legacy_interface_definition.md @@ -38,22 +38,30 @@ Each field is described by a *type* and a *name*. A single data structure is called *message*. Each message has a *name*. -Together with the name of the *package* a message can be uniquely identified. ### Services For request / reply style communication the two exchanged data structures are related. These pairs of data structures are called *services*. -A service is identified by its *name* and the *package* it is in. Each service describes two messages, one for the request data structure, one for the reply data structure. ### Actions For longer running request / reply style communication with feedback about the progress the exchanged data structures are related. These triplets of data structures are called *actions*. -An action is identified by its *name* and the *package* it is in. Each action describes three messages, one for the goal data structure, one for the result data structure, and one for the feedback data structure. +### Identifying data structures + +Every data structure can be uniquely identified with three pieces of information: + +1. **Package** - the name of the package containing the data structure definition. +2. **Subfolders** - the list of subfolders within the package where the data structure defintion can be found. +3. **Name** - the name of the data structure. + +For example, a message with the name `Foo` in subfolder `msg` of the package `bar` has the unique identifier `bar/msg/Foo`. +Here, `/` is used as a separator, but in practice any delimeter could be used. + ### Field types The type of a field can be either a primitive type or another data structure. From e686281a7a035c2cef535c6eb0302e3ac66c92c8 Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Tue, 26 Mar 2019 11:22:27 -0700 Subject: [PATCH 2/9] Replace the term 'subfolder' with 'subnamespace'. Signed-off-by: Jacob Perron --- articles/143_legacy_interface_definition.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/articles/143_legacy_interface_definition.md b/articles/143_legacy_interface_definition.md index f67b3e647..6eba92c13 100644 --- a/articles/143_legacy_interface_definition.md +++ b/articles/143_legacy_interface_definition.md @@ -56,10 +56,10 @@ Each action describes three messages, one for the goal data structure, one for t Every data structure can be uniquely identified with three pieces of information: 1. **Package** - the name of the package containing the data structure definition. -2. **Subfolders** - the list of subfolders within the package where the data structure defintion can be found. +2. **Subnamespaces** - the list of namespaces within the package where the data structure is defined. 3. **Name** - the name of the data structure. -For example, a message with the name `Foo` in subfolder `msg` of the package `bar` has the unique identifier `bar/msg/Foo`. +For example, a message with the name `Foo` in the namespace `msg` of the package `bar` has the unique identifier `bar/msg/Foo`. Here, `/` is used as a separator, but in practice any delimeter could be used. ### Field types From 4d50aeb23cc6eaaaa1bcf38c6a7b8c56774d440a Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Fri, 29 Mar 2019 11:22:03 -0700 Subject: [PATCH 3/9] Add section on interface identification to IDL design doc Signed-off-by: Jacob Perron --- articles/142_idl.md | 58 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 56 insertions(+), 2 deletions(-) diff --git a/articles/142_idl.md b/articles/142_idl.md index 98a6a5074..fae07da0f 100644 --- a/articles/142_idl.md +++ b/articles/142_idl.md @@ -40,7 +40,7 @@ Both line comments (`//`) as well as block comments (`/* ... */`) are being supp #### 7.2.3 Identifiers -An identifier must start with an is an ASCII alphabetic characteran followed by any number of ASCII alphabetic, digit and underscore (`_`) characters. +An identifier must start with an ASCII alphabetic character followed by any number of ASCII alphabetic, digit and underscore (`_`) characters. #### 7.2.6 Literals @@ -129,7 +129,7 @@ the DDS-XTypes specification 1.2 defines it with 16-bit. | ---------------------- | ---------------------------------------------------------- | | sequence\ | sequence of items of the specific type\_spec | | | the sequence is unbounded and no maximum size is specified | -| sequence | sequence of of up to N items of the specified type\_spec | +| sequence | sequence of up to N items of the specified type\_spec | | | the sequence is bounded and contain between 0 and N items | #### 7.4.1.4.4.3.2 Strings @@ -159,6 +159,60 @@ An enumerated type consist of an ordered list of enumerators. A multidimensional, fixed-size array is defined by the type of each item and the explicit sizes for each dimension. For now only a one-dimensional, fixed-size array is supported though. +### Interface Identification + +#### Uniform Resource Name (URN) + +Following 7.5.1 from the IDL 4.2 specification, every IDL definition can be uniquely identified with a qualified name of the form +**::**. +In addition to the specification, the scope of an IDL definition is prefixed with the package name from which the defintions is derived. +This is to guarantee uniqueness of definitions across packages (under the assumption that package names are unique). +Therefore, each interface defintion can be resolved with a URN of the form: **//**. + +#### Uniform Resource Locator (URL) + +For source code to use an interface (e.g. include or import) there needs to be a way to reference the file containing the defintion. +To reference the location of an IDL defintion we use a URL of the form: **rosidl://**. +Where ** is the relative path from the root of the package where generated defintions can be found. + +#### Example + +Imagine we have a package `foo_pkg` containing an IDL file `Bar.idl` with the following contents: + +```idl +struct MsgA { + boolean bool_member; +}; + +module bar { + const int8 MY_CONSTANT = 42; + + struct MsgB { + int8 int_member; + }; + + module baz { + struct MsgC { + string string_member; + }; + }; +}; +``` + +Also imagine the message generation pipeline places the generated implementation to a subfolder `interface`. + +Then, we can reference the interfaces with the following URNs: + +- `foo_pkg/MsgA` +- `foo_pkg/bar/MY_CONSTANT` +- `foo_pkg/bar/MsgB` +- `foo_pkg/bar/baz/MsgC` + +And all can be located with the URL: `rosidl:foo_pkg/interface/Bar`. + +For example, the definitions could be included in C++ with `#include ` +or imported in Python with `import foo_pkg.interface.Bar`. + ### Annotations The syntax for arbitrary annotations is supported. From 729c2d903d23338bf953938c8e6e03267ff9cc6f Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Fri, 29 Mar 2019 11:52:07 -0700 Subject: [PATCH 4/9] Update legacy interface article Reference the IDL section on identifying interfaces and be explicit about the namespaces for messages, services, and actions. Signed-off-by: Jacob Perron --- articles/143_legacy_interface_definition.md | 35 +++++++++++++++++---- 1 file changed, 29 insertions(+), 6 deletions(-) diff --git a/articles/143_legacy_interface_definition.md b/articles/143_legacy_interface_definition.md index 6eba92c13..8341f7288 100644 --- a/articles/143_legacy_interface_definition.md +++ b/articles/143_legacy_interface_definition.md @@ -38,12 +38,15 @@ Each field is described by a *type* and a *name*. A single data structure is called *message*. Each message has a *name*. +Together with the name of the *package* a message can be uniquely identified. +A message has the URN: package/msg/name`. ### Services For request / reply style communication the two exchanged data structures are related. These pairs of data structures are called *services*. Each service describes two messages, one for the request data structure, one for the reply data structure. +Together with the name of the *package* a ### Actions @@ -53,14 +56,34 @@ Each action describes three messages, one for the goal data structure, one for t ### Identifying data structures -Every data structure can be uniquely identified with three pieces of information: +Every data structure can be uniquely referenced with a *uniform resource name* (URN) and a *uniform resource locator* (URL) +as described by [IDL - Interface Identification](idl_interface_definition.html#interface-identification) -1. **Package** - the name of the package containing the data structure definition. -2. **Subnamespaces** - the list of namespaces within the package where the data structure is defined. -3. **Name** - the name of the data structure. +#### Messages -For example, a message with the name `Foo` in the namespace `msg` of the package `bar` has the unique identifier `bar/msg/Foo`. -Here, `/` is used as a separator, but in practice any delimeter could be used. +- URN: `/msg/` +- URL: `/msg/` + +#### Services + +- URN: `/srv/` +- URL: `/srv/` + +The underlying message definitions that make up a service are located in the same file (ie. have the same URL) and are in the `srv` namespace: + +- URN: `/srv/\_Request` +- URN: `/srv/\_Response` + +#### Actions + +- URN: `/action/` +- URL: `/action/` + +The underlying message definitions that make up an action are located in the same file (ie. have the same URL) and are in the `action` namespace: + +- URN: `/action/\_Goal` +- URN: `/action/\_Result` +- URN: `/action/\_Feedback` ### Field types From 3ea4e56e521509df0fb6ceff1c3bf060566e457f Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Fri, 29 Mar 2019 12:01:57 -0700 Subject: [PATCH 5/9] Fix typos Signed-off-by: Jacob Perron --- articles/142_idl.md | 6 +++--- articles/143_legacy_interface_definition.md | 10 +++++----- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/articles/142_idl.md b/articles/142_idl.md index fae07da0f..0a19a78a0 100644 --- a/articles/142_idl.md +++ b/articles/142_idl.md @@ -164,10 +164,10 @@ For now only a one-dimensional, fixed-size array is supported though. #### Uniform Resource Name (URN) Following 7.5.1 from the IDL 4.2 specification, every IDL definition can be uniquely identified with a qualified name of the form -**::**. -In addition to the specification, the scope of an IDL definition is prefixed with the package name from which the defintions is derived. +**\::\**. +In addition to the specification, the scope of an IDL definition is prefixed with the package name from which the defintion is derived. This is to guarantee uniqueness of definitions across packages (under the assumption that package names are unique). -Therefore, each interface defintion can be resolved with a URN of the form: **//**. +Therefore, each interface defintion can be resolved with a URN of the form: **\/\/\**. #### Uniform Resource Locator (URL) diff --git a/articles/143_legacy_interface_definition.md b/articles/143_legacy_interface_definition.md index 8341f7288..3f11d9346 100644 --- a/articles/143_legacy_interface_definition.md +++ b/articles/143_legacy_interface_definition.md @@ -71,8 +71,8 @@ as described by [IDL - Interface Identification](idl_interface_definition.html#i The underlying message definitions that make up a service are located in the same file (ie. have the same URL) and are in the `srv` namespace: -- URN: `/srv/\_Request` -- URN: `/srv/\_Response` +- URN: `/srv/_Request` +- URN: `/srv/_Response` #### Actions @@ -81,9 +81,9 @@ The underlying message definitions that make up a service are located in the sam The underlying message definitions that make up an action are located in the same file (ie. have the same URL) and are in the `action` namespace: -- URN: `/action/\_Goal` -- URN: `/action/\_Result` -- URN: `/action/\_Feedback` +- URN: `/action/_Goal` +- URN: `/action/_Result` +- URN: `/action/_Feedback` ### Field types From 30a99ff0ecf204cae44ba4730d84e7ae9ebea865 Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Fri, 29 Mar 2019 14:38:19 -0700 Subject: [PATCH 6/9] Remove unnecessary sentences Signed-off-by: Jacob Perron --- articles/143_legacy_interface_definition.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/articles/143_legacy_interface_definition.md b/articles/143_legacy_interface_definition.md index 3f11d9346..0b260df90 100644 --- a/articles/143_legacy_interface_definition.md +++ b/articles/143_legacy_interface_definition.md @@ -38,15 +38,12 @@ Each field is described by a *type* and a *name*. A single data structure is called *message*. Each message has a *name*. -Together with the name of the *package* a message can be uniquely identified. -A message has the URN: package/msg/name`. ### Services For request / reply style communication the two exchanged data structures are related. These pairs of data structures are called *services*. Each service describes two messages, one for the request data structure, one for the reply data structure. -Together with the name of the *package* a ### Actions From b9a28263adeaabc1b0f21ecafb4ab2405b8868cf Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Fri, 29 Mar 2019 14:41:18 -0700 Subject: [PATCH 7/9] And service Signed-off-by: Jacob Perron --- articles/143_legacy_interface_definition.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/143_legacy_interface_definition.md b/articles/143_legacy_interface_definition.md index 0b260df90..ebc9c2bde 100644 --- a/articles/143_legacy_interface_definition.md +++ b/articles/143_legacy_interface_definition.md @@ -76,7 +76,7 @@ The underlying message definitions that make up a service are located in the sam - URN: `/action/` - URL: `/action/` -The underlying message definitions that make up an action are located in the same file (ie. have the same URL) and are in the `action` namespace: +The underlying message and service definitions that make up an action are located in the same file (ie. have the same URL) and are in the `action` namespace: - URN: `/action/_Goal` - URN: `/action/_Result` From 53ff8b213cccc61c090463ea30ee9506c2c4e2fe Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Mon, 8 Apr 2019 14:36:36 -0700 Subject: [PATCH 8/9] Update URI syntax * Use URI, instead of URN, for interface definitions * Add forward slashes to URL and rename 'rosidl' -> 'package' Signed-off-by: Jacob Perron --- articles/142_idl.md | 17 ++++++++------- articles/143_legacy_interface_definition.md | 24 ++++++++++----------- 2 files changed, 21 insertions(+), 20 deletions(-) diff --git a/articles/142_idl.md b/articles/142_idl.md index 0a19a78a0..c41f3fe57 100644 --- a/articles/142_idl.md +++ b/articles/142_idl.md @@ -161,18 +161,19 @@ For now only a one-dimensional, fixed-size array is supported though. ### Interface Identification -#### Uniform Resource Name (URN) +#### Uniform Resource Identifier (URI) Following 7.5.1 from the IDL 4.2 specification, every IDL definition can be uniquely identified with a qualified name of the form **\::\**. In addition to the specification, the scope of an IDL definition is prefixed with the package name from which the defintion is derived. This is to guarantee uniqueness of definitions across packages (under the assumption that package names are unique). -Therefore, each interface defintion can be resolved with a URN of the form: **\/\/\**. +Therefore, each interface defintion can be resolved with a URI of the form: **rosidl:\/\/\**. +Where *\* is one or more names separated by forward slashes ("/"). #### Uniform Resource Locator (URL) For source code to use an interface (e.g. include or import) there needs to be a way to reference the file containing the defintion. -To reference the location of an IDL defintion we use a URL of the form: **rosidl://**. +To reference the location of an IDL defintion we use a URL of the form: **package:////**. Where ** is the relative path from the root of the package where generated defintions can be found. #### Example @@ -203,12 +204,12 @@ Also imagine the message generation pipeline places the generated implementation Then, we can reference the interfaces with the following URNs: -- `foo_pkg/MsgA` -- `foo_pkg/bar/MY_CONSTANT` -- `foo_pkg/bar/MsgB` -- `foo_pkg/bar/baz/MsgC` +- `rosidl:foo_pkg/MsgA` +- `rosidl:foo_pkg/bar/MY_CONSTANT` +- `rosidl:foo_pkg/bar/MsgB` +- `rosidl:foo_pkg/bar/baz/MsgC` -And all can be located with the URL: `rosidl:foo_pkg/interface/Bar`. +And all can be located with the URL: `package://foo_pkg/interface/Bar`. For example, the definitions could be included in C++ with `#include ` or imported in Python with `import foo_pkg.interface.Bar`. diff --git a/articles/143_legacy_interface_definition.md b/articles/143_legacy_interface_definition.md index ebc9c2bde..a66163792 100644 --- a/articles/143_legacy_interface_definition.md +++ b/articles/143_legacy_interface_definition.md @@ -53,34 +53,34 @@ Each action describes three messages, one for the goal data structure, one for t ### Identifying data structures -Every data structure can be uniquely referenced with a *uniform resource name* (URN) and a *uniform resource locator* (URL) +Every data structure can be uniquely referenced with a *uniform resource identifier* (URI) and a *uniform resource locator* (URL) as described by [IDL - Interface Identification](idl_interface_definition.html#interface-identification) #### Messages -- URN: `/msg/` -- URL: `/msg/` +- URI: `rosidl:/msg/` +- URL: `package:///msg/` #### Services -- URN: `/srv/` -- URL: `/srv/` +- URI: `rosidl:/srv/` +- URL: `package:///srv/` The underlying message definitions that make up a service are located in the same file (ie. have the same URL) and are in the `srv` namespace: -- URN: `/srv/_Request` -- URN: `/srv/_Response` +- URI: `rosidl:/srv/_Request` +- URI: `package:///srv/_Response` #### Actions -- URN: `/action/` -- URL: `/action/` +- URI: `rosidl:/action/` +- URL: `package:///action/` The underlying message and service definitions that make up an action are located in the same file (ie. have the same URL) and are in the `action` namespace: -- URN: `/action/_Goal` -- URN: `/action/_Result` -- URN: `/action/_Feedback` +- URI: `rosidl:/action/_Goal` +- URI: `rosidl:/action/_Result` +- URI: `rosidl:/action/_Feedback` ### Field types From 4d454c3acb3fe114bb1eaa84e0afca1cfeb4732c Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Wed, 1 May 2019 16:48:04 -0700 Subject: [PATCH 9/9] Fix typos Signed-off-by: Jacob Perron --- articles/142_idl.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/articles/142_idl.md b/articles/142_idl.md index c41f3fe57..d9fe18cdf 100644 --- a/articles/142_idl.md +++ b/articles/142_idl.md @@ -202,17 +202,17 @@ module bar { Also imagine the message generation pipeline places the generated implementation to a subfolder `interface`. -Then, we can reference the interfaces with the following URNs: +Then, we can reference the interfaces with the following URIs: - `rosidl:foo_pkg/MsgA` - `rosidl:foo_pkg/bar/MY_CONSTANT` - `rosidl:foo_pkg/bar/MsgB` - `rosidl:foo_pkg/bar/baz/MsgC` -And all can be located with the URL: `package://foo_pkg/interface/Bar`. +And all can be located with the URL: `package://foo_pkg/interface/bar`. -For example, the definitions could be included in C++ with `#include ` -or imported in Python with `import foo_pkg.interface.Bar`. +For example, the definitions could be included in C++ with `#include ` +or imported in Python with `import foo_pkg.interface.bar`. ### Annotations