RailScript

Volledige huidige syntax

De keywords hieronder zijn Nederlands. De editor kan ze naar Engels of Duits vertalen. Opdrachten mogen op één regel of, waar de grammatica eenduidig blijft, over meerdere regels worden verdeeld.

Ondersteunde statements

Statement	Wat het doet
`PARAMS TYPE naam [, TYPE naam …]`	Declareert de invoerparameters van het script; dit staat vóór de uitvoerbare statements.
`RETURNS TYPE`	Declareert welk type waarde dit script met RETURN teruggeeft.
`INT naam = expressie`	Declareert een lokale variabele voor gehele getallen. STRING en BOOLEAN werken hetzelfde.
`OBJECTTYPE naam = domein["object"]`	Declareert een sterk getypeerde lokale verwijzing naar één bestaand namespaceobject.
`naam = expressie`	Geeft een reeds gedeclareerde lokale variabele een nieuwe waarde.
`ZET object.property = expressie`	Schrijft een schrijfbaar namespace-attribuut.
`LOG expressie`	Schrijft een waarde naar de RailScript-logging.
`ALS conditie DAN … ANDERS … EINDE`	Voert één van twee takken uit; ANDERS is optioneel.
`WANNEER conditie TOTDAT conditie DOE … ANDERS … EINDE`	Wacht op een eventconditie; TOTDAT en ANDERS zijn optioneel.
`ZOLANG conditie DOE … EINDE`	Herhaalt statements zolang een conditie waar blijft.
`VOOR ELK item IN object[] DOE … EINDE`	Doorloopt een momentopname van een objectcollectie.
`WACHT milliseconden`	Pauzeert alleen dit script gedurende de opgegeven tijd.
`PROMPT tekst`	Pauzeert dit script en vraagt de gebruiker om bevestiging.
`PROMPT tekst, variabele`	Vraagt de gebruiker om een waarde en bewaart deze in een bestaande variabele.
`RIJD trein VIA route [WACHTRIJ]`	Start een opgeslagen route direct of plaatst hem in de wachtrij.
`RIJD trein NAAR blok [OPSLAANALS naam]`	Genereert een route naar een bestemmingsblok en slaat hem desgewenst op.
`RUN "script" [WITH argumenten]`	Start een ander ingeschakeld projectscript met optionele parameters en gaat zelf meteen verder.
`RUN THIS`	Herstart dit script en voltooit de huidige uitvoering onmiddellijk.
`CALL "script" [WITH argumenten]`	Start een script en wacht asynchroon op de voltooiing; een eventuele returnwaarde wordt hier genegeerd.
`TYPE resultaat = CALL "script" [WITH argumenten]`	Wacht op een script en bewaart de met RETURN teruggegeven waarde.
`RETURN expressie`	Beëindigt het huidige gecallde script en geeft zijn gedeclareerde waarde terug.
`RESERVE doelen VOOR trein`	Reserveert blokken, accessoires of routes atomair voor een geplaatste trein.
`RELEASE doelen VOOR trein`	Geeft reserveringen van een trein atomair vrij.
`SWITCH [commandStation] [PROTOCOL p] ADDRESS expressie POSITION positie`	Schakelt rechtstreeks één decoderadres; standaard worden DCC en de enige aangesloten centrale gebruikt.

Commentaar

-- commentaar | // commentaar | # commentaar

Voorbeelden

-- commentaar
// commentaar
# commentaar

Lokale variabelen

INT naam = expressie | STRING naam = expressie | BOOLEAN naam = expressie | naam = expressie

Voorbeelden

INT aantal = 0
STRING bericht = "Gereed"
BOOLEAN toegestaan = WAAR
aantal = aantal + 1

De gebruiker om invoer vragen

PROMPT tekst [, variabele]

Voorbeelden

-- Alleen bevestiging
PROMPT "Zet de trein op het programmeerspoor"

-- Invoer opslaan in een bestaande lokale variabele
INT snelheid = 40
PROMPT "Gewenste snelheid?", snelheid

-- Of in een bestaande schrijfbare projectvariabele
PROMPT "Naam machinist?", variable["machinist"].value

Op een gebeurtenis wachten, eventueel met een grens

WANNEER conditie [TOTDAT conditie] DOE statements [ANDERS statements] EINDE

Voorbeelden

WANNEER feedback["K31"].occupied
TOTDAT timer["limiet"].expired
DOE
    LOG "K31 is bezet geworden"
ANDERS
    LOG "Tijdslimiet verstreken"
EINDE

Eenvoudige wachttijd

WACHT milliseconden

Voorbeelden

WACHT 1500
WACHT timer["vertraging"].durationMillis

Een decoderadres rechtstreeks schakelen

SWITCH [commandStation] [PROTOCOL protocol] ADDRESS expressie POSITION positie

Voorbeelden

-- DCC op de enige aangesloten centrale
SWITCH ADDRESS accessory["Stationssein"].address5 POSITION GREEN

-- Volledig gespecificeerde vorm
SWITCH commandStation["YaMoRC"] PROTOCOL MM ADDRESS 17 POSITION RED

Sterk getypeerde objectvariabelen

OBJECTTYPE naam = domein["naam of GUID"]

Voorbeelden

BLOCK station = block["Perron 1"]
TRAIN intercity = train["IC 123"]
ROUTE rit = route["Stationsronde"]
ACCESSORY wissel = accessory["W12"]

ZET station.maximumSpeed = 60
RESERVE station VOOR intercity
RIJD intercity VIA rit

Een objectvariabele verwijst gedurende deze scriptuitvoering naar precies één bestaand object. De validator controleert zowel het gedeclareerde type als het type rechts van het =-teken. Beschikbare types zijn COMMANDSTATION, FEEDBACK, ACCESSORY, SIGNAL, SWITCH, BLOCK, TRAIN, WAGONGROUP, TRAINTYPE, LOCOMOTIVE, VARIABLE, ROUTE, SCRIPT, COUNTER en TIMER. De vormen COMMAND_STATION, WAGON_GROUP en TRAIN_TYPE worden eveneens geaccepteerd.

Namespacewaarden lezen en schrijven

object.property | ZET object.property = expressie

Open de RailScript-namespacereferentie

Voorbeelden

LOG feedback["K31"].occupied
ZET counter["vertrekken"].value = 1
ZET accessory["A.1"].position = STRAIGHT
ZET locomotive["Class 66"].speed = 64

Voorwaarden en expressies

ALS conditie DAN statements [ANDERS statements] EINDE

Voorbeelden

ALS feedback["K31"].occupied EN NIET block["Station"].reserved
DAN
    LOG "De route mag worden voorbereid"
ANDERS
    LOG "Wachten"
EINDE

-- Operatoren: + - * / = != < <= > >= EN OF NIET ( )

NULL en ontbrekende runtimewaarden

expressie = NULL | expressie != NULL

Voorbeelden

ALS train["Intercity"].currentRoute != NULL
DAN
    LOG "De trein heeft een actieve route"
EINDE

Parameters en returnwaarden

PARAMS TYPE naam [, TYPE naam …] | RETURNS TYPE | RETURN expressie

Voorbeelden

-- Dit is het afzonderlijke script 'Kies stationsblok'
PARAMS BLOCK huidigBlok, TRAIN trein
RETURNS BLOCK
ZET huidigBlok.maximumSpeed = 50
RETURN huidigBlok

PARAMS staat, indien gebruikt, bovenaan; RETURNS staat eveneens in de scriptkop, direct na PARAMS of anders als eerste declaratie. Beschikbare types zijn INT, STRING, BOOLEAN, EVENT en alle RailScript-objecttypes. Primitieve waarden worden gekopieerd. Objecten worden als live referentie op GUID doorgegeven en teruggegeven: een wijziging via een parameter wijzigt dus het echte projectobject. Iedere uitvoeringsroute van een script met RETURNS moet een passende RETURN bereiken.

Scripts starten met RUN en CALL

RUN "script" [WITH argumenten] | TYPE resultaat = CALL "script" [WITH argumenten] | CALL "script" [WITH argumenten]

Voorbeelden

-- RUN start het script en gaat meteen verder
RUN "Meld vertrek" WITH train["Intercity"]

-- CALL wacht en bewaart hier de BLOCK-returnwaarde
BLOCK gekozen = CALL "Kies stationsblok" WITH block["Perron 1"], train["Intercity"]
LOG gekozen.name

-- Een losse CALL mag de returnwaarde negeren
CALL "Controleer station" WITH gekozen

-- Na RUN THIS wordt niets meer uitgevoerd
RUN THIS

RUN is fire-and-forget: het aangeroepen script start met de meegegeven parameters en de aanroeper gaat verder. CALL wacht op RETURN zonder de gebruikersinterface te blokkeren; WAIT, WHEN en PROMPT blijven dus ook in een gecalld script asynchroon werken. CALL-ketens zijn begrensd op 32 niveaus. Lopende en wachtende scripts zijn zichtbaar in de Script Monitor en hun uitvoering staat in Script Logging; schakel daar Debug in voor logging per statement.

Waarschuwing: scripts kunnen andere scripts starten en zichzelf opnieuw starten. Onbeheerst of zeer vaak starten kan zoveel gelijktijdige uitvoeringen veroorzaken dat RailKernel of zelfs het hele systeem vastloopt. Het begrenzen en beheersbaar houden van zulke constructies is de verantwoordelijkheid van de gebruiker.

De eventparameter

PARAMS EVENT event

Voorbeelden

-- In een door een objectevent gestart script vult RailKernel dit automatisch
PARAMS EVENT event
LOG event.type + " van " + event.objectType + " " + event.objectName
ALS event.trainName != NULL
DAN
    LOG "Trein: " + event.trainName
EINDE

De naam van de parameter is vrij te kiezen. Met PARAMS EVENT trigger gebruikt hetzelfde script bijvoorbeeld trigger.type en trigger.objectName. De bestaande impliciete event.*-waarden blijven beschikbaar voor oudere scripts.

Op iedere treinfeedback reageren

WANNEER conditie DOE statements EINDE

Voorbeelden

ZOLANG train["Intercity"].currentRoute != NULL
DOE
    WANNEER train["Intercity"].newFeedback
    DOE
        ZET train["Intercity"].function[3].active = WAAR
        WACHT 500
        ZET train["Intercity"].function[3].active = ONWAAR
    EINDE
EINDE

Herhaling

ZOLANG conditie DOE statements EINDE

Voorbeelden

INT stap = 0
ZOLANG stap < 10
DOE
    stap = stap + 1
EINDE

Collecties en VOOR ELK

VOOR ELK item IN object[] DOE statements EINDE

Voorbeelden

INT bezet = 0
VOOR ELK item IN block[]
DOE
    ALS item.occupied
    DAN
        bezet = bezet + 1
        LOG item.name + " is bezet"
    EINDE
EINDE
LOG "Bezette blokken: " + bezet

Scriptlogging

LOG expressie

Voorbeelden

LOG "Treinsnelheid: " + locomotive["Class 66"].speed

Een opgeslagen route starten of in de wachtrij zetten

RIJD trein VIA route [WACHTRIJ]

Voorbeelden

RIJD "Intercity" VIA "Stationsronde"
RIJD "Intercity" VIA "Stationsronde" WACHTRIJ

Een route naar een bestemmingsblok genereren

RIJD trein NAAR blok [OPSLAANALS "routenaam"]

Voorbeelden

-- Genereer en voer een tijdelijke route uit
RIJD train["Intercity"] NAAR block["Perron 4"]

-- Sla de gegenereerde route ook op
RIJD "Intercity" NAAR "Perron 4" OPSLAANALS "Intercity naar perron 4"

-- Namen zonder spaties mogen zonder aanhalingstekens
RIJD Intercity NAAR Perron4

Baanonderdelen reserveren en vrijgeven

RESERVE doelen VOOR trein | RELEASE doelen VOOR trein

Voorbeelden

-- Reserveer één of meer onderdelen atomair voor een geplaatste trein
RESERVE block["Perron 1"], accessory["A.1"] VOOR train["Intercity"]

-- Een blok, accessory of complete route kan worden gereserveerd
BOOLEAN gelukt = RESERVE route["Stationsronde"] VOOR train["Intercity"]
ALS gelukt
DAN
    LOG "Route gereserveerd"
EINDE

-- Geef dezelfde onderdelen vrij; RELEASE retourneert ook BOOLEAN
BOOLEAN vrijgegeven = RELEASE route["Stationsronde"] VOOR train["Intercity"]

Objectselectoren

domein["naam of GUID"].property

Voorbeelden

feedback["K31"].occupied
feedback["object-guid"].occupied
locomotive["Class 66"].function[0].name

Regels voor waarden

Objectnamen en GUIDs worden beide als selector geaccepteerd.
Tekst staat tussen dubbele aanhalingstekens; ondersteunde escapes zijn onder andere \n, \r, \t, \" en \\.
Getallen mogen geheel of decimaal zijn. Lokale INT-variabelen vereisen gehele waarden.
Booleans zijn WAAR en ONWAAR. Enumwaarden zoals STRAIGHT staan zonder aanhalingstekens.
ZET is verplicht voor namespace-attributen; lokale variabelen worden zonder ZET toegewezen.
Een scriptfout wordt vastgelegd in RailScript-logging en de Script Monitor.
NULL staat voor een waarde die momenteel ontbreekt, zoals currentRoute wanneer een trein geen actieve route heeft.
De operator ! is een compacte vorm van NIET.
PROMPT accepteert BOOLEAN-, STRING- en INT-variabelen. BOOLEAN gebruikt een WAAR/ONWAAR-keuzelijst; INT accepteert alleen gehele getallen. Annuleren van de dialoog annuleert het wachtende script.