prima-tmlink – Online in der Cloud

PROGRAMM:

NAME/FUNKTION

gencls – Klassenschnittstellen-Compiler für Prima-Kernmodule

ZUSAMMENFASSUNG

gencls --h --inc --tml -O -I --depend --sayparent Dateiname.cls

BESCHREIBUNG

Erstellt Header mit C-Makros und Strukturen für Objektdefinitionen des Prima-Kernmoduls.

ARGUMENTE

gencls akzeptiert die folgenden Argumente:

--h Erstellt eine .h-Datei (mit Deklarationen, die in eine oder mehrere Dateien aufgenommen werden sollen)

--inc
Erstellt eine .inc-Datei (mit Deklarationen, die nur in die Datei aufgenommen werden sollen)

-O Aktiviert den Optimierungsalgorithmus für .inc-Dateien. Der Algorithmus basiert auf einer Annahme,
dass einige Funktionen identisch deklariert sind, daher der Codeteil, der sie verarbeitet
Die Parameter- und Ergebniskonvertierung kann gemeinsam genutzt werden. Wenn die Flagge „-O“ aktiviert ist, handelt es sich um einen Thunk-Body
durch einen Aufruf einer Funktion ersetzt, deren Name sich aus allen Methodenparametern zusammensetzt
plus Ergebnis. Die eigentliche Funktion wird nicht in die .inc-Datei geschrieben, sondern in die .tml-Datei. Alle
Doppelte Deklarationen aus einer Reihe von .tml-Dateien können entfernt und die Erinnerung angezeigt werden
vom Dienstprogramm tmlink in eine Datei geschrieben.

--tml
Erzeugt eine .tml-Datei. Schaltet „-O“ automatisch ein.

-Idirname
Fügt einem Suchpfad ein Verzeichnis hinzu, in dem das Dienstprogramm nach CLS-Dateien sucht. Kann sein
mehrfach angegeben.

--abhängen
Druckt Abhängigkeiten für eine bestimmte Datei aus.

--sayparent
Gibt das unmittelbare übergeordnete Element einer Klasse in der angegebenen Datei aus.

SYNTAX

Kurz gesagt kann die Syntax einer .cls-Datei durch das folgende Schema beschrieben werden:

[null oder mehr Typdeklarationen]
[null oder eine Klassendeklaration]

Gencls erzeugt .h-, .inc- oder .tml-Dateien mit einem Basisnamen der .cls-Datei, wenn kein Objekt oder vorhanden ist
Der angegebene Paketname oder andernfalls der Name des Objekts oder Pakets.

Grundlagen Skalar frustrierten Typen
Gencls verfügt über mehrere integrierte Skalardatentypen, mit denen es umzugehen weiß. Verkaufen'
bedeutet, dass es einen Code generieren kann, der Daten dieser Art zwischen C und Perl überträgt.
Verwenden der XS-Bibliotheksschnittstelle (siehe Perlguts).

Die Typen sind:

int
Bool
Handle
doppelt
SV*
HV*
Zeichen *
string (C-Deklaration ist char[256])

Es gibt auch einige abgeleitete integrierte Typen

lange
kurz
verkohlen
Farbe
U8

die auf int abgebildet sind. Die Daten werden im Übertragungsprozess nicht in int konvertiert, sondern
wird stattdessen mit Perl-Skalar gespeichert neuSViv() Funktion, die wiederum Bits verlieren kann
oder ein Zeichen.

Abgeleitet frustrierten Typen
Die Syntax für eine neue Datentypdefinition lautet wie folgt:



Ein Bereich kann eines von zwei Pragmas sein: „global“ oder „lokal“. Sie weisen auf die Verwendung neuer Daten hin
Typ, ob der Typ nur für ein oder mehrere Objekte verwendet wird. Die Verwendung von „lokal“ ist
ähnelt etwas dem statischen C-Pragma. Derzeit besteht der einzige Unterschied darin, dass es sich um eine Funktion handelt
Verwendung eines komplexen lokalen Typs in der Parameterliste oder da das Ergebnis kein Subjekt für ist
„-O“-Optimierung.

Scalar Typen
Neue Skalartypen dürfen nur mit einem Alias ​​auf die vorhandenen Typen angewendet werden, vor allem für die C-Codierung
Bequemlichkeit. Ein Skalartyp kann auf zwei Arten definiert werden:

Direktes Aliasing
Syntax:

$id => ;

Ejemplo:

global $Handle => int;

Die neue Typ-ID ist in C-Dateien nicht sichtbar, der Typ wird jedoch ersetzt
alle .cls-Dateien, die diese Definition enthalten.

C-Makro
Syntax:

id1 id2

Ejemplo:

globales API_HANDLE UV

Ein solcher Code erstellt eine C-Makrodefinition in der Form einer .h-Headerdatei

#definiere id1 id2

C-Makros mit Parametern sind nicht erlaubt. id1 und id2 müssen nicht vorhanden sein
im .cls-Namensraum und es erfolgt keine Ersetzung während der Verarbeitung der .cls-Datei. Das
Die Verwendung von Pragma ist sehr begrenzt.

Complex Typen
Komplexe Datentypen können Arrays, Strukturen und Hashes sein. Sie können eine Kombination oder eine sein
Vektor skalarer (aber nicht komplexer) Datentypen.

Gencls erlaubt mehrere Kombinationen komplexer Datentypen, die in der C-Sprache nicht möglich sind
erkenne. Diese werden im Folgenden beschrieben.

Komplexe Datentypen werden nicht in Perl-Code importiert. Ein Perl-Programmierer muss sich daran halten
Der Datentyp, der bei der Übergabe von Parametern an eine Funktion verwendet wird.

Arrays
Syntax:

@Ausweis [Abmessungen];

Ejemplo:

global @FillPattern U8[8];

Beispiel für Funktionen mit Arrays:

Array * func( Array a1, Array * a2);

Perl-Code:

@ret = func( @array1, @array2);

Beachten Sie, dass keine Array-Referenzen verwendet werden, sondern die Anzahl der Elemente im gesamten Array
Die Parameter müssen genau den Abmessungen der Arrays entsprechen.

Hinweis: Die folgende Deklaration lässt sich nicht mit dem C-Compiler kompilieren, da C nicht zurückkehren kann
Arrays. Allerdings wird es von gencls nicht als Fehler behandelt:

Array func();

Strukturen
Syntax:

@Ausweis {
;
...
;
};

Ejemplo:

global @Struc {
int Zahl;
String-ID;
}

Beispiel für Funktionen, die Strukturen verwenden:

Struc * func1( Struc a1, Struc * a2);
Struc func2( Struc a1, Struc * a2);

Perl-Code:

@ret = func1( @struc1, @struc2);
@ret = func2( @struc1, @struc2);

Beachten Sie, dass keine Array-Referenzen verwendet werden und dass sowohl die Anzahl als auch die Reihenfolge der Elemente insgesamt berücksichtigt werden
Array-Parameter müssen genau auf die Abmessungen und Reihenfolge der Strukturen eingestellt werden. Struktur
Feldnamen werden auch im Perl-Code nicht verwendet.

Hashes
Syntax:

%Ausweis {
;
...
;
};

Ejemplo:

globaler %Hash {
int Zahl;
String-ID;
}

Beispiel für Funktionen, die Hashes verwenden:

Hash * func1( Hash a1, Hash * a2);
Hash func2( Hash a1, Hash * a2);

Perl-Code:

%ret = %{func1( \%hash1, \%hash2)};
%ret = %{func2( \%hash1, \%hash2)};

Beachten Sie, dass nur Hash-Referenzen verwendet und zurückgegeben werden. Wenn ein Hash von Perl übergeben wird
Code kann es sein, dass einige oder alle Felder nicht festgelegt sind. Die C-Struktur wird gefüllt und an a übergeben
C-Funktion und die nicht gesetzten Felder werden einer entsprechenden zugewiesen
C_TYPE_UNDEF-Wert, wobei TYPE eines der Literale NUMERIC, STRING und POINTER ist.

Die Rückkonvertierung berücksichtigt diese Werte nicht und gibt immer alle Hash-Schlüssel mit a zurück
entsprechendes Paar.

Namespace Abschnitt
Syntax:

{

...

}

Eine .cls-Datei kann null oder einen Namespace-Abschnitt enthalten, der mit Funktionsbeschreibungen gefüllt ist.
Die hier beschriebenen Funktionen werden während des Initialisierungscodes in die angegebene ID exportiert. A
Namespace kann entweder „Objekt“ oder „Paket“ sein.

Die Paket-Namespace-Syntax erlaubt nur die Deklaration von Funktionen innerhalb eines „Pakets“.
blockieren.

Paket {

...
}

Die Objekt-Namespace-Syntax umfasst Variablen und Eigenschaften sowie Funktionen (
sogenannte Methoden in der Objektsyntax). Die allgemeine Objekt-Namespace-Syntax lautet

