[ Impressum ]

LiveCode JSONlib

www.Rozek.de > LiveCode > JSONlib
Die "JSONlib" ist ein kleiner LiveCode [1] "Library Stack" mit Funktionen für die Serialisierung von LiveCode Daten in eine JSON[2]-Zeichenkette bzw. Deserialisierung von JSON-Zeichenketten in LiveCode-Daten.

Download und Installation

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

Verwendung in Desktop-Anwendungen

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

start using stack "JSONlib"

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 "JSONlib" 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 "JSONlib" 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") & "/JSONlib.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 "JSONlib" enthält die folgenden zwei Funktionen:

JSON_stringified (<LiveCodeValue> [, <maxIndentation>])


JSON_stringified serialisiert den übergebenen LiveCodeValue in eine JSON-Zeichenkette und liefert diese an den Aufrufer zurück. Mithilfe des optionalen Parameters maxIndentation kann die Formatierung der JSON-Ausgabe gesteuert werden:
  • maxIndentation < 0
    JSON_stringified
    liefert eine einzige Textzeile zurück (die also keinerlei Zeilenvorschübe enthält);
     
  • maxIndentation = 0
    JSON_stringified
    liefert mehrere Zeilen Text zurück (mit ungefähr einem Wert pro Zeile), rückt diese Zeilen jedoch nicht ein;
     
  • maxIndentation > 0
    JSON_stringified
    liefert mehrere Zeilen Text zurück (mit ungefähr einem Wert pro Zeile) und rückt die Inhalte von (numerisch indizierten) Arrays und Objekten (d.h. literal indizierten LiveCode Arrays) mit insgesamt bis zu maxIndentation Leerzeichen ein. Die Einrückung pro Schachtelungsebene beträgt derzeit ein Leerzeichen.
"Primitive" Daten (wie boolesche Werte, Zahlen und Zeichenketten) werden stets in eine einzige Zeile serialisiert - nur Arrays und Objekte werden auf Wunsch (d.h. in Abhängigkeit von maxIndentation) auch in mehreren Zeilen dargestellt.

JSON_stringified kann die folgenden Exceptions werfen:
  • "UninitializedLibrary: ..."
    wird geworfen, wenn die "JSONlib" nicht als Library Stack eingebunden wurde (siehe oben);
     
  • "MissingArgument: ..."
    wird geworfen, wenn der zu serialisierende LiveCodeValue fehlt;
     
  • "InvalidArgument: ..."
    wird geworfen, wenn die angegebene maxIndentation keine ganze Zahl ist.

JSON_parsed (<JSONstring>)


JSON_parsed analysiert den gegebenen JSONstring und liefert die darin enthaltenen LiveCode-Daten zurück.

JSON_parsed kann die folgenden Exceptions werfen:
  • "UninitializedLibrary: ..."
    wird geworfen, wenn die "JSONlib" nicht als Library Stack eingebunden wurde (siehe oben);
     
  • "EmptyArgument: ..."
    wird geworfen, wenn der zu analysierende JSONstring fehlt oder leer ist;
     
  • "UnexpectedCharacter: ..."
    wird geworfen, wenn JSON_parsed auf ein unzulässiges Zeichen stößt;
     
  • "UnexpectedEOF: ..."
    wird geworfen, wenn JSON_parsed das Ende des JSONstring erreicht hat, obwohl eigentlich noch Angaben zu erwarten sind;
     
  • "InvalidNumber: ..."
    wird geworfen, wenn JSON_parsed einen Wert entdeckt hat, der eigentlich wie eine Zahl aussieht, aber nicht in eine Zahl umgewandelt werden kann.
Einschränkungen

Da sich LiveCode signifikant von JavaScript (und vielen anderen Programmiersprachen) unterscheidet, unterliegt die Umwandlung von LiveCode-Werten von und nach JSON einer Reihe von Einschränkungen:
  • LiveCode unterstützt keine null-Referenzen
    JSON_parsed
    wandelt null stattdessen in eine leere Zeichenkette um;
     
  • LiveCode unterstützt keine "leeren" Arrays oder Objekte
    JSON_parsed
    wandelt diese stattdessen in eine leere Zeichenkette um;
     
  • die Indices von JSON-Arrays beginnen stets bei 0
    JSON_parsed verwendet bei der Deserialisierung numerisch indizierter Felder dieselbe Form der Indizierung - und JSON_stringified erwartet mit 0 beginnende Indizes, wenn es entscheiden muss, ob ein LiveCode-Array als JavaScript Array oder Objekt serialisiert werden soll.

System-Anforderungen

Die "JSONlib" 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 "JSONlib" hängt von keinem weiteren Stack ab.

Bekannte Fehler

Derzeit sind keine Fehler der "JSONlib" bekannt.

Lizenz-Hinweis

Die "JSONlib" 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 "JSONlib"! 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.
[2]
Douglas Crockford
JSON (JavaScript Object Notation)
JSON ist ein kompaktes Textformat für die Darstellung und den Austausch strukturierter Daten (ähnlich wie XML). Es ist in seiner Syntax an die Programmiersprache JavaScript angelehnt und lässt sich entsprechend einfach lesen und verarbeiten.