Skip to main content

Groovy reference

This section is common to groovy listeners and scripted simulations. It lists various scripting methods that were not introduced, available only if called from Groovy.

Methods​

include(scriptPath)​

  • Signature: void include(String scriptPath)
  • Arguments:
    • scriptPath path, relative to the calling script.
  • Usage: 
    include('config.script')
    Executes the script in scriptPath and includes its bindings in the caller script bindings. It is useful for finding configuration files written in groovy.

loadScript(scriptPath)​

  • Signature: void loadScript(String scriptPath)
  • Arguments:
    • scriptPath path, relative to the calling script.
  • Usage: 
    loadScript('other-script.script')
    Loads and parses the script in scriptPath with the same shell as the calling script. It is useful for including snippets in an event listener.

loadScript(scriptPath, delegate)​

  • Signature: void loadScript(String scriptPath, Object delegate)
  • Arguments:
    • scriptPath path, relative to the calling script.
    • delegate object used as a delegate for the script to be loaded.
  • Usage: 
    def delegate = new MyDelegate()
    loadScript('other-script.script', delegate)
    Loads and parses the script in scriptPath with the same shell as the calling script. It is useful for including snippets in an event listener.
👷👷🏾 Document all the BaseScript methods

Events​

Extension methods​

Simulation settings​

SimulationOptionConfiguration getAt(optionName)​

  • Signature: SimulationOptionConfiguration getAt[String optionName], which is the same as settings[optionName]
  • Arguments:
    • optionName name of the simulation option
  • Usage: 
    settings['dispatching'].enabled = false
    Returns the configuration of the specified simulation option.

Timetable​

Timetable filter(expression)​

👷👷🏾

Timetable filter(trainNumbers)​

👷👷🏾

MacroTrain getAt(expression)​

  • Signature: MacroTrain getAt[String expression], which is the same as timetable[expression]
  • Arguments:
    • expression train number, or expression that represents a predicate on MacroTrain.
  • Usage: 
    def train = timetable['1A23']
    Returns the MacroTrain with the specified train number or that satisfies the predicate, in the form of an expression. For a complete predicate list, see Train matchers.

MacroTrain find(expression)​

  • Signature: MacroTrain find(String expression)
  • Arguments:
    • expression expression that represents a predicate on MacroTrain.
  • Usage: 
    timetable.find('train number = 1A23 and operator = SW')
    Equivale a getAt(expression). Returns the MacroTrain of the Timetable that satisfies the predicate, in the form of an expression.

MacroTrain find(predicate)​

  • Signature: MacroTrain find(Closure predicate)
  • Arguments:
    • predicate closure that takes as argument a MacroTrain and returns true to select the train.
  • Usage: 
    timetable.find { it.trainNumber = '1A23' && it.operator.name = 'SW' }
    Returns the MacroTrain of the Timetable that satisfies the predicate, in the form of closure.

Iterable<MacroTrain> findAll()​

  • Signature: Iterable<MacroTrain> findAll()
  • Usage: 
    def trains = timetable.findAll()
    Returns all the MacroTrains that are part of the Timetable.

Iterable<MacroTrain> findAll(expression)​

  • Signature: Iterable<MacroTrain> findAll(String expression)
  • Arguments:
    • expression expression that represents a predicate on MacroTrain.
  • Usage: 
    def trains = timetable.findAll('operator = SW')
    Returns all the MacroTrains of the Timetable that satisfy the given predicate, in the form of an expression. For a complete predicate list, see Train matchers.

Iterable<MacroTrain> findAll(predicate)​

  • Signature: Iterable<MacroTrain> findAll(Closure predicate)
  • Arguments:
    • expression closure that takes as argument a MacroTrain and returns true to select the train.
  • Usage: 
    def trains = timetable.findAll { it.operator.name = 'SW' }
    Returns all the MacroTrains of the Timetable that satisfy the given predicate, in the form of closure.