Objekt [(Elternklassen-ID)] {



}

Innerhalb eines Objektnamensraums kann die Vererbungssyntax verwendet werden:

Objekt ( ) { ... }

oder eine bloße Root-Objektbeschreibung (ohne Vorfahren)

Objekt { ... }

für die Objektklassendeklaration.

Funktionen
Syntax:

[ ] ( ) [ => ];

Beispiele:

int package_func1( int a, int b = 1) => c_func_2;
Punkt package_func2( Struc * x, ...);
Methode void object_func3( HV * Profil);

Ein Präfix wird nur bei Objektfunktionen (Methoden) verwendet. Mehr zum Präfix in Methoden
.

Eine Funktion kann nichts (void), einen Skalar (int, string usw.) oder einen komplexen Wert (
Array, Hash) Typ. Es kann auch skalare und komplexe Parameter mit Typ akzeptieren
Konvertierung, die den oben in „Grundlegende skalare Datentypen“ beschriebenen Regeln entspricht
.

Wenn eine Funktion Parameter und/oder Ergebnisse eines Typs hat, der nicht konvertiert werden kann
automatisch zwischen C und Perl, es wird deklariert, aber nicht dem Perl-Namespace ausgesetzt. Der
Es erfolgt eine entsprechende Warnung. Mit der gencls-Syntax ist es nicht möglich, a zu deklarieren
Funktion mit benutzerdefinierten Parametern oder Ergebnisdaten. Zu diesem Zweck wurde explizit C
Es muss eine Codedeklaration zusammen mit dem „newXS“-Aufruf erfolgen.

Beispiel: Auslassungspunkte (...) können von gencls nicht konvertiert werden, es handelt sich jedoch um ein zulässiges C
Konstruktion.

Punkt package_func2( Struc * x, ...);

Die Funktionssyntax weist mehrere praktische Ergänzungen auf:

Standardparameterwerte
Ejemplo:

void func( int a = 15);

Eine so deklarierte Funktion kann sowohl mit 0 als auch mit 1 Parametern aufgerufen werden. Wenn ja
Wird mit 0 Parametern aufgerufen, wird automatisch ein ganzzahliger Wert von 15 verwendet. Der
Die Syntax erlaubt Standardparameter für die Typen int, pointer und string sowie deren Skalar
Aliase.

Es können so viele Standardparameter wie möglich sein, sie müssen jedoch am Ende stehen
Funktionsparameterliste. Deklaration „func( int a = 1, int b)“ ist falsch.

Aliasing
Im generierten C-Code muss nach Eingabe der Parameter eine C-Funktion aufgerufen werden
analysiert. Gencls erwartet, dass im C-Code eine konforme Funktion mit festem Namen vorhanden ist
und Parameterliste. Wenn die Aufgabe einer solchen Funktion jedoch ein Wrapper für eine identische Funktion ist
Wenn eine Funktion unter einem anderen Namen veröffentlicht wird, kann Aliasing durchgeführt werden, um sowohl Code als auch zu speichern
Geschwindigkeit.

Ejemplo:

Paket Paket {
void func( int x) => internal;
}

Eine auf diese Weise deklarierte Funktion wird nicht aufgerufen Package_func() C-Funktion, aber
intern() Funktion stattdessen. Die einzige Bitte ist das intern() Funktion muss haben
identische Parameter- und Ergebnisdeklaration zu a func().

Inline-Hash
Es wurde eine praktische Möglichkeit entwickelt, eine Funktion mit einem Hash als Parameter aus Perl aufzurufen. Wenn ein
Funktion wird mit dem letzten Parameter oder Typ „HV*“ deklariert, dann Parameterübersetzung
von Perl nach C wird so durchgeführt, als ob alle übergebenen Parameter ein Hash wären. Dieser Hash ist
an eine C-Funktion übergeben und der Inhalt wird dann wieder als Hash an Perl zurückgegeben.
Der Hash-Inhalt kann innerhalb der C-Funktion geändert werden.

Diese Deklaration wird häufig in Konstruktoren verwendet, was typisch für Perl-Code ist

Sub-Init
{
mein %ret = shift-> SUPER::init( @_);
...
return %ret;
}

und C-Code ist normalerweise

void Obj_init ( HV * Profil) {
geerbt init( Profil);
... [Profilinhalt ändern] ...
}

Methoden
Methoden sind Funktionen, die im Kontext eines Objekts aufgerufen werden. Praktisch alle Methoden müssen dies tun
Zugriff auf ein Objekt haben, mit dem sie es zu tun haben. Prima-Objekte sind in C als sichtbar
Behandeln Sie den Datentyp. Ein solcher Handle ist eigentlich ein Zeiger auf eine Objektinstanz, die wiederum
enthält einen Zeiger auf die Tabelle der virtuellen Objektmethoden (VMT). Um ein OO-ähnliches zu erleichtern
Aufgrund der Syntax wird dieser Handle-Parameter fast nie in allen Methoden eines Objekts erwähnt
Beschreibung in einer CLS-Datei, obwohl implizit gezählt, also jede CLS-Methode
Erklärung

Methode void a( int x)

Für eine Objektklasse wird Object in C als reflektiert

void Object_a( Handle self, int x)

Funktionsdeklaration. Im Gegensatz zu Paketfunktionen kann gencls if nicht veröffentlichen
Es ist nicht in der Lage, mit den nicht unterstützten, nicht konvertierbaren Parametern umzugehen. Es gibt eine Möglichkeit dazu
Geben Sie eine solche Deklaration mit einer Methode aus. Der Hauptzweck hierfür ist der Methodenname
im VMT des Objekts reserviert.

Auf Methoden kann im C-Code durch die direkte Namensdereferenzierung eines „Handle self“ als a zugegriffen werden
entsprechende Struktur:

((( PSampleObject) self)-> self)-> sample_method( self, ...);

Eine Methode kann eines von sechs Präfixen haben, die die C-Code-Generierung steuern:

Methode
Dies ist der erste und grundlegendste Methodentyp. Der Präfixname lautet „Methode“.
Daher wurde der aussagekräftigste Name gewählt. Es wird erwartet, dass Methoden codiert werden
C ist das Objekthandle implizit und nicht in einer .cls-Beschreibung enthalten.

Methode void a()

Ergebnisse in

void Object_a( Handle self)

C-Deklaration. Eine veröffentlichte Methode konvertiert automatisch ihre Parameter und ein Ergebnis
zwischen C und Perl.

Öffentlichkeit
Wenn die Methoden Parameter und/oder Ergebnisse haben, die nicht automatisch sein können
Konvertierungen zwischen C und Perl müssen deklariert werden, andernfalls ist die Funktionsdeklaration nicht erforderlich
Um in die C-Syntax zu passen, wird ein „öffentliches“ Präfix verwendet. Die mit „public“ deklarierten Methoden sind
Es wird erwartet, dass die Kommunikation mit Perl über die XS-Schnittstelle (siehe perlxs) erfolgt. Es ist auch
erwartet, dass eine „öffentliche“ Methode sowohl REDEFINED- als auch FROMPERL-Funktionen erstellt (siehe
Prima::internals für Details). Beispiele gibt es überall in der Prima-Quelle und im Willen
werden hier nicht angezeigt. „öffentliche“ Methoden haben normalerweise ein leeres Ergebnis und keine Parameter, aber
Das spielt keine große Rolle, da gencls für solche Methoden keine Konvertierung erstellt.

importieren
Für die Methoden, die sich nicht in C, sondern stattdessen in Perl codieren lassen, kann es sich um gencls handeln
wird angewiesen, die entsprechenden Wrapper mit dem Präfix „import“ zu erstellen. So eine Art
Methode kann als „Methode“ von innen nach außen betrachtet werden. Die Funktion „import“ benötigt kein C
Gegenstück, mit Ausnahme des automatisch generierten Codes.

statisch
Wenn eine Methode sowohl mit als auch ohne Objektinstanz funktionieren muss, muss sie dies tun
muss das Präfix „statisch“ vorangestellt werden. „statische“ Methoden sind alle gleich „Methoden“,
außer dass der erste Parameter „Handle self“ nicht implizit deklariert ist. Wenn eine „statische“
Methode wird ohne Objekt (aber mit Klasse) aufgerufen, z

Class::Object-> static_method();

Sein erster Parameter ist kein Objekt, sondern ein „Class::Object“-String. Wenn eine Methode nie
sich mit einem Objekt befasst, reicht es aus, seine Deklaration als zu verwenden

static a( char * className = "");

aber ist, wenn es so ist, a

static a( SV * class_or_object = nil);

Erklärung ist erforderlich. Im letzteren Fall muss der C-Code selbst bestimmen, was genau hat
bestanden, wenn überhaupt. Beachten Sie hier den Standardparameter: Normalerweise handelt es sich um eine „statische“ Methode
lesbar zu nennen als

Class::Object::static_method();

wobei ihm keine Parameter übergeben werden. Ohne den Standardparameter wäre ein solcher Aufruf möglich
generiert den Laufzeitfehler „Unzureichende Parameter übergeben“.

seltsam
Wir konnten keinen besseren Namen dafür finden. Das Präfix „seltsam“ bezeichnet eine Methode, die kombiniert wird
Eigenschaften sowohl von „statisch“ als auch von „öffentlich“. Mit anderen Worten, gencls generiert nein
Konvertierungscode und erwartet kein „Handle self“ als ersten Parameter für eine solche Methode.
Als Beispiel sei Prima::Image::load dargestellt, das über ein Wide aufgerufen werden kann
Spektrum der Aufrufsemantik (siehe Prima::image-load für Details).

c_only
Wie der Name schon sagt, handelt es sich bei „c_only“ um eine Methode, die auf einem VMT vorhanden, aber nicht vorhanden ist
Von Perl aus zugänglich. Es kann nur von C aus überladen werden. Darüber hinaus ist es erlaubt
Registrieren Sie eine Perl-Funktion mit dem Namen einer „c_only“-Methode und trotzdem diese Entitäten
völlig unabhängig voneinander sein - die Überlastung findet nicht statt.

Hinweis: Methoden mit Ergebnis- und/oder Parameterdatentypen, die nicht konvertiert werden können
automatisch ihr Präfix in „c_only“ ändern. Wahrscheinlich ist das das falsche Verhalten,
und ein solcher Zustand muss einen Fehler signalisieren.

Immobilien
Das Prima-Toolkit führt eine Entität namens Eigenschaft ein, die die Methode ersetzen soll
Paare, deren Funktion darin besteht, eine interne Objektvariable zu erfassen und zuzuweisen, z. B.
ein Objektname, eine Farbe usw. Anstelle von Methodenpaaren wie Object::set_color und
Object::get_color, eine Eigenschaft Object::color wird entwickelt. Eine Eigenschaft ist eine Methode mit dem
Besondere Überlegungen, insbesondere wenn es ohne Parameter aufgerufen wird, ein „Get“-Modus
ist impliziert. Im Gegensatz dazu wird bei einem Aufruf mit einem Parameter ein „Set“-Modus ausgelöst.
Beachten Sie, dass sowohl bei „set“- als auch bei „get“-Aufrufen „Handle self“ der erste implizite Parameter ist
immer anwesend.

Eigenschaften können mit unterschiedlichen, aber festen Parametermengen arbeiten und einen „Satz“ ausführen.
und „get“ funktioniert nur für einen. Standardmäßig ist der einzige Parameter das implizite „Handle“.
selbst":

Eigenschaft char * Name

hat ein C-Gegenstück

char * Object_name( Handle self, Bool set, char * name)

Je nach Modus ist „Bool set“ entweder „true“ oder „false“. Im Set-Modus ein C-Code
Das Ergebnis wird verworfen, im Get-Modus ist der Parameterwert undefiniert.

Die Syntax für die Eigenschaft mit mehreren Parametern lautet

Eigenschaft long pixel( int x, int y);

und C-Code

long Object_pixel( Handle self, Bool set, int x, int y, long pixel)

Beachten Sie, dass im Fall mehrerer Parameter die Parameter nach dem Eigenschaftsnamen deklariert werden
immer initialisiert, sowohl im Set- als auch im Get-Modus.

Beispiel Variablen
Jedes Objekt zeichnet sich durch seinen einzigartigen inneren Zustand aus. Die Gencls-Syntax ermöglicht a
Variablendeklaration für Variablen, die jeder Objektinstanz zugewiesen werden. Obwohl
Für Variablen wird keine Datentypvalidierung durchgeführt und ihre Deklarationen werden einfach abgerufen
„wie sie sind“ kopiert, komplexe C-Deklarationen mit Array-, Struktur- und Funktionszeigern werden kopiert
nicht wiedererkannt. Um dieses Problem zu umgehen, werden Zeiger auf typisierte Entitäten verwendet. Beispiel:

Objekt SampleObject {
int x;
Listenliste;
struct { int x } s; # illegale Deklaration
}

Auf Variablen kann im C-Code durch direkte Namensdereferenzierung eines „Handle self“ als a zugegriffen werden
entsprechende Struktur:

(( PSampleObject) self)-> x;

AUTOREN

Dmitri Karasik,[E-Mail geschützt] >. Anton Berezin,[E-Mail geschützt] >.

Nutzen Sie prima-tmlink online über die Dienste von onworks.net