1.30.2.6. KogniCom¶

1.30.2.6.1. Zusammenfassung¶

KogniCom ist ein RSB-Werkzeug welches als Ergänzung zu rsb-tools genutzt werden kann, um Scopes und Beispielnachrichten zu definieren. Anderen Entwicklern wird es dadurch ermöglicht Komponenten mit diesen Beispielnachrichten zu testen und dadurch bereits gegen nicht finalisierte Schnittstellen zu entwickeln. Außerdem kann mit Hilfe ausführlicher Beispielnachrichten auch die Funktionalität einer Komponente durch Testen geprüft werden.

$ python setup.py install [--prefix=/path/to/kognihome]

$ kom -d /path/to/settings.yaml listen -s /foo/bar # listens to scope /foo/bar
$ kom -d /path/to/settings.yaml send -s /foo/bar String # sends Example message scope foo bar
$ kom set config /path/to/settings.yaml # sets /path/to/config.yaml as default setting

%YAML 1.2
---

foo:
  bar:
    type: rst.generic.Value
    examples:
      "String":
        type: 4 # VALUE.STRING
        string: "Hello World"
      # END
      "Integer":
        type: 2 # Value.Integer
        int: 42
      # END
  baz:
    type: string

1.30.2.6.2. Kom konfigurieren¶

Mit kom set <variable> <value> können Standardwerte für Kom festgelegt werden. Besonders die Verwendung einer festen Setting-Datei bieten sich an, da sich dieser Kontext selten ändert. Die Kom-Konfiguration wird unter $USER/ .config/kom.cfg abgelegt. Folgende Variablen werden unterstützt:

• config – definiert die YAML-Datei mit dem Scope-Baum und den Beispielnachrichten
• limit – definiert nach wie vielen Nachrichten ein Listener deaktivert werden soll. Dieser Parameter bietet sich für Nachrichten an, die mit hoher Frequenz gesendet werden.

1.30.2.6.3. Auf Scopes lauschen¶

Mit kom listen -s <scope> [-s <scope>] kann auf einen oder mehrere Scopes gelauscht werden. Die Ausgabe erfolgt auf die Konsole im JSON-Format. kom unterstützt das sogenannte Unix filename pattern matching. Das heißt Scopes müssen nicht vollständig, sondern nur eindeutig angegeben werden (mit Wildcards). Für das oben genannte Beispiel-Setting würde also kom listen -s */bar ausreichen. Sogar kom listen -s *r wäre hinreichend genau.

Folgende optionale Parameter werden untertützt:

• config – die zu ladende Config-Datei (Standartwert ist ~/.config/kom.cfg)
• definitions – die zu ladende YAML-Datei (Muss angegeben werden, wenn nicht durch die Konfiguration spezifiert)
• max-messages – definiert nach wie vielen Nachrichten ein Listener deaktiviert werden soll. Entpricht dem limit-Konfigurationsparameter.

Vordefinierte Beispielnachrichten senden:

Mit kom send -s <scope> <example> [-s <scope> <example>] können vordefinierte Nachrichten gesendet werden. Auch für <example> wird das pattern matching verwendet. kom listen -s *r S* würde demnach auf Scope /foo/bar die Beispielnachricht String absetzen.

Folgende optionale Parameter werden unterstützt:

• amount – gibt an, wie oft die Nachricht gesendet werden soll.

1.30.2.6.4. Aufbau der YAML-Datei¶

Die oben beschriebenen :YAML:-Settings sind Teil dieser Dokumentation. Autoren finden diese unter static/kognihome/examples im Quellcode. Nur Blätter mit einem type-Blatt werden als mögliche Scopes interpretiert. Diese Limitierung resultiert aus der Tatsache, dass für sogenannte Parents mehr als ein Nachrichtentyp möglich ist. KogniCom prüft das Nachrichtenschema eines Scopes jedoch nicht bei jeder Nachricht, sondern setzt dieses initial durch die mitgegebenen Settings. Deshalb ist Vorsicht geboten, wenn Subscopes andere Nachrichtentypen erwarten, als ihr Parent. Ist ein Typ definiert, können auch Beispiele definiert werden:

%YAML 1.2
---

root:
  branch1:
    leaf1.1:
      type: message_type
    branch1.2:
      leaf1.2.1:
        type: message_type
        examples:
          "key 1": {message content}
          # END
          "key 2": {message content}
          # END

Die Kommentarfelder #END hinter Beispielen sind keine Notwendigkeit für die Settings, sondern erlauben die Benutzung der Code-Snippets innerhalb der Dokumentation einer Komponente. Dies reduziert den Wartungsaufwand bei der Anpassung von Schnittstellen und Nachrichtentypen. Die folgende Nachricht aus dem KogniChef-Kontext, kann an GUI-Interaktionsinsel gesendet werden, um den ersten Schritt des Rezeptes anzuzeigen:

  id: Step1_Milchreis
  done: false

Der Direktivaufruf in der Dokumentation dazu ist:

.. literalinclude:: /../static/kognihome/examples/chef.yaml
    :language: yaml
    :start-after: Chef: Springe zu Schritt Step1_Milchreis
    :end-before: END
    :dedent: 10

:detent: ist hier optional und kann je nach Bedarf zur Einrückung gesetzt werden.