idl-parser 0.2.0__tar.gz → 0.2.1__tar.gz

{idl_parser-0.2.0/idl_parser.egg-info → idl_parser-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: idl_parser
-Version: 0.2.0
+Version: 0.2.1
 Summary: Very simple OMG IDL (Interface Definition Language) parser. This parses IDL files and outputs intermediate class objects.
 Author-email: ysuga <ysuga@ysuga.net>
 Project-URL: Homepage, http://www.sugarsweetrobotics.com/
@@ -95,6 +95,14 @@ Example
     print('  name:', m.name)
     print('  type:', m.type.name)
 
+More examples are in the ``examples`` folder of the repository:
+
+- ``example.py``: interfaces, typedefs, unions and structs
+- ``union_example.py``: unions (discriminator kinds, case labels, member types)
+- ``annotation_example.py``: IDL 4 annotations (``@key``, ``@range``, ...) and struct keys
+
+https://github.com/sugarsweetrobotics/idl_parser/tree/main/examples
+
 How to install
 ---------------
 

{idl_parser-0.2.0 → idl_parser-0.2.1}/README.md

@@ -70,6 +70,16 @@ for m in timedDoubleSeq.members:
   print('  name:', m.name)
   print('  type:', m.type.name)
 ```
+More examples are in the [examples](examples/) folder:
+
+| File | Shows |
+|---|---|
+| [`example.py`](examples/example.py) | interfaces, typedefs, unions and structs |
+| [`union_example.py`](examples/union_example.py) | unions: discriminator kinds, case labels, member types |
+| [`annotation_example.py`](examples/annotation_example.py) | IDL 4 annotations (`@key`, `@range`, ...) and struct keys |
+
+Run them with e.g. `python examples/union_example.py` (in a source checkout no install is needed).
+
 ## How to install
     sudo pip install idl_parser
 

{idl_parser-0.2.0 → idl_parser-0.2.1}/README.rst

@@ -74,6 +74,14 @@ Example
     print('  name:', m.name)
     print('  type:', m.type.name)
 
+More examples are in the ``examples`` folder of the repository:
+
+- ``example.py``: interfaces, typedefs, unions and structs
+- ``union_example.py``: unions (discriminator kinds, case labels, member types)
+- ``annotation_example.py``: IDL 4 annotations (``@key``, ``@range``, ...) and struct keys
+
+https://github.com/sugarsweetrobotics/idl_parser/tree/main/examples
+
 How to install
 ---------------
 

idl_parser-0.2.1/examples/_path.py

@@ -0,0 +1,14 @@
+"""Make the examples use the idl_parser of this source checkout.
+
+``python examples/xxx.py`` puts ``examples/`` (not the repository root) on
+``sys.path``, so ``import idl_parser`` would fail without installing the
+package, or would pick up an older installed version. When the examples sit
+in a checkout next to the ``idl_parser`` package, that package is used.
+Copied elsewhere, the examples use the installed ``idl_parser``.
+"""
+import os
+import sys
+
+_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if os.path.isdir(os.path.join(_root, 'idl_parser')) and _root not in sys.path:
+    sys.path.insert(0, _root)

idl_parser-0.2.1/examples/annotation_example.py

@@ -0,0 +1,160 @@
+"""Example: read IDL 4 annotations (``@key``, ``@range(min=0, max=10)``, ...).
+
+Annotations are kept on whatever they are written before: a module, struct,
+union, enum, typedef, const, interface, struct/union member, enum value,
+method or method argument. They never leak into type names.
+
+Shows how to
+- list annotations and look one up by name (``annotations``,
+  ``annotation_by_name``, ``has_annotation``),
+- read annotation arguments (``args``, ``params``, ``value``),
+- get struct keys from ``@key`` (combined with ``#pragma keylist``),
+- read annotations that change parsing (``@bit_bound``, ``@position``),
+- get annotations in ``to_dic()`` output,
+- use your own annotations (``@annotation`` definitions are skipped).
+
+Run::
+
+    python examples/annotation_example.py
+"""
+import json
+
+import _path  # noqa: F401  (use the idl_parser of this checkout)
+
+from idl_parser import parser
+
+IDL = '''
+// A user-defined annotation. The definition itself is skipped by the parser,
+// but uses of it (@unit_system(...)) are kept like any other annotation.
+@annotation unit_system { string name default "SI"; };
+
+@unit_system(name="SI")
+module robot {
+
+  @extensibility(APPENDABLE) @topic
+  struct JointState {
+    @key long joint_id;
+    @key string robot_name;
+    @range(min=-180, max=180) @unit("deg") double position;
+    @unit("deg/s") @default(0) double velocity;
+    @optional double effort;
+    long sequence_number;
+  };
+
+  struct Command {
+    long target_id;
+    long priority;
+    @key long command_id;
+  };
+
+  enum Mode {
+    @value(10) IDLE,
+    @value(20) RUNNING,
+    @value(99) @deprecated ERROR
+  };
+
+  @extensibility(FINAL)
+  union Setpoint switch (Mode) {
+    case IDLE:
+      @unit("deg") double hold_position;
+    case RUNNING:
+      @unit("deg/s") double target_velocity;
+  };
+
+  @bit_bound(8)
+  bitmask Status {
+    @position(0) POWERED,
+    MOVING,
+    @position(7) FAULT
+  };
+
+  @range(min=0, max=100) typedef long Percent;
+
+  @verbatim(language="c++", text="constexpr") const long MAX_JOINTS = 7;
+
+  @service(platform="DDS")
+  interface Controller {
+    @oneway_hint void setMode(in Mode mode);
+    long move(@range(min=0, max=6) in long joint_id, in double position);
+  };
+};
+
+#pragma keylist robot::Command target_id
+'''
+
+
+def show(label, node):
+    anns = ' '.join(str(a) for a in node.annotations) or '(none)'
+    print('%-28s %s' % (label, anns))
+
+
+def main():
+    global_module = parser.IDLParser().load(IDL)
+    robot = global_module.module_by_name('robot')
+
+    print('== Annotations on each kind of definition')
+    show('module robot', robot)
+    joint_state = robot.struct_by_name('JointState')
+    show('struct JointState', joint_state)
+    for m in joint_state.members:
+        # Annotations never become part of the type name.
+        show('  %s %s' % (m.type, m.name), m)
+    mode = robot.enum_by_name('Mode')
+    for v in mode.values:
+        show('enum value %s' % v.name, v)
+    setpoint = robot.union_by_name('Setpoint')
+    show('union Setpoint', setpoint)
+    for m in setpoint.members:
+        show('  case %s: %s' % (','.join(m.descriminator_value_associations), m.name), m)
+    show('typedef Percent', robot.typedef_by_name('Percent'))
+    show('const MAX_JOINTS', robot.const_by_name('MAX_JOINTS'))
+    controller = robot.interface_by_name('Controller')
+    show('interface Controller', controller)
+    for method in controller.methods:
+        show('  method %s' % method.name, method)
+        for a in method.arguments:
+            show('    arg %s' % a.name, a)
+    print()
+
+    print('== Reading annotation arguments')
+    position = joint_state.member_by_name('position')
+    rng = position.annotation_by_name('range')
+    print('str:    ', str(rng))                      # @range(min=-180, max=180)
+    print('name:   ', rng.name)                      # range
+    print('params: ', rng.params)                    # {'min': '-180', 'max': '180'}
+    print('min/max:', int(rng.params['min']), int(rng.params['max']))
+    unit = position.annotation_by_name('unit')
+    print('unit:   ', unit.args, unit.value)         # ['"deg"'] "deg" (quotes are kept)
+    print('unit without quotes:', unit.value.strip('"'))
+    print('IDLE value:', int(mode.value_by_name('IDLE').annotation_by_name('value').value))
+    print('ERROR deprecated?', mode.value_by_name('ERROR').has_annotation('deprecated'))
+    print('effort optional?', joint_state.member_by_name('effort').has_annotation('optional'))
+    print('sequence_number annotation:', joint_state.member_by_name('sequence_number').annotation_by_name('range'))
+    print('module unit system:', robot.annotation_by_name('unit_system').params['name'])
+    print()
+
+    print('== Keys from @key and #pragma keylist')
+    print('JointState keys:', joint_state.keys)
+    print('JointState key members:', [m.name for m in joint_state.members if m.is_key])
+    command = robot.struct_by_name('Command')
+    # Keys from #pragma keylist come first, then members marked @key.
+    print('Command keys:', command.keys,
+          '(pragma: %s, @key: %s)' % (command.pragma_keys, command.annotated_keys))
+    print()
+
+    print('== Annotations that change parsing')
+    status = robot.bitmask_by_name('Status')
+    print('Status bit_bound:', status.bit_bound)
+    print('Status positions:', [(v.name, v.position) for v in status.values])
+    print()
+
+    print('== to_dic() includes annotations')
+    dic = robot.struct_by_name('JointState').to_dic()
+    print(json.dumps({'annotations': dic['annotations'],
+                      'members': [{k: m[k] for k in ('name', 'type', 'annotations') if k in m}
+                                  for m in dic['members'][:3]]},
+                     indent=2))
+
+
+if __name__ == '__main__':
+    main()

{idl_parser-0.2.0 → idl_parser-0.2.1/examples}/example.py

@@ -1,7 +1,17 @@
-"""Example: parse an IDL string and print interfaces, typedefs, unions and structs."""
+"""Example: parse an IDL string and print interfaces, typedefs, unions and structs.
 
-def test():
-    from idl_parser import parser
+Run (no install needed in a checkout)::
+
+    python examples/example.py
+
+See also ``union_example.py`` and ``annotation_example.py`` in this folder.
+"""
+import _path  # noqa: F401  (use the idl_parser of this checkout)
+
+from idl_parser import parser
+
+
+def main():
     _parser = parser.IDLParser()
     idl_str = '''
 module my_module {
@@ -88,4 +98,4 @@ module my_module {
 
 
 if __name__ == '__main__':
-    test()
+    main()

idl_parser-0.2.1/examples/union_example.py

@@ -0,0 +1,143 @@
+"""Example: read IDL unions (discriminated unions).
+
+Shows how to get
+- the discriminator type of a union (enum, integer, boolean),
+- which case labels select each member (including several labels for one member),
+- each member's type: primitive, struct, typedef of a sequence, or array,
+- a union used as a struct member,
+- the union as a plain dict (``to_dic``).
+
+Run::
+
+    python examples/union_example.py
+"""
+import json
+
+import _path  # noqa: F401  (use the idl_parser of this checkout)
+
+from idl_parser import parser
+
+IDL = '''
+module shapes {
+  enum ShapeKind { CIRCLE, RECTANGLE, POLYGON, POINT };
+
+  struct Point2D {
+    double x;
+    double y;
+  };
+
+  typedef sequence<Point2D> PointSeq;
+
+  struct Rectangle {
+    Point2D top_left;
+    double width;
+    double height;
+  };
+
+  // Discriminator is an enum. One member can be selected by several labels.
+  union Shape switch (ShapeKind) {
+    case CIRCLE:
+      double radius;
+    case RECTANGLE:
+      Rectangle rect;
+    case POLYGON:
+      PointSeq vertices;
+    case POINT:
+      Point2D point;
+  };
+
+  // Discriminator is an integer type; labels are numbers (negative is fine).
+  union Value switch (long) {
+    case -1:
+    case 0:
+      string error_message;
+    case 1:
+      long long integer_value;
+    case 2:
+      double matrix[3][3];
+  };
+
+  // Discriminator is boolean.
+  union OptionalDouble switch (boolean) {
+    case TRUE:
+      double value;
+  };
+
+  // A union can be a member of a struct.
+  struct ShapeMessage {
+    ShapeKind kind;
+    Shape shape;
+  };
+};
+'''
+
+
+def describe_type(t):
+    """Return a short human readable description of a member type."""
+    if t.is_primitive:
+        return 'primitive %s' % t.name
+    if t.is_array:
+        return 'array %s' % t.name
+    if t.is_typedef:
+        # Follow the typedef to see what it stands for.
+        inner = t.type
+        if inner.is_sequence:
+            return 'typedef %s = sequence of %s' % (t.full_path, inner.inner_type.name)
+        return 'typedef %s = %s' % (t.full_path, inner.name)
+    if t.is_struct:
+        return 'struct %s (members: %s)' % (t.full_path, ', '.join(m.name for m in t.members))
+    if t.is_union:
+        return 'union %s' % t.full_path
+    if t.is_enum:
+        return 'enum %s' % t.full_path
+    return t.name
+
+
+def print_union(union):
+    print('union %s switch (%s)' % (union.full_path, union.descriminator_kind))
+    for member in union.members:
+        labels = ', '.join(member.descriminator_value_associations)
+        print('  case %s -> %s: %s' % (labels, member.name, describe_type(member.type)))
+
+
+def main():
+    global_module = parser.IDLParser().load(IDL)
+    shapes = global_module.module_by_name('shapes')
+
+    # All unions in a module
+    print('unions in module shapes:', [u.name for u in shapes.unions])
+    print()
+
+    for union in shapes.unions:
+        print_union(union)
+        print()
+
+    # Look up a member by name, and find the member for a discriminator value.
+    shape = shapes.union_by_name('Shape')
+    rect = shape.member_by_name('rect')
+    print('Shape.rect full path:', rect.full_path)
+    print('Shape.rect.top_left type:', rect.type.member_by_name('top_left').type.full_path)
+
+    value = shapes.union_by_name('Value')
+    for label in ('-1', '0', '1', '2'):
+        selected = [m.name for m in value.members if label in m.descriminator_value_associations]
+        print('Value with discriminator %s holds: %s' % (label, selected[0]))
+    print()
+
+    # The discriminator kind is a name; resolve it to its enum to list the labels.
+    kind = shapes.enum_by_name(shape.descriminator_kind)
+    print('%s values: %s' % (kind.name, [v.name for v in kind.values]))
+    print()
+
+    # A union used inside a struct
+    message = shapes.struct_by_name('ShapeMessage')
+    for m in message.members:
+        print('ShapeMessage.%s: %s' % (m.name, describe_type(m.type)))
+    print()
+
+    # The whole union as a dict (handy for JSON or code generators)
+    print(json.dumps(shapes.union_by_name('OptionalDouble').to_dic(), indent=2))
+
+
+if __name__ == '__main__':
+    main()

{idl_parser-0.2.0 → idl_parser-0.2.1}/idl_parser/module.py

@@ -195,16 +195,26 @@ class IDLModule(node.IDLNode):
                 values = []
                 while True:
                     ln, fn, t = token_buf.pop()
+                    if t is None:
+                        if self._verbose: sys.stdout.write('# Error. No ";" after const.\n')
+                        raise InvalidIDLSyntaxError(message='No ";" after const definition')
                     if t == ';':
                         break
                     values.append(t)
 
-                value_ = values[-1]
-                name_ = values[-3]
-                typename = ''
-                for t in values[:-3]:
-                    typename = typename + ' ' + t
-                typename = typename.strip()
+                # Split at '=': "<type> <name> = <value>" (issue #52).
+                # The value is every token after '=', so that an
+                # expression such as "1 + 2" is kept whole.
+                if '=' not in values:
+                    raise InvalidIDLSyntaxError(ln, fn, 'No "=" in const definition "%s"' % ' '.join(values))
+                eq = values.index('=')
+                if eq < 2:
+                    raise InvalidIDLSyntaxError(ln, fn, 'No type or name in const definition "%s"' % ' '.join(values))
+                if eq == len(values) - 1:
+                    raise InvalidIDLSyntaxError(ln, fn, 'No value in const definition "%s"' % ' '.join(values))
+                value_ = ' '.join(values[eq+1:])
+                name_ = values[eq-1]
+                typename = ' '.join(values[:eq-1])
                 s = const.IDLConst(name_, typename, value_, self, filepath=filepath)
                 s._add_annotations(pending_annotations)
                 s_ = self.const_by_name(name_)

{idl_parser-0.2.0 → idl_parser-0.2.1}/idl_parser/parser.py

@@ -1,7 +1,25 @@
 import os, sys
 import re
+import functools
+import warnings
+
+try:
+    from warnings import deprecated as _deprecated
+except ImportError:  # Python < 3.13 (PEP 702)
+    def _deprecated(message, *, category=DeprecationWarning, stacklevel=1):
+        """Small stand-in for :func:`warnings.deprecated` (Python 3.13+):
+        warn with ``category`` each time the function is called."""
+        def decorator(func):
+            @functools.wraps(func)
+            def wrapper(*args, **kwargs):
+                warnings.warn(message, category=category, stacklevel=stacklevel + 1)
+                return func(*args, **kwargs)
+            wrapper.__deprecated__ = message
+            return wrapper
+        return decorator
 
 from . import  module, token_buffer, pragma as idl_pragma
+from .token_buffer import _literal_end
 from . import type as idl_type
 from . import exception 
 
@@ -24,6 +42,21 @@ class ConsoleTracker():
 
 logger = ConsoleTracker()
 
+
+def _format_code(code):
+    """Put spaces around punctuation in code outside of literals and
+    comments, and squash runs of whitespace into one space."""
+    code = code.replace('{', ' { ')
+    # A single ':' (case label, inheritance), but not '::' (scoped name).
+    code = re.sub(r'(?<!:):(?!:)', ' : ', code)
+    code = code.replace(';', ' ;')
+    code = code.replace('(', ' ( ')
+    code = code.replace(',', ' , ')
+    code = code.replace('=', ' = ')
+    code = code.replace(')', ' ) ')
+    code = code.replace('}', ' } ')
+    return re.sub(r'\s+', ' ', code)
+
 class IDLParser():
 
     def __init__(self, idl_dirs=[], verbose=False):
@@ -58,7 +91,20 @@ class IDLParser():
     def dirs(self):
         return self._dirs
 
+    @_deprecated('IDLParser.prepare_input() is no longer used by load() and '
+                'does not look at string literals (issue #53). '
+                'load() and parse() now handle spaces inside "[ ]" and "< >" by themselves.')
     def prepare_input(self, data):
+        """Remove whitespace just inside ``[ ]`` and ``< >`` in ``data``.
+
+        No longer used by :meth:`load`: the same joining is now done on
+        tokens outside literals and comments, for :meth:`load` and
+        :meth:`parse` alike (see :func:`idl_parser.token_buffer.join_brackets`,
+        issue #53). Kept for compatibility; it does not look at literals.
+
+        .. deprecated:: 0.2.1
+           Calling it emits a :class:`DeprecationWarning`.
+        """
         from re import compile, UNICODE, MULTILINE
         flags = UNICODE | MULTILINE
 
@@ -80,7 +126,6 @@ class IDLParser():
 
     def load(self, input_str, include_dirs=[], filepath=None):
         self._dirs = self._dirs + include_dirs
-        input_str = self.prepare_input(input_str)
         lines = [(i+1, filepath, l) for i, l in enumerate(input_str.split('\n'))]
         self.parse_lines(lines, filepath=filepath)
         return self._global_module
@@ -308,46 +353,51 @@ class IDLParser():
 
 
     def _clear_comments(self, lines):
+        """Remove comments and put spaces around punctuation so that each
+        token is separated by whitespace.
+
+        Lines are scanned one character at a time. String literals
+        (``"..."``) and character literals (``'...'``) are copied as they
+        are: ``//`` or ``/*`` inside them is not a comment (issue #50), and
+        no spaces are put into them. A ``:`` right after a literal, as in
+        ``case 'a':``, is separated like any other ``:`` (issue #49).
+        """
         output_lines = []
         in_comment = False
 
         for line_number, file_name, line in lines:
-            line = line.strip()
-            output_line = ''
-            if line.find('//') >= 0:
-                line = line[:line.find('//')]
-
-            for token in line.split():
-
-                if in_comment and token.find('*/') >= 0:
+            parts = []  # code (formatted) and literals (as they are), in order
+            code = ''
+            i = 0
+            n = len(line)
+            while i < n:
+                if in_comment:
+                    end = line.find('*/', i)
+                    if end < 0:
+                        break  # the comment continues on the next line
                     in_comment = False
-                    output_line = output_line + ' ' + token[token.find('*/')+2:].strip()
-
-                elif in_comment:
-                    continue
-
-                elif token.startswith('//'):
-                    break # ignore this line
-
-                elif token.find('/*') >= 0:
+                    i = end + 2
+                    code = code + ' '
+                elif line.startswith('//', i):
+                    break  # ignore the rest of this line
+                elif line.startswith('/*', i):
                     in_comment = True
-                    output_line = output_line + ' ' + token[0: token.find('/*')]
+                    i = i + 2
+                    code = code + ' '
+                elif line[i] in '"\'':
+                    end = _literal_end(line, i)
+                    parts.append(_format_code(code))
+                    parts.append(line[i:end].rstrip('\r\n'))
+                    code = ''
+                    i = end
                 else:
-                    if token.find('{') >= 0:
-                        token = token.replace('{', ' { ')
-                    if token.find(':') >= 0:
-                        token = re.sub(r'([a-zA-Z0-9_]{1}):([a-zA-Z0-9_]{1}|$)', r'\1 : \2', token)
-                    if token.find(';') >= 0:
-                        token = token.replace(';', ' ;')
-                    if token.find('(') >= 0:
-                        token = token.replace('(', ' ( ')
-                    token = token.replace(',', ' , ')
-                    token = token.replace('=', ' = ')
-                    token = token.replace(')', ' ) ')
-                    token = token.replace('}', ' } ')
-                    output_line = output_line + ' ' + token.strip()
-            if len(output_line.strip()) > 0:
-                output_lines.append((line_number, file_name, output_line.strip() + '\n'))
+                    code = code + line[i]
+                    i = i + 1
+            parts.append(_format_code(code))
+
+            output_line = ''.join(parts).strip()
+            if len(output_line) > 0:
+                output_lines.append((line_number, file_name, output_line + '\n'))
 
         return output_lines