Iterable<MacroTrain> findAll(expression, sort)​

  • Signature: Iterable<MacroTrain> findAll(String expression, String sort)
  • Arguments:
    • expression expression that represents a predicate on MacroTrain.
    • sort expression that represents the sorting order criterion. The form is attr [ desc ] [ , attr [ desc] ]* that is, an expression that represents a train attribute, optionally followed by the desc clause; more expressions can be concatenated, separated by a comma. Furthermore, for the attributes that cannot be defined, it is possible to use the or operator, for example, attr1 or attr2 [ desc ]. In this case, if the first attribute is not defined, the second one will be evaluated. For a complete predicate list, see Train matchers.
  • Usage: 
    def trains = timetable.findAll('operator = SW', 'departure time at LIVST')
    Returns all the MacroTrains of the Timetable that satisfy the given predicate, in the form of an expression. For a complete predicate list, see Train matchers. Furthermore, the MacroTrains are ordered by the specified criterion. The criterion can list more attributes; if one attribute is not defined, or has the same value for two trains, the next attribute is examined, and so on.

MacroTrain find(expression, sort)​

  • Signature: MacroTrain find(String expression, String sort)
  • Arguments:
    • expression expression that represents a predicate on MacroTrain.
    • sort expression that represents the sorting order criterion. The form is attr [ desc ] [ , attr [ desc] ]* that is, an expression that represents a train attribute, optionally followed by the desc clause; more expressions can be concatenated, separated by a comma. Furthermore, for the attributes that cannot be defined, it is possible to use the or operator, for example, attr1 or attr2 [ desc ]. In this case, if the first attribute is not defined, the second one will be evaluated. For a complete predicate list, see Train matchers.
  • Usage: 
    def train = timetable.find('calling at LIVST and station = GIDEAPK at next entry after LIVST and departure time > 12:00:00 at LIVST', 'departure time at LIVST')
    Returns the first MacroTrains of the Timetable that satisfies the given predicate, in the specified order. Corresponds to the first MacroTrain returned by the Timetable.findAll(expression, sort).

Map<?, MacroTrain> groupBy(keyExtractor)​

  • Signature: Map<?, MacroTrain> groupBy(Closure keyExtractor)
  • Arguments:
    • keyExtractor closure that takes as a parameter a MacroTrain and returns the grouping key.
  • Usage: 
    def trainsByOperatorName = timetable.groupBy { it.operator.name }
    Groups the trains of the Timetable based on the returned closure key.

int count()​

  • Signature: int count()
  • Usage: 
    def count = timetable.count()
    Returns the number of trains present in the timetable.

int timetable.count(expression)​

  • Signature: int count(String expression)
  • Arguments:
    • expression expression that represents a predicate on MacroTrain.
  • Usage: 
    def count = timetable.count('operator = SW')
    Returns the number of trains in the Timetable that satisfy the given predicate, in the form of an expression. For a complete predicate list, see Train matchers.

int count(predicate)​

  • Signature: int count(Closure predicate)
  • Arguments:
    • predicate closure that takes as argument a MacroTrain and returns true to count the train.
  • Usage: 
    def count = timetable.count { it.operator.name = 'SW' }
    Returns the number of trains present in the Timetable that satisfy the predicate.

each(closure)​

  • Signature: void each(Closure closure)
  • Arguments:
    • closure closure that takes as argument a MacroTrain.
  • Usage: 
    timetable.each { println it.operator.name }
    Calls the closure on each train of the timetable.

each(expression, closure)​

  • Signature: void each(String expression, Closure closure)
  • Arguments:
    • expression expression that represents a predicate on MacroTrain.
    • closure closure that takes as argument a MacroTrain.
  • Usage: 
    timetable.each('operator = SW') { println it.trainNumber }
    Calls the closure on each train of the timetable that satisfies the predicate.

each(filterExpression, sortExpression, Closure)​

  • Signature: void each(String filterExpression, String sortExpression, Closure closure)
  • Arguments:
    • filterExpression expression that represents a predicate on MacroTrain.
    • sortExpression expression that represents a sorting order criterion. The form is attr [ desc ] [ , attr [ desc] ]*, that is, an expression that represents a train attribute, optionally followed by the desc clause; more expressions can be concatenated, separated by a comma. For a complete predicate list, see Train matchers.
    • closure closure that takes as argument a MacroTrain.
  • Usage: 
    timetable.each('operator = SW and origin = LIVST', 'departure time from LIVST') { println it.trainNumber }
    Calls the closure on each train of the Timetable that satisfies the predicate, in the order established by the sorting order criterion.

