Meta - Versionsgeschichte

Loredo: /* Encoding */

2019-07-11T14:37:40Z

Encoding

← Nächstältere Version		Version vom 11. Juli 2019, 16:37 Uhr
Zeile 50:		Zeile 50:
	=encoding utf8		=encoding utf8

	~~=for :application/json;q=META.json 00_myModule.pm~~
	{ ... }		...
	~~=end :application/json;q=META.json~~

	=cut		=cut

Loredo: /* Erweiterung eines FHEM Moduls mit META.json Pod */

2019-07-11T14:35:46Z

Erweiterung eines FHEM Moduls mit META.json Pod

← Nächstältere Version		Version vom 11. Juli 2019, 16:35 Uhr
Zeile 30:		Zeile 30:
	Für das Hinzufügen des META.json Abschnitts kann man mit der Beispieldatei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt contrib/META.json.txt] als Ausgangsbasis starten. Die oben erwähnte Spezifikation sollte man einmal gelesen haben um zu verstehen, welches Format für ein Datenfeld gilt und welche Angaben die Spezifikation als zwingend vorschreibt. Es ist empfehlenswert alle dort als ''mandatory'' erwähnten Angaben in META.json anzugeben, auch wenn diese Informationen vielleicht teilweise in anderen Dateien in FHEM bereits vorhanden sind (gilt natürlich nur für Module, die auch über das SVN verteilt werden). Beispielsweise sollte eine (Kurz-)Beschreibung trotzdem enthalten sein. Der Grund ist, dass zumindest theoretisch dann auch andere 3rd-party Tools, die mit Perl Modulen hantieren, diese Informationen in vereinfachter Art ebenfalls auslesen und auswerten können. Diese Tools könnten darauf bestehen, dass sie eben diese als zwingend spezifizierten Attribute dort auch vorfinden. FHEM::Meta fügt fehlende Informationen zwar zur Laufzeit selbst hinzu, dies hilft jedoch anderen Tools, die das JSON Objekt direkt auswerten, eben nicht. Wie genau ein Modulautor dieser Empfehlung folgen möchte, ist ihm überlassen.		Für das Hinzufügen des META.json Abschnitts kann man mit der Beispieldatei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt contrib/META.json.txt] als Ausgangsbasis starten. Die oben erwähnte Spezifikation sollte man einmal gelesen haben um zu verstehen, welches Format für ein Datenfeld gilt und welche Angaben die Spezifikation als zwingend vorschreibt. Es ist empfehlenswert alle dort als ''mandatory'' erwähnten Angaben in META.json anzugeben, auch wenn diese Informationen vielleicht teilweise in anderen Dateien in FHEM bereits vorhanden sind (gilt natürlich nur für Module, die auch über das SVN verteilt werden). Beispielsweise sollte eine (Kurz-)Beschreibung trotzdem enthalten sein. Der Grund ist, dass zumindest theoretisch dann auch andere 3rd-party Tools, die mit Perl Modulen hantieren, diese Informationen in vereinfachter Art ebenfalls auslesen und auswerten können. Diese Tools könnten darauf bestehen, dass sie eben diese als zwingend spezifizierten Attribute dort auch vorfinden. FHEM::Meta fügt fehlende Informationen zwar zur Laufzeit selbst hinzu, dies hilft jedoch anderen Tools, die das JSON Objekt direkt auswerten, eben nicht. Wie genau ein Modulautor dieser Empfehlung folgen möchte, ist ihm überlassen.

	Die Inhalte aus der Beispieldatei oben sollten als Mindestvoraussetzung angesehen werden. Insbesondere der Abschnitt <code>prereqs</code> für verwendete Perl Module ist hier wichtig, da das Vorhandensein eines selben eine wesentlich schnellere Ladezeit der Metainformationen zur Folge hat, da die Abhängigkeiten nicht durch eine Analyse erfolgen muss. Das bedeutet jedoch auch, dass diese Informationen vollständig sein müssen und der Autor dafür verantwortlich ist, das diese stimmig sind. Als Hilfestellung, was man hier für sein Modul eintragen sollte, kann man ~~sichüber~~ den FHEM Installer im oben erwähnten Developer-Modus das über das ~~Analyse-Verfahren~~ erzeugte META.json ansehen und dort den entsprechenden prereqs Abschnitt kopieren. Im Grunde werden dort alle "use" und "require" Aufrufe, die ein Modul macht, aufgeführt. Das schließt auch den Aufruf von Perl Builtin Funktionen wie "use strict;" oder ähnliches ein. Es ist empfehlenswert diese hier ebenfalls mit aufzuführen. Über die Metadaten kann man dann auch als FHEM Entwickler entsprechende Statistiken über die Code/Modul Qualität (so man die Nutzung von "use strict;" denn beispielhaft als positiv wirkend interpretieren möchte) fahren.		Die Inhalte aus der Beispieldatei oben sollten als Mindestvoraussetzung angesehen werden. Insbesondere der Abschnitt <code>prereqs</code> für verwendete Perl Module ist hier wichtig, da das Vorhandensein eines selben eine wesentlich schnellere Ladezeit der Metainformationen zur Folge hat, da die Abhängigkeiten nicht durch eine Analyse erfolgen muss. Das bedeutet jedoch auch, dass diese Informationen vollständig sein müssen und der Autor dafür verantwortlich ist, das diese stimmig sind. Als Hilfestellung, was man hier für sein Modul eintragen sollte, kann man sich über den FHEM Installer im oben erwähnten Developer-Modus das über das Analyseverfahren erzeugte META.json ansehen und dort den entsprechenden prereqs Abschnitt kopieren. Im Grunde werden dort alle "use" und "require" Aufrufe, die ein Modul macht, aufgeführt. Das schließt auch den Aufruf von Perl Builtin Funktionen wie "use strict;" oder ähnliches ein. Es ist empfehlenswert diese hier ebenfalls mit aufzuführen. Über die Metadaten kann man dann auch als FHEM Entwickler entsprechende Statistiken über die Code/Modul Qualität (so man die Nutzung von "use strict;" denn beispielhaft als positiv wirkend interpretieren möchte) fahren.

	Hat man das JSON Objekt für sein Modul nun also fertig, dann kopiert man es in seine Moduldatei ''hinter'' den letzten commandRef Abschnitt und ''vor'' der Schlussformel <code>=cut</code>. Dabei wird das META.json Objekt von folgender Markierung umschlossen:		Hat man das JSON Objekt für sein Modul nun also fertig, dann kopiert man es in seine Moduldatei ''hinter'' den letzten commandRef Abschnitt und ''vor'' der Schlussformel <code>=cut</code>. Dabei wird das META.json Objekt von folgender Markierung umschlossen:

Loredo: /* Erweiterung eines FHEM Moduls mit META.json Pod */

2019-07-11T14:34:31Z

Erweiterung eines FHEM Moduls mit META.json Pod

← Nächstältere Version		Version vom 11. Juli 2019, 16:34 Uhr
Zeile 28:		Zeile 28:
	Möchte ein Modulautor aktiven Support für FHEM::Meta einbauen, dann ist der erste Schritt die Bereitstellung eines META.json Abschnitts am Ende der Modul- oder Paketdatei. Dieser Abschnitt beinhaltet ein reguläres JSON Objekt. Deshalb empfiehlt es sich den Abschnitt vor dem hinzufügen über einen JSON Validator auf seine Syntax zu überprüfen. Ansonsten wird von FHEM::Meta beim laden eine entsprechende Meldung im FHEM Log ausgegeben und es werden keinerlei Metadaten mehr über das Modul bereitgestellt. Sobald ein META.json Abschnitt vorhanden ist, geht FHEM::Meta davon aus, dass dieses maßgeblich ist und wird deshalb nur noch Daten ergänzen, die dort nicht enthalten sind. Fehlt also ein valides META.json Objekt als Basis, so werden auch diese Ergänzungen nicht erfolgen und der Modulautor muss zunächst zwingend das JSON Gerüst korrigieren.		Möchte ein Modulautor aktiven Support für FHEM::Meta einbauen, dann ist der erste Schritt die Bereitstellung eines META.json Abschnitts am Ende der Modul- oder Paketdatei. Dieser Abschnitt beinhaltet ein reguläres JSON Objekt. Deshalb empfiehlt es sich den Abschnitt vor dem hinzufügen über einen JSON Validator auf seine Syntax zu überprüfen. Ansonsten wird von FHEM::Meta beim laden eine entsprechende Meldung im FHEM Log ausgegeben und es werden keinerlei Metadaten mehr über das Modul bereitgestellt. Sobald ein META.json Abschnitt vorhanden ist, geht FHEM::Meta davon aus, dass dieses maßgeblich ist und wird deshalb nur noch Daten ergänzen, die dort nicht enthalten sind. Fehlt also ein valides META.json Objekt als Basis, so werden auch diese Ergänzungen nicht erfolgen und der Modulautor muss zunächst zwingend das JSON Gerüst korrigieren.

	Für das Hinzufügen des META.json Abschnitts kann man mit der Beispieldatei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt contrib/META.json.txt] als Ausgangsbasis starten. Die oben erwähnte Spezifikation sollte man einmal gelesen haben um zu verstehen, welches Format für ein Datenfeld gilt und welche Angaben die Spezifikation als zwingend vorschreibt. Es ist empfehlenswert alle dort als ''mandatory'' erwähnten Angaben in META.json anzugeben, auch wenn diese Informationen vielleicht teilweise in anderen Dateien in FHEM bereits vorhanden sind (gilt natürlich nur für Module, die auch über das SVN verteilt werden). Beispielsweise sollte eine (Kurz-)Beschreibung trotzdem enthalten sein. Der Grund ist, dass zumindest theoretisch dann auch andere 3rd-party Tools, die mit Perl Modulen hantieren, diese Informationen in vereinfachter Art ebenfalls auslesen und auswerten können. Diese Tools könnten darauf bestehen, dass sie eben diese als zwingend spezifizierten Attribute dort auch vorfinden. FHEM::Meta fügt fehlende Informationen zwar zur Laufzeit selbst hinzu, dies ~~hilt~~ jedoch anderen Tools, die das JSON Objekt direkt auswerten, eben nicht. Wie genau ein Modulautor dieser Empfehlung folgen möchte, ist ihm überlassen.		Für das Hinzufügen des META.json Abschnitts kann man mit der Beispieldatei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt contrib/META.json.txt] als Ausgangsbasis starten. Die oben erwähnte Spezifikation sollte man einmal gelesen haben um zu verstehen, welches Format für ein Datenfeld gilt und welche Angaben die Spezifikation als zwingend vorschreibt. Es ist empfehlenswert alle dort als ''mandatory'' erwähnten Angaben in META.json anzugeben, auch wenn diese Informationen vielleicht teilweise in anderen Dateien in FHEM bereits vorhanden sind (gilt natürlich nur für Module, die auch über das SVN verteilt werden). Beispielsweise sollte eine (Kurz-)Beschreibung trotzdem enthalten sein. Der Grund ist, dass zumindest theoretisch dann auch andere 3rd-party Tools, die mit Perl Modulen hantieren, diese Informationen in vereinfachter Art ebenfalls auslesen und auswerten können. Diese Tools könnten darauf bestehen, dass sie eben diese als zwingend spezifizierten Attribute dort auch vorfinden. FHEM::Meta fügt fehlende Informationen zwar zur Laufzeit selbst hinzu, dies hilft jedoch anderen Tools, die das JSON Objekt direkt auswerten, eben nicht. Wie genau ein Modulautor dieser Empfehlung folgen möchte, ist ihm überlassen.

	Die Inhalte aus der Beispieldatei oben sollten als Mindestvoraussetzung angesehen werden. Insbesondere der Abschnitt <code>prereqs</code> für verwendete Perl Module ist hier wichtig, da das Vorhandensein eines selben eine wesentlich schnellere Ladezeit der Metainformationen zur Folge hat, da die Abhängigkeiten nicht durch eine Analyse erfolgen muss. Das bedeutet jedoch auch, dass diese Informationen vollständig sein müssen und der Autor dafür verantwortlich ist, das diese stimmig sind. Als Hilfestellung, was man hier für sein Modul eintragen sollte, kann man sichüber den FHEM Installer im oben erwähnten Developer-Modus das über das Analyse-Verfahren erzeugte META.json ansehen und dort den entsprechenden prereqs Abschnitt kopieren. Im Grunde werden dort alle "use" und "require" Aufrufe, die ein Modul macht, aufgeführt. Das schließt auch den Aufruf von Perl Builtin Funktionen wie "use strict;" oder ähnliches ein. Es ist empfehlenswert diese hier ebenfalls mit aufzuführen. Über die Metadaten kann man dann auch als FHEM Entwickler entsprechende Statistiken über die Code/Modul Qualität (so man die Nutzung von "use strict;" denn beispielhaft als positiv wirkend interpretieren möchte) fahren.		Die Inhalte aus der Beispieldatei oben sollten als Mindestvoraussetzung angesehen werden. Insbesondere der Abschnitt <code>prereqs</code> für verwendete Perl Module ist hier wichtig, da das Vorhandensein eines selben eine wesentlich schnellere Ladezeit der Metainformationen zur Folge hat, da die Abhängigkeiten nicht durch eine Analyse erfolgen muss. Das bedeutet jedoch auch, dass diese Informationen vollständig sein müssen und der Autor dafür verantwortlich ist, das diese stimmig sind. Als Hilfestellung, was man hier für sein Modul eintragen sollte, kann man sichüber den FHEM Installer im oben erwähnten Developer-Modus das über das Analyse-Verfahren erzeugte META.json ansehen und dort den entsprechenden prereqs Abschnitt kopieren. Im Grunde werden dort alle "use" und "require" Aufrufe, die ein Modul macht, aufgeführt. Das schließt auch den Aufruf von Perl Builtin Funktionen wie "use strict;" oder ähnliches ein. Es ist empfehlenswert diese hier ebenfalls mit aufzuführen. Über die Metadaten kann man dann auch als FHEM Entwickler entsprechende Statistiken über die Code/Modul Qualität (so man die Nutzung von "use strict;" denn beispielhaft als positiv wirkend interpretieren möchte) fahren.

Loredo: /* Erweiterung eines FHEM Moduls mit META.json Pod */

2019-07-11T14:32:36Z

Erweiterung eines FHEM Moduls mit META.json Pod

← Nächstältere Version		Version vom 11. Juli 2019, 16:32 Uhr
Zeile 26:		Zeile 26:
	== Erweiterung eines FHEM Moduls mit META.json Pod ==		== Erweiterung eines FHEM Moduls mit META.json Pod ==

	Möchte ein Modulautor aktiven Support FHEM::Meta einbauen, dann ist der erste Schritt die Bereitstellung eines META.json Abschnitts am Ende der Modul- oder Paketdatei. Dieser Abschnitt beinhaltet ein reguläres JSON Objekt. Deshalb empfiehlt es sich den Abschnitt vor dem hinzufügen über einen JSON Validator auf seine Syntax zu überprüfen. Ansonsten wird von FHEM::Meta beim laden eine entsprechende Meldung im FHEM Log ausgegeben und es werden keinerlei Metadaten mehr über das Modul bereitgestellt. Sobald ein META.json Abschnitt vorhanden ist, geht FHEM::Meta davon aus, dass dieses maßgeblich ist und wird deshalb nur noch Daten ergänzen, die dort nicht enthalten sind. Fehlt also ein valides META.json Objekt als Basis, so werden auch diese Ergänzungen nicht erfolgen und der Modulautor muss zunächst zwingend das JSON Gerüst korrigieren.		Möchte ein Modulautor aktiven Support für FHEM::Meta einbauen, dann ist der erste Schritt die Bereitstellung eines META.json Abschnitts am Ende der Modul- oder Paketdatei. Dieser Abschnitt beinhaltet ein reguläres JSON Objekt. Deshalb empfiehlt es sich den Abschnitt vor dem hinzufügen über einen JSON Validator auf seine Syntax zu überprüfen. Ansonsten wird von FHEM::Meta beim laden eine entsprechende Meldung im FHEM Log ausgegeben und es werden keinerlei Metadaten mehr über das Modul bereitgestellt. Sobald ein META.json Abschnitt vorhanden ist, geht FHEM::Meta davon aus, dass dieses maßgeblich ist und wird deshalb nur noch Daten ergänzen, die dort nicht enthalten sind. Fehlt also ein valides META.json Objekt als Basis, so werden auch diese Ergänzungen nicht erfolgen und der Modulautor muss zunächst zwingend das JSON Gerüst korrigieren.

	Für das Hinzufügen des META.json Abschnitts kann man mit der Beispieldatei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt contrib/META.json.txt] als Ausgangsbasis starten. Die oben erwähnte Spezifikation sollte man einmal gelesen haben um zu verstehen, welches Format für ein Datenfeld gilt und welche Angaben die Spezifikation als zwingend vorschreibt. Es ist empfehlenswert alle dort als ''mandatory'' erwähnten Angaben in META.json anzugeben, auch wenn diese Informationen vielleicht teilweise in anderen Dateien in FHEM bereits vorhanden sind (gilt natürlich nur für Module, die auch über das SVN verteilt werden). Beispielsweise sollte eine (Kurz-)Beschreibung trotzdem enthalten sein. Der Grund ist, dass zumindest theoretisch dann auch andere 3rd-party Tools, die mit Perl Modulen hantieren, diese Informationen in vereinfachter Art ebenfalls auslesen und auswerten können. Diese Tools könnten darauf bestehen, dass sie eben diese als zwingend spezifizierten Attribute dort auch vorfinden. FHEM::Meta fügt fehlende Informationen zwar zur Laufzeit selbst hinzu, dies hilt jedoch anderen Tools, die das JSON Objekt direkt auswerten, eben nicht. Wie genau ein Modulautor dieser Empfehlung folgen möchte, ist ihm überlassen.		Für das Hinzufügen des META.json Abschnitts kann man mit der Beispieldatei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt contrib/META.json.txt] als Ausgangsbasis starten. Die oben erwähnte Spezifikation sollte man einmal gelesen haben um zu verstehen, welches Format für ein Datenfeld gilt und welche Angaben die Spezifikation als zwingend vorschreibt. Es ist empfehlenswert alle dort als ''mandatory'' erwähnten Angaben in META.json anzugeben, auch wenn diese Informationen vielleicht teilweise in anderen Dateien in FHEM bereits vorhanden sind (gilt natürlich nur für Module, die auch über das SVN verteilt werden). Beispielsweise sollte eine (Kurz-)Beschreibung trotzdem enthalten sein. Der Grund ist, dass zumindest theoretisch dann auch andere 3rd-party Tools, die mit Perl Modulen hantieren, diese Informationen in vereinfachter Art ebenfalls auslesen und auswerten können. Diese Tools könnten darauf bestehen, dass sie eben diese als zwingend spezifizierten Attribute dort auch vorfinden. FHEM::Meta fügt fehlende Informationen zwar zur Laufzeit selbst hinzu, dies hilt jedoch anderen Tools, die das JSON Objekt direkt auswerten, eben nicht. Wie genau ein Modulautor dieser Empfehlung folgen möchte, ist ihm überlassen.
Zeile 61:		Zeile 61:

	Hat man nun also den META.json Abschnitt ordnungsgemäß hinzugefügt, kann man mit Hilfe des FHEM Installer überprüfen, ob die Daten richtig hinterlegt worden sind und geladen werden können.		Hat man nun also den META.json Abschnitt ordnungsgemäß hinzugefügt, kann man mit Hilfe des FHEM Installer überprüfen, ob die Daten richtig hinterlegt worden sind und geladen werden können.


	== Eigenständiges Laden der Metadaten aus einem FHEM Modul heraus ==		== Eigenständiges Laden der Metadaten aus einem FHEM Modul heraus ==

Loredo: /* Einleitung */

2019-07-11T14:29:30Z

Einleitung

← Nächstältere Version		Version vom 11. Juli 2019, 16:29 Uhr
Zeile 6:		Zeile 6:
	Neben den für ein FHEM Modul notwendigen [[DevelopmentModuleIntro\|obligatorischen]] Metadaten (CommandRef, Kurzbeschreibung, Typ), gibt es in FHEM das Perl Package FHEM::Meta (oder kurz Meta.pm). Die Einbindung in ein FHEM Modul (= stellt Devices zur Verfügung) oder ein FHEM Package (= stellt Subroutinen für ein oder mehrere FHEM Module bereit) ermöglicht es, Informationen über das Modul in Form eines JSON [https://perldoc.perl.org/perlpod.html Pod] (auch META.json genannt) direkt in die Datei mit einzubetten. Darüber wird es möglich, diese Zusatzinformationen auch bereits auszuwerten und anzuzeigen, ohne dass ein Modul geladen oder verwendet wird. Beispielsweise kann ermittelt werden, welche Perl Module für die Nutzung des Moduls notwendig sind und ob eine bestimmte Version vorausgesetzt wird. Außerdem können Informationen über die Version des Moduls, die Historie, den Autor, für Supportanfragen und vieles weiteres hinterlegt werden.		Neben den für ein FHEM Modul notwendigen [[DevelopmentModuleIntro\|obligatorischen]] Metadaten (CommandRef, Kurzbeschreibung, Typ), gibt es in FHEM das Perl Package FHEM::Meta (oder kurz Meta.pm). Die Einbindung in ein FHEM Modul (= stellt Devices zur Verfügung) oder ein FHEM Package (= stellt Subroutinen für ein oder mehrere FHEM Module bereit) ermöglicht es, Informationen über das Modul in Form eines JSON [https://perldoc.perl.org/perlpod.html Pod] (auch META.json genannt) direkt in die Datei mit einzubetten. Darüber wird es möglich, diese Zusatzinformationen auch bereits auszuwerten und anzuzeigen, ohne dass ein Modul geladen oder verwendet wird. Beispielsweise kann ermittelt werden, welche Perl Module für die Nutzung des Moduls notwendig sind und ob eine bestimmte Version vorausgesetzt wird. Außerdem können Informationen über die Version des Moduls, die Historie, den Autor, für Supportanfragen und vieles weiteres hinterlegt werden.

	Das Grundschema für die JSON Struktur basiert dabei auf der offiziellen [https://metacpan.org/pod/CPAN::Meta::Spec CPAN::Meta::Spec] Spezifikation, welche auch bei regulär veröffentlichten Perl Modulen verwendet wird. Das FHEM::Meta Package hilft dabei, diese JSON Informationen aus der Datei auszulesen und stellt diese im globalen %modules Hash des jeweiligen Moduls zur weiteren Verarbeitung bereit. Meta wertet dabei die in der Moduldatei (bei Modulen, die im SVN veröffentlicht sind, auch ~~die in FHEM bereits bekannten~~) hinterlegten Maintenance und Supportdaten aus, so dass diese Informationen für sämtliche FHEM Module grundsätzlich bereitgestellt werden können. Meta erweitert die Standard Spezifikation dafür mit eigenen JSON Attributen, die spezifikationskonform im Namen mit <code>x_</code> beginnen. Diese Art, zusätzliche Informationen über die Funktionalität eines Modules bereitzustellen, ohne dass ein Modul dafür tatsächlich geladen werden muss, steht jedem Modul als Erweiterung zur Verfügung. Es ist also denkbar, dass Module darüber bekanntmachen, welche Netzwerk-Protokolle sie beherrschen, wie bestimmte Geräte im Netzwerk gefunden werden können und mit welchen define-Parametern ein Gerät in FHEM angelegt werden kann. Hierzu gibt es erste Ansätze, die sich in [https://forum.fhem.de/index.php/topic,67368.0.html Planung] befinden.		Das Grundschema für die JSON Struktur basiert dabei auf der offiziellen [https://metacpan.org/pod/CPAN::Meta::Spec CPAN::Meta::Spec] Spezifikation, welche auch bei regulär veröffentlichten Perl Modulen verwendet wird. Das FHEM::Meta Package hilft dabei, diese JSON Informationen aus der Datei auszulesen und stellt diese im globalen %modules Hash des jeweiligen Moduls zur weiteren Verarbeitung bereit. Meta wertet dabei die in der Moduldatei (bei Modulen, die im SVN veröffentlicht sind, auch weitere Informationsquellen/-dateien des SVN) hinterlegten Maintenance und Supportdaten aus, so dass diese Informationen für sämtliche FHEM Module grundsätzlich bereitgestellt werden können. Meta erweitert die Standard Spezifikation dafür mit eigenen JSON Attributen, die spezifikationskonform im Namen mit <code>x_</code> beginnen. Diese Art, zusätzliche Informationen über die Funktionalität eines Modules bereitzustellen, ohne dass ein Modul dafür tatsächlich geladen werden muss, steht jedem Modul als Erweiterung zur Verfügung. Es ist also denkbar, dass Module darüber bekanntmachen, welche Netzwerk-Protokolle sie beherrschen, wie bestimmte Geräte im Netzwerk gefunden werden können und mit welchen define-Parametern ein Gerät in FHEM angelegt werden kann. Hierzu gibt es erste Ansätze, die sich in [https://forum.fhem.de/index.php/topic,67368.0.html Planung] befinden.


	== Der FHEM Installer ==		== Der FHEM Installer ==

Loredo: /* Development Module and Package Meta Data */

2019-07-11T13:21:18Z

Development Module and Package Meta Data

← Nächstältere Version		Version vom 11. Juli 2019, 15:21 Uhr
Zeile 4:		Zeile 4:
	== Einleitung ==		== Einleitung ==

	Neben den für ein FHEM Modul notwendigen [[DevelopmentModuleIntro\|obligatorischen]] Metadaten (CommandRef, Kurzbeschreibung, Typ), gibt es in FHEM das Perl Package FHEM::Meta (oder kurz Meta.pm). Die Einbindung in ein FHEM Modul (= stellt Devices zur Verfügung) oder ein FHEM Package (= stellt Subroutinen für ein oder mehrere FHEM Module bereit) ermöglicht es, Informationen über das Modul in Form eines JSON [https://perldoc.perl.org/perlpod.html Pod] (auch META.json genannt) direkt in die Datei mit einzubetten. Darüber wird es möglich, diese Zusatzinformationen auch bereits auszuwerten und anzuzeigen, ohne dass ein Modul ~~bereits~~ geladen oder verwendet wird. Beispielsweise kann ermittelt werden, welche Perl Module für die Nutzung des Moduls notwendig sind und ob eine bestimmte Version vorausgesetzt wird. Außerdem können Informationen über die Version des Moduls, die Historie, den Autor, für Supportanfragen und vieles weiteres hinterlegt werden.		Neben den für ein FHEM Modul notwendigen [[DevelopmentModuleIntro\|obligatorischen]] Metadaten (CommandRef, Kurzbeschreibung, Typ), gibt es in FHEM das Perl Package FHEM::Meta (oder kurz Meta.pm). Die Einbindung in ein FHEM Modul (= stellt Devices zur Verfügung) oder ein FHEM Package (= stellt Subroutinen für ein oder mehrere FHEM Module bereit) ermöglicht es, Informationen über das Modul in Form eines JSON [https://perldoc.perl.org/perlpod.html Pod] (auch META.json genannt) direkt in die Datei mit einzubetten. Darüber wird es möglich, diese Zusatzinformationen auch bereits auszuwerten und anzuzeigen, ohne dass ein Modul geladen oder verwendet wird. Beispielsweise kann ermittelt werden, welche Perl Module für die Nutzung des Moduls notwendig sind und ob eine bestimmte Version vorausgesetzt wird. Außerdem können Informationen über die Version des Moduls, die Historie, den Autor, für Supportanfragen und vieles weiteres hinterlegt werden.

	Das Grundschema für die JSON Struktur basiert dabei auf der offiziellen [https://metacpan.org/pod/CPAN::Meta::Spec CPAN::Meta::Spec] Spezifikation, welche auch bei regulär veröffentlichten Perl Modulen verwendet wird. Das FHEM::Meta Package hilft dabei, diese JSON Informationen aus der Datei auszulesen und stellt diese im globalen %modules Hash des jeweiligen Moduls zur weiteren Verarbeitung bereit. Meta wertet dabei die in der Moduldatei (bei Modulen, die im SVN veröffentlicht sind, auch die in FHEM bereits bekannten) hinterlegten Maintenance und Supportdaten aus, so dass diese Informationen für sämtliche FHEM Module grundsätzlich bereitgestellt werden können. Meta erweitert die Standard Spezifikation dafür mit eigenen JSON Attributen, die spezifikationskonform im Namen mit <code>x_</code> beginnen. Diese Art, zusätzliche Informationen über die Funktionalität eines Modules bereitzustellen, ohne dass ein Modul dafür tatsächlich geladen werden muss, steht jedem Modul als Erweiterung zur Verfügung. Es ist also denkbar, dass Module darüber bekanntmachen, welche Netzwerk-Protokolle sie beherrschen, wie bestimmte Geräte im Netzwerk gefunden werden können und mit welchen define-Parametern ein Gerät in FHEM angelegt werden kann. Hierzu gibt es erste Ansätze, die sich in [https://forum.fhem.de/index.php/topic,67368.0.html Planung] befinden.		Das Grundschema für die JSON Struktur basiert dabei auf der offiziellen [https://metacpan.org/pod/CPAN::Meta::Spec CPAN::Meta::Spec] Spezifikation, welche auch bei regulär veröffentlichten Perl Modulen verwendet wird. Das FHEM::Meta Package hilft dabei, diese JSON Informationen aus der Datei auszulesen und stellt diese im globalen %modules Hash des jeweiligen Moduls zur weiteren Verarbeitung bereit. Meta wertet dabei die in der Moduldatei (bei Modulen, die im SVN veröffentlicht sind, auch die in FHEM bereits bekannten) hinterlegten Maintenance und Supportdaten aus, so dass diese Informationen für sämtliche FHEM Module grundsätzlich bereitgestellt werden können. Meta erweitert die Standard Spezifikation dafür mit eigenen JSON Attributen, die spezifikationskonform im Namen mit <code>x_</code> beginnen. Diese Art, zusätzliche Informationen über die Funktionalität eines Modules bereitzustellen, ohne dass ein Modul dafür tatsächlich geladen werden muss, steht jedem Modul als Erweiterung zur Verfügung. Es ist also denkbar, dass Module darüber bekanntmachen, welche Netzwerk-Protokolle sie beherrschen, wie bestimmte Geräte im Netzwerk gefunden werden können und mit welchen define-Parametern ein Gerät in FHEM angelegt werden kann. Hierzu gibt es erste Ansätze, die sich in [https://forum.fhem.de/index.php/topic,67368.0.html Planung] befinden.

Loredo am 11. Juli 2019 um 13:00 Uhr

2019-07-11T13:00:14Z

← Nächstältere Version		Version vom 11. Juli 2019, 15:00 Uhr
Zeile 35:		Zeile 35:
	Hat man das JSON Objekt für sein Modul nun also fertig, dann kopiert man es in seine Moduldatei ''hinter'' den letzten commandRef Abschnitt und ''vor'' der Schlussformel <code>=cut</code>. Dabei wird das META.json Objekt von folgender Markierung umschlossen:		Hat man das JSON Objekt für sein Modul nun also fertig, dann kopiert man es in seine Moduldatei ''hinter'' den letzten commandRef Abschnitt und ''vor'' der Schlussformel <code>=cut</code>. Dabei wird das META.json Objekt von folgender Markierung umschlossen:

			==== META.json Abschnitt ====
	<syntaxhighlight lang="perl">		<syntaxhighlight lang="perl">
	=for :application/json;q=META.json 00_myModule.pm		=for :application/json;q=META.json 00_myModule.pm
Zeile 44:		Zeile 45:
	Alle Informationen innerhalb des META.json sind im UTF-8 Format. Dies machen wir deshalb zusätzlich nochmals zum Beginn des <code>=pod</code> Abschnitts ''vor'' dem ersten CommandRef Eintrag deutlich:		Alle Informationen innerhalb des META.json sind im UTF-8 Format. Dies machen wir deshalb zusätzlich nochmals zum Beginn des <code>=pod</code> Abschnitts ''vor'' dem ersten CommandRef Eintrag deutlich:

			==== Encoding ====
	<syntaxhighlight lang="perl">		<syntaxhighlight lang="perl">
	=pod		=pod

Loredo: /* Anzeigen der Modulversion über FHEM::Meta */

2019-07-11T12:58:43Z

Anzeigen der Modulversion über FHEM::Meta

← Nächstältere Version		Version vom 11. Juli 2019, 14:58 Uhr
Zeile 109:		Zeile 109:
	Als Informationen sind hier verpackt:		Als Informationen sind hier verpackt:
	* Dateiname des Moduls inkl. Präfix		* Dateiname des Moduls inkl. Präfix
	* semantische Version (version-Attribut in META.json vorhanden)		* semantische Version (= version-Attribut in META.json vorhanden)
	* Subversion Revision (-s steht für "Subversion", danach folgt die Revisionsnummer des jeweiligen Commits)		* Subversion Revision (-s steht für "Subversion", danach folgt die Revisionsnummer des jeweiligen Commits)
	* das Release Datum (hier konkret das Check-in Datum in das SVN)		* das Release Datum (hier konkret das Check-in Datum in das SVN)

Loredo: /* Eigenständiges Laden der Metadaten aus einem FHEM Modul heraus */

2019-07-11T12:57:01Z

Eigenständiges Laden der Metadaten aus einem FHEM Modul heraus

← Nächstältere Version		Version vom 11. Juli 2019, 14:57 Uhr
Zeile 67:		Zeile 67:
	Hierfür muss am Beginn der Moduldatei zunächst <code>use FHEM::Meta;</code> hinzugefügt werden und die <code>X_Initialize();</code> Funktion am Ende um einen Initialisierungsaufruf erweitert werden:		Hierfür muss am Beginn der Moduldatei zunächst <code>use FHEM::Meta;</code> hinzugefügt werden und die <code>X_Initialize();</code> Funktion am Ende um einen Initialisierungsaufruf erweitert werden:

			==== X_Initialize ====
	<syntaxhighlight lang="perl">		<syntaxhighlight lang="perl">
	use FHEM::Meta;		use FHEM::Meta;
Zeile 80:		Zeile 81:

	Die Metadaten werden dann beim Initialisieren des Moduls nach $modules{<TYPE>}{META} geladen und stehen dort bereit.		Die Metadaten werden dann beim Initialisieren des Moduls nach $modules{<TYPE>}{META} geladen und stehen dort bereit.


	== Anzeigen der Modulversion über FHEM::Meta ==		== Anzeigen der Modulversion über FHEM::Meta ==

Loredo am 11. Juli 2019 um 12:49 Uhr

2019-07-11T12:49:50Z

← Nächstältere Version		Version vom 11. Juli 2019, 14:49 Uhr
Zeile 36:		Zeile 36:

	<syntaxhighlight lang="perl">		<syntaxhighlight lang="perl">
	=for :application/json;q=META.json ~~'''~~00_myModule.pm~~'''~~		=for :application/json;q=META.json 00_myModule.pm
	{ ... }		{ ... }
	=end :application/json;q=META.json		=end :application/json;q=META.json
Zeile 47:		Zeile 47:
	=pod		=pod

	~~'''~~=encoding utf8~~'''~~		=encoding utf8

	=for :application/json;q=META.json 00_myModule.pm		=for :application/json;q=META.json 00_myModule.pm
Zeile 68:		Zeile 68:

	<syntaxhighlight lang="perl">		<syntaxhighlight lang="perl">
	~~'''~~use FHEM::Meta;~~'''~~		use FHEM::Meta;

	sub X_Initialize($)		sub X_Initialize($)
Zeile 75:		Zeile 75:
	...		...

	~~'''~~return FHEM::Meta::InitMod( __FILE__, $hash );~~'''~~		return FHEM::Meta::InitMod( __FILE__, $hash );
	}		}
	</syntaxhighlight>		</syntaxhighlight>
Zeile 94:		Zeile 94:
	{		{
	my ( $hash, $def ) = @_;		my ( $hash, $def ) = @_;
	~~'''~~return $@ unless ( FHEM::Meta::SetInternals($hash) );~~'''~~		return $@ unless ( FHEM::Meta::SetInternals($hash) );
	...		...