.. _`kognihome/tools/kom`: ======== KogniCom ======== 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. .. note:: Entwickler und Autoren werden **ausdrücklich** gebeten ihrer Schnittstelle Beispieldaten hinzuzufügen. `KogniCom` bietet Mechanismen an, um sowohl die Dokumentation, als auch das Testen zu unterstützen. :Kontakt: Alexander Neumann :CITK: `kognicom `_ :Vorbedingung: Python (2.7), setuptools, :ref:`guides/rsb` und :ref:`guides/rst` sind installiert und im ``PYTHONPATH`` vefügbar. `KogniCom` kann entweder über das :ref:`guides/citk` gebaut und ausgerollt werden oder ausgecheckt und gebaut werden mit:: $ python setup.py install [--prefix=/path/to/kognihome] :Quickstart: `KogniCom` installiert das Tool ``kom``, welches von der Kommandozeile aus aufgerufen werden kann:: $ 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 Die dazugehörige :term:`YAML`-Datei könnte folgendermaßen aussehen: .. code-block:: yaml %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 Kom konfigurieren ----------------- Mit ``kom set `` 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 :term:`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. Auf Scopes lauschen ------------------- Mit ``kom listen -s [-s ]`` kann auf einen oder mehrere Scopes gelauscht werden. Die Ausgabe erfolgt auf die Konsole im :term:`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 :term:`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 [-s ]`` können vordefinierte Nachrichten gesendet werden. Auch für ```` 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. 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: .. code-block:: yaml %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 .. note:: Zur Einrückung werden in Settings-Dateien **Zwei Leerzeichen** verwendet. Einrückung ist für YAML wichtig, da sie Blockzugehörigkeit definiert. Es ist empfohlen einen Text-Editor oder eine IDE mit YAML-Syntax-Unterstützung zu verwenden. 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 :ref:`kognihome/kitchen/chef`-Kontext, kann an :ref:`kognihome/kitchen/screen` gesendet werden, um den ersten Schritt des Rezeptes anzuzeigen: .. literalinclude:: /../static/kognihome/examples/chef.yaml :language: yaml :start-after: Chef: Springe zu Schritt Step1_Milchreis :end-before: END :dedent: 10 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. .. todo:: * test and document `test` * add `--test-constraints`` if low effort * if required send-delay could be made accessible for kom