SimulationTimetable​

Since SimulationTimetable extends Timetable, all the methods seen for the Timetable can be called on SimulationTimetable as well, except that they return a MacroTrainCourse instead of a MacroTrain, or a Iterable<MacroTrainCourse> instead of a Iterable<MacroTrain>.

MacroTrainCourse getAt(expression)​

  • Signature: MacroTrainCourse getAt[String expression], which is equivalent to timetable[expression]
  • Arguments:
    • expression train number, or the key of the train composed by train number@data, or an expression that represents a predicate on MacroTrainCourse.
  • Usage: 
    def course = timetable['1A23@2021-05-01']
    Returns the MacroTrainCourse with the specified train number or key. If there are more courses with the same number, any MacroTrainCourse will be returned.

SimulationActualTimetable​

Since SimulationActualTimetable extends SimulationTimetable, all the methods seen for the SimulationTimetable can be called on SimulationActualTimetable as well, except that they return MacroActualTrainCourse instead of a MacroTrainCourse, or a Iterable<MacroActualTrainCourse> instead of a Iterable<MacroTrainCourse>.

MacroTrain​

MacroTrainPathEntry getAt(entryIndex)​

  • Signature: MacroTrainPathEntry getAt(int entryIndex), which is the same as train[entryIndex]
  • Arguments:
    • entryIndex index of the path entry, 0-based.
  • Usage: 
    def entry = timetable['1A23@2021-05-01'][0]
    Returns the MacroTrainPathEntry with the specified index.

MacroTrainPathEntry getAt(expression)​

  • Signature: MacroTrainPathEntry getAt(String expression), which is the same as train[expression]
  • Arguments:
    • expression short code of the station, or expression that represents a predicate on MacroTrainPathEntry. Furthermore, for the trains that pass more times the same station (loop trains, or turnback along the path) and that consequently have more entries with the same station code, it is possible to specify which entry to return with the stationCode#index syntax, with index equal to 0 for the first found entry, 1 for the second, and so forth.
  • Usage: 
    def entry = timetable['1A23@2021-05-01'][0]
    Returns the first MacroTrainPathEntry that satisfies the expression. For a complete list, see Path entry matcher.

MacroTrainPathEntry find(expression)​

  • Signature: MacroTrainPathEntry find(String expression)
  • Arguments:
    • expression expression that represents a predicate on MacroTrainPathEntry
  • Usage: 
    def entry = timetable['1A23@2021-05-01']['origin']
    Returns the first MacroTrainPathEntry that satisfies the expression. For a complete list, see Path entry matcher.

Iterable<MacroTrainPathEntry> findAll(expression)​

  • Signature: Iterable<MacroTrainPathEntry> find(String expression)
  • Arguments:
    • expression expression that represents a predicate on MacroTrainPathEntry
  • Usage: 
    def turnbacks = timetable['1A23@2021-05-01'].findAll('turnback')
    Returns all the MacroTrainPathEntry that satisfies the expression. For a complete list, see Path entry matcher.

Object call(expression)​

  • Signature: Object call(String expression), which is the same as train(expression)
  • Arguments:
    • expression expression that represents a property of MacroTrain
  • Usage: 
    def origin = timetable['1A23@2021-05-01']('origin')
    Evaluates the expression in the MacronTrain context

MacroTrainCourse​

The available methods are the same as for MacroTrains

MacroActualTrainCourse​

The available methods are the same as for MacroTrainCourse

SimulationResults​

SimulationResults.Train getAt(expression)​

  • Signature: SimulationResults.Train getAt(String expression), which is the same as simulationResults[expression]
  • Arguments:
    • expression train number, or expression that represents a predicate on MacroTrainCourse.
  • Usage: 
    def trainResults = simulationResults['1A23@2021-05-01']
    Returns the results of the simulation of the first train with the specified number, or that satisfies the predicate, in the form of an expression. For a complete predicate list, see Train matchers.

