[ Impressum ]

LiveCode ValidatorLib

www.Rozek.de > LiveCode > ValidatorLib
Die "ValidatorLib" ist ein kleiner LiveCode [1] "Library Stack" mit einer Reihe von Kommandos für die Validierung von erforderlichen oder optionalen Argumenten.

Download und Installation

Die "ValidatorLib" liegt als unverschlüsselter LiveCode-Stack bereit und kann von hier aus heruntergeladen werden:
Nach dem Herunterladen legen Sie die "ValidatorLib" einfach in einem Verzeichnis Ihrer Wahl ab - eine explizite Installation ist nicht erforderlich.

Verwendung in Desktop-Anwendungen

Die "ValidatorLib" wurde als LiveCode "Library Stack" implementiert und muss deshalb vor ihrer Verwendung zunächst einmalig mithilfe der Anweisung

start using stack "ValidatorLib"

eingebunden werden. Zweckmäßigerweise wird diese Anweisung im Rahmen einer preOpenStack-Prozedur von einem MainStack ausgeführt.

Soll aus dem MainStack später eine eigenständige Anwendung werden, muss die "ValidatorLib" außerdem Bestandteil der Liste der "Stack Files" zu diesem MainStack sein (am einfachsten geschieht dies mithilfe der "Standalone Application Settings" aus der LiveCode-Entwicklungsumgebung heraus).

Verwendung in mobilen Anwendungen

Die "ValidatorLib" kann auch in mobilen Anwendungen eingesetzt werden. Allerdings muss sie dann - anders als für eigenständige Desktop-Anwendungen - in die Liste der "non-stack files" aufgenommen und mithilfe der Anweisung

start using stack (specialFolderPath("engine") & "/ValidatorLib.livecode")

in den MainStack eingebunden werden. Die Liste der "non-stack files" findet sich ebenfalls auf der Seite "Copy Files" in den "Standalone Application Settings" der LiveCode-Entwicklungsumgebung.

Funktionsübersicht

Die "ValidatorLib" enthält vor allem Kommandos zur Validierung mitgegebener Argumente. Ist die Validierung erfolgreich, laufen die Kommandos ohne weitere Vorkommnisse durch und das aufrufende Skript kann fortgesetzt werden. Schlägt sie aber fehl, wird eine entsprechende Ausnahme geworfen, die das rufende Skript verarbeiten kann.

Validierung optionaler Argumente

Die erste Hälfte der Kommandos (diejenigen, deren Name mit "allow" beginnt) validiert optionale Argumente - von der zweiten Hälfte unterschieden sich diese Prozeduren dadurch, dass das übergebene Argument auch empty sein darf. Die Kommandos sind (in alphabetischer Reihenfolge):

allowArray <ArgName>, <ArgValue>


allowArray stellt sicher, dass das der übergebene ArgValue entweder fehlt (d.h. empty ist) oder ein numerisch indiziertes LiveCode-Array darstellt.

Die Indizes müssen bei 0 beginnen und bei n-1 enden, wobei n die Anzahl der Schlüssel in ArgValue darstellt. Diese Konvention wurde eingeführt, um eine gewisse Kompatibilität mit JSON-Arrays sicherzustellen - sollte Ihr LiveCode Array diese Forderung nicht erfüllen, wäre es besser, auf allowObject auszuweichen.

ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

allowBoolean <ArgName>, <ArgValue>


allowBoolean stellt sicher, dass das der übergebene ArgValue entweder fehlt (d.h. empty ist) oder von LiveCode als gültiger boolescher Wert erkannt wird. ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

allowColor <ArgName>, <ArgValue>


allowColor stellt sicher, dass das der übergebene ArgValue entweder fehlt (d.h. empty ist) oder von LiveCode als gültige (numerische oder symbolische) Farbangabe erkannt wird. ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

allowDate <ArgName>, <ArgValue>


allowDate stellt sicher, dass das der übergebene ArgValue entweder fehlt (d.h. empty ist) oder von LiveCode als gültige Datumsangabe erkannt wird. ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

allowIdentifier <ArgName>, <ArgValue>


allowIdentifier stellt sicher, dass das der übergebene ArgValue entweder fehlt (d.h. empty ist) oder (in möglichst vielen Programmiersprachen) einen gültigen Bezeichner (bestehend aus Buchstaben, Ziffern und Unterstrichen - aber nicht mit einer Ziffer am Anfang) darstellt. ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

allowInteger <ArgName>, <ArgValue> [, minValue [, maxValue]]


allowInteger stellt sicher, dass das der übergebene ArgValue entweder fehlt (d.h. empty ist) oder von LiveCode als ganze Zahl erkannt wird.

Sofern vorhanden (und nicht empty), legen minValue und maxValue die niedrigsten bzw. höchsten zulässigen Werte für ArgValue fest.

ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

allowNumber <ArgName>, <ArgValue> [, minValue [, maxValue [, withoutMin [, withoutMax]]]]


allowNumber stellt sicher, dass das der übergebene ArgValue entweder fehlt (d.h. empty ist) oder von LiveCode als gültige Zahl erkannt wird.

Sofern vorhanden (und nicht empty), legen minValue und maxValue die niedrigsten bzw. höchsten zulässigen Werte für ArgValue fest. Hat withoutMin den Wert true, so ist minValue selbst nicht Teil des zulässigen Werte-Intervalles - auf der anderen Seite schließt die Angabe true für withoutMax den Wert maxValue aus dem zulässigen Wertebereich aus.

ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

allowObject <ArgName>, <ArgValue> [, requiredKey [, ...]]


allowObject stellt sicher, dass das der übergebene ArgValue entweder fehlt (d.h. empty ist) oder ein gültiges LiveCode-Array enthält.

Evtl. weitere Angaben (requiredKey u.a.) sind Schlüssel, die in ArgValue enthalten sein müssen, damit allowObject erfolgreich durchläuft (der jeweilige Wert des betreffenden Array-Elementes ist dabei unerheblich).

ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

allowOneOf <ArgName>, <ArgValue>, foreseenValue [, ...]


allowOneOf stellt sicher, dass das der übergebene ArgValue entweder fehlt (d.h. empty ist) oder einen der angegebenen zulässigen Werte (foreseenValue u.a.) enthält. ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

allowPoint <ArgName>, <ArgValue>


allowPoint stellt sicher, dass das der übergebene ArgValue entweder fehlt (d.h. empty ist) oder von LiveCode als gültige Punkt-Koordinate erkannt wird. ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

allowRectangle <ArgName>, <ArgValue>


allowRectangle stellt sicher, dass das der übergebene ArgValue entweder fehlt (d.h. empty ist) oder von LiveCode als gültige Rechteck-Koordinaten erkannt wird. ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

allowString <ArgName>, <ArgValue>


allowString stellt sicher, dass das der übergebene ArgValue entweder fehlt (d.h. empty ist) oder von LiveCode als Zeichenkette erkannt wird - was in der Praxis bedeutet, dass ArgValue kein LiveCode Array enthält. ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

Validierung erforderlicher Argumente

Die zweite Hälfte der Kommandos (diejenigen, deren Name mit "expect" beginnt) validiert mandatorische Argumente - von der ersten Hälfte unterschieden sich diese Prozeduren dadurch, dass das übergebene Argument üblicherweise nicht empty sein darf. Die Kommandos sind (in alphabetischer Reihenfolge):

expectArray <ArgName>, <ArgValue>


expectArray stellt sicher, dass das der übergebene ArgValue vorhanden (also nicht empty) ist und ein numerisch indiziertes LiveCode-Array darstellt.

Die Indizes müssen bei 0 beginnen und bei n-1 enden, wobei n die Anzahl der Schlüssel in ArgValue darstellt. Diese Konvention wurde eingeführt, um eine gewisse Kompatibilität mit JSON-Arrays sicherzustellen - sollte Ihr LiveCode Array diese Forderung nicht erfüllen, wäre es besser, auf expectObject auszuweichen.

ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

expectBoolean <ArgName>, <ArgValue>


expectBoolean stellt sicher, dass das der übergebene ArgValue vorhanden (also nicht empty) ist und von LiveCode als gültiger boolescher Wert erkannt wird. ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

expectColor <ArgName>, <ArgValue>


expectColor stellt sicher, dass das der übergebene ArgValue vorhanden (also nicht empty) ist undvon LiveCode als gültige (numerische oder symbolische) Farbangabe erkannt wird. ArgName muss einsyntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

expectDate <ArgName>, <ArgValue>


expectDate stellt sicher, dass das der übergebene ArgValue vorhanden (also nicht empty) ist und von LiveCode als gültige Datumsangabe erkannt wird. ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

expectIdentifier <ArgName>, <ArgValue>


expectIdentifier stellt sicher, dass das der übergebene ArgValue vorhanden (also nicht empty) ist und (in möglichst vielen Programmiersprachen) einen gültigen Bezeichner (bestehend aus Buchstaben, Ziffern und Unterstrichen - aber nicht mit einer Ziffer am Anfang) darstellt. ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

expectInteger <ArgName>, <ArgValue> [, minValue [, maxValue]]


expectInteger stellt sicher, dass das der übergebene ArgValue vorhanden (also nicht empty) ist und von LiveCode als ganze Zahl erkannt wird.

Sofern vorhanden (und nicht empty), legen minValue und maxValue die niedrigsten bzw. höchsten zulässigen Werte für ArgValue fest.

ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

expectNumber <ArgName>, <ArgValue> [, minValue [, maxValue [, withoutMin [, withoutMax]]]]


expectNumber stellt sicher, dass das der übergebene ArgValue vorhanden (also nicht empty) ist und von LiveCode als gültige Zahl erkannt wird.

Sofern vorhanden (und nicht empty), legen minValue und maxValue die niedrigsten bzw. höchsten zulässigen Werte für ArgValue fest. Hat withoutMin den Wert true, so ist minValue selbst nicht Teil des zulässigen Werte-Intervalles - auf der anderen Seite schließt die Angabe true für withoutMax den Wert maxValue aus dem zulässigen Wertebereich aus.

ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

expectObject <ArgName>, <ArgValue> [, requiredKey [, ...]]


expectObject stellt sicher, dass das der übergebene ArgValue vorhanden (also nicht empty) ist und ein gültiges LiveCode-Array enthält.

Evtl. weitere Angaben (requiredKey u.a.) sind Schlüssel, die in ArgValue enthalten sein müssen, damit expectObject erfolgreich durchläuft (der jeweilige Wert des betreffenden Array-Elementes ist dabei unerheblich).

ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

expectOneOf <ArgName>, <ArgValue>, foreseenValue [, ...]


expectOneOf stellt sicher, dass das der übergebene ArgValue vorhanden (also nicht empty) ist und einen der angegebenen zulässigen Werte (foreseenValue u.a.) enthält. ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

expectPoint <ArgName>, <ArgValue>


expectPoint stellt sicher, dass das der übergebene ArgValue vorhanden (also nicht empty) ist und von LiveCode als gültige Punkt-Koordinate erkannt wird. ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

expectRectangle <ArgName>, <ArgValue>


expectRectangle stellt sicher, dass das der übergebene ArgValue vorhanden (also nicht empty) ist und von LiveCode als gültige Rechteck-Koordinaten erkannt wird. ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

expectString <ArgName>, <ArgValue> [, nonEmpty]


expectString stellt sicher, dass das der übergebene ArgValue von LiveCode als Zeichenkette erkannt wird - was in der Praxis bedeutet, dass ArgValue kein LiveCode Array enthält. ArgValue darf hier ausnahmsweise auch empty sein - es sei denn, nonEmpty besitzt den Wert true. ArgName muss ein syntaktisch korrekter, nicht-leerer LiveCode-Bezeichner sein und wird dazu verwendet, für eine evtl. zu werfende Ausnahme eine sinnvolle Fehlermeldung zu bilden.

System-Anforderungen

Die "ValidatorLib" benötigt LiveCode 6.x oder neuer und funktioniert unabhängig vom jeweiligen Betriebssystem sowohl auf stationären wie auch auf mobilen Plattformen.

Abhängigkeiten

Die "ValidatorLib" verwendet intern die "BasicLib" - beim Einsatz der "ValidatorLib" muss diese also ebenfalls vorhanden sein.

Automatisierte Tests

Für die "ValidatorLib" steht auch ein separater Stack mit automatisierten Tests dieser Bibliothek bereit:
Beim Öffnen dieses Stack wird zugleich auch das Kommando performTests ausgeführt, welches für die eigentlichen Tests zuständig ist. Am Ende sollte die "Message Box" der LiveCode-Entwicklungsumgebung erscheinen und die Meldung

all tests passed

angezeigt werden - anderenfalls sollte dort stattdessen eine Fehlermeldung mit Hinweisen zum fehlgeschlagenen Test zu finden sein.

Bekannte Fehler

Derzeit sind keine Fehler der "ValidatorLib" bekannt.

Lizenz-Hinweis

Die "ValidatorLib" und die zugehörigen Tests unterliegen der "Creative Commons Namensnennung 4.0 Unported Lizenz", was im Wesentlichen bedeutet, dass Sie beides (selbst in kommerziellem Rahmen) sowohl verwenden als auch verändern dürfen, sofern Sie Ihre Änderungen als solche kenntlich machen und an geeigneter Stelle auf mich als den ursprünglichen Autor hinweisen.

                       
Viel Spaß mit LiveCode und der "ValidatorLib"! Creative Commons Lizenzvertrag

Literaturhinweise

[1]
(RunRev Ltd.)
LiveCode | Create apps for multiple platforms. Quickly. Easily. Free
LiveCode ist eine (dem legendären HyperCard von Apple) nachempfundene Entwicklungsumgebung sowohl für stationäre (Windows, Linux, MacOS X) als auch für mobile (IOS, Android) Anwendungen. Ein visueller Editor ermöglicht den schnellen Entwurf von Bedienoberflächen, die der englischen Sprache nachempfundene Programmiersprache erlaubt auch Nicht-Programmierprofis die Entwicklung professioneller Anwendungen und das Konzept der "Modifikation am laufenden Programm" vereinfacht Test und Fehlerbehebung.