SimulationResults.Train find(String expression)​

  • Signature: SimulationResults.Train find(String expression)
  • Arguments:
    • expression the expression that represents a predicate on MacroTrain
  • Usage: 
    def train = simulationResults.find('origin = LIVST and departure time = 11:03:00')
    Returns the results of the simulation of the first train that satisfies the predicate, in the form of an expression. For a complete predicate list, see Train matchers.

Iterable\u003CSimulationResults.Train\u003E findAll(String expression)​

  • Signature: Iterable<SimulationResults.Train> findAll(String expression)
  • Arguments:
    • expression expression that represents a predicate on MacroTrain
  • Usage: 
    simulationResults.findAll('origin = LIVST').each { ... }
    Returns the results of the simulation of trains that satisfy the predicate. For a complete predicate list, see Train matchers.

SimulationResults.Train​

SimulationResults.PathEntry getAt(index)​

  • Signature: SimulationResults.PathEntry getAt(int index), which is the same as trainResults[index]
  • Arguments:
    • index index of the entry
  • Usage: 
    def entryResults = trainResults[0]
    Returns the results of the simulation for the entry specified by the index

SimulationResults.PathEntry find(String expression)​

  • Signature: SimulationResults.PathEntry find(String expression)
  • Arguments:
    • expression expression that represents a predicate on MacronTrainPathEntry
  • Usage: 
    def origin = trainResults.find('origin')
    Returns the results of the simulation for the entry that satisfies the expression. For a complete predicate list, see Train matchers.

SimulationResults.PathEntry findFirst(String expression)​

  • Signature: SimulationResults.PathEntry findFirst(String expression)
  • Arguments:
    • expression expression that represents a predicate on MacronTrianPathEntry
  • Usage: 
    def origin = trainResults.findFirst('LIVST')
    Returns the simulation results of the first entry that satisfies the expression. For a complete predicate list, see Train matchers.

SimulationResults.PathEntry findLast(String expression)​

  • Signature: SimulationResults.PathEntry findLast(String expression)
  • Arguments:
    • expression expression that represents a predicate on MacronTrianPathEntry
  • Usage: 
    def origin = trainResults.findLast('LIVST')

Restituisce i risultati di simulazione dell'ultima entry che soddisfa l'espressione. For a complete predicate list, see Train matchers.

Iterable<SimulationResults.PathEntry> findAll(String expression)​

  • Signature: Iterable<SimulationResults.PathEntry> findAll(String expression)
  • Arguments:
    • expression expression that represents a predicate on MacronTrianPathEntry
  • Usage: 
    trainResults.findAll('stop').each { ... }

Returns all the results of the simulation for the entries that satisfy the expression. For a complete predicate list, see Train matchers.

DescriptiveStatistics​

Please see the Official documentation, here we will only consider the extension methods available in groovy scripts.

property nonNegativeMean​

  • Signature: double nonNegativeMeaan
  • Returns: the non negative mean of this statistics
  • Usage: 
    double val = descriptiveStatistics.nonNegativeMean

Returns the mean of all the values, assigning zero to the negative ones.

property punctualityIndex​

  • Signature: double punctualityIndex[int threshold], double punctualityIndex[duration threshold]
  • Arguments:
    • threshold delay threshold, in seconds or Duration.
  • Usage: 
    double val = descriptiveStatistics.punctualityIndex[5.minutes]

Returns the percentage of the values in the statistics that are smaller than the threshold

property percentile​

  • Signature: double percentile[double p]
  • Arguments:
    • p the requested percentile (scaled from 0 - 100)
  • Returns: an estimate for the p-th percentile of the stored data
  • Usage: 
    double val = descriptiveStatistics.percentile[95]

Returns the estimate of the p-th percentile.

ANTLR-based statistics​

trainStatistic​

  • Signature: Double Collection<MacroActualTrainCourse>.trainStatistic(String expr)
  • Arguments:
    • expr an ANTLR-based expression on trains, such as avg (delay at destination)
  • Returns: the result of the computation across the collection of trains.
  • Usage: 
    double val = trains.trainStatistic('avg (delay at destination)')

asTrainStatistic​

  • Signature: Function<Collection<MacroActualTrainCourse>, Double> String.asTrainStatistic()
  • Returns: a function to compute the statistic across a collection of trains.
  • Usage: 
    double fn = 'avg (delay at destination)'.asTrainStatistic()
    double val = fn(trains)

entryStatistic​

  • Signature: Double Collection<MacroTrainActualPathEntry>.entryStatistic(String expr)
  • Arguments:
    • expr an ANTLR-based expression on entries, such as avg (arrival delay)
  • Returns: the result of the computation across the collection of entries.
  • Usage: 
    double val = entries.entryStatistic('avg (arrival delay)')

asTrainStatistic​

  • Signature: Function<Collection<MacroTrainActualPathEntry>, Double> String.asEntryStatistic()
  • Returns: a function to compute the statistic across a collection of entries.
  • Usage: 
    double fn = 'avg (arrival delay)'.asEntryStatistic()
    double val = fn(entries)

Free functions​

Measure units​

m(originalUnit), m(originalUnit, hint)​

  • Signature: String m(String originalUnit), String m(String originalUnit, String hint)
  • Arguments:
    • originalUnit SI unit of measurement.
    • hint optional, disambiguates the units of measurement used for different magnitudes, for example, 'm' for lengths of progressive kilometers.
  • Usage: 
    m('m', 'kmpoint')  // -> km
    IS unit of measurement -> predefined unit of measurement

m(originalValue, originalUnit), m(originalValue, originalUnit, hint)​

  • Signature: String m(Number originalValue, String originalUnit), String m(Number originalValue, String originalUnit, String hint)
  • Arguments:
    • originalValue value expressed in the SI unit of measurement.
    • originalUnit SI unit of measurement.
    • hint optional, disambiguates the units of measurement used for different magnitudes, for example, 'm' for lengths of progressive kilometers.
  • Usage: 
    m(10, 'm/s')  // -> 36
    Converts a numeric value expressed in the SI unit of measurement to a textual value expressed in the predefined measurement system unit.

m(originalValue, originalUnit), m(originalValue, originalUnit, hint)​

  • Signature: String mm(Number originalValue, String originalUnit), String mm(Number originalValue, String originalUnit, String hint)
  • Arguments:
    • originalValue value expressed in the SI unit of measurement.
    • originalUnit SI unit of measurement.
    • hint optional, disambiguates the units of measurement used for different magnitudes, for example, 'm' for lengths of progressive kilometers.
  • Usage: 
    mm(10, 'm/s')  // -> 36 km/h
    Converts a numeric value expressed in the SI unit of measurement to a textual value expressed in the predefined measurement system unit, with the appropriate suffix.

v(text, originalUnit), m(originalValue, originalUnit, hint) 1.4.23+​

  • Signature: String m(String text, String originalUnit), String m(String text, String originalUnit, String hint)
  • Arguments:
    • text text that represents a value in the predefined measurement system unit.
    • originalUnit SI unit of measurement.
    • hint optional, disambiguates the units of measurement used for different magnitudes, for example, 'm' for lengths of progressive kilometers.
  • Usage: 
    v('36', 'm/s')  // -> 3106
    Converts a numeric value expressed in the SI unit of measurement to a textual value expressed in the predefined measurement system unit, in a numeric value in SI.

Time​

t(time)​

  • Signature: String t(Number time) v1.4.22+
  • Arguments:
    • time time expressed in seconds.
  • Usage: 
    t(12345)  // -> '03:25:45'
    t(123456)  // -> '34:17:36'

Converts a time expressed in seconds in a time with hhh:mm:ss format. The hour field can go over 23 if the time exceeds 24 hours. It's the inverse function of s(time).

s(time)​

  • Signature: String s(String time) v1.4.22+
  • Arguments:
    • time time in hhh:mm:ss format.
  • Usage: 
    t('03:25:45')  // -> 12345
    t('34:17:36')  // -> 123456

Converts a time in hhh:mm:ss format in a time expressed in seconds. It's the inverse function of t(time).

Bundled libraries​