Module utils

Provides common functions used in different code files.

Info:

  • Copyright: 2022 Patrick Lang
  • Author: Patrick Lang

Functions

enableDebugLogging () Enables the logging of debug messages.
disableDebugLogging () Disables the logging of debug messages.
logDebug (source, message) Writes a debug log message into the X-Plane log file.
logInfo (source, message) Writes an information log message into the X-Plane log file.
logError (source, message) Writes an error log message into the X-Plane log file.
verifyType (valueName, value, expectedType) Verifies that a value is of the expected type.
verifyNotNil (valueName, value) Verifies that a value is not nil.
getTime () Gets the current time.
fileExists (filePath) Checks whether a file exists
arrayContains (array, value) Checks whether an array contains a specific value
checkArrayValuesAll (array, verifyFunction) Checks whether all items of an array meet a given condition.
checkArrayValuesAny (array, verifyFunction) Checks whether any item of an array meets a given condition.
readDataRefInteger (dataRefName, defaultValue) Reads an integer DataRef from X-Plane.
readDataRefFloat (dataRefName, defaultValue) Reads a float DataRef from X-Plane.
checkArrayValuesAllInteger (dataRefName, startIndex, count, verifyFunction) Checks whether the items within a range of an integer DataRef array meet a given condition.
checkArrayValuesAnyInteger (dataRefName, startIndex, count, verifyFunction) Checks whether any item within a range of an integer DataRef array meets a given condition.
checkArrayValuesAllFloat (dataRefName, startIndex, count, verifyFunction) Checks whether the items within a range of a float DataRef array meet a given condition.
checkArrayValuesAnyFloat (dataRefName, startIndex, count, verifyFunction) Checks whether any item within a range of a float DataRef array meets a given condition.


Functions

enableDebugLogging ()
Enables the logging of debug messages.
disableDebugLogging ()
Disables the logging of debug messages.
logDebug (source, message)
Writes a debug log message into the X-Plane log file. The message is only written if debug logging is enabled.

Parameters:

  • source string The source of the log message.
  • message string The log message.
logInfo (source, message)
Writes an information log message into the X-Plane log file.

Parameters:

  • source string The source of the log message.
  • message string The log message.
logError (source, message)
Writes an error log message into the X-Plane log file.

Parameters:

  • source string The source of the log message.
  • message string The log message.
verifyType (valueName, value, expectedType)
Verifies that a value is of the expected type. An error is thrown if the type of the value does not match the expected type.

Parameters:

  • valueName string The name of the value. Used for the error message.
  • value The value to check.
  • expectedType string The expected type of the value.
verifyNotNil (valueName, value)
Verifies that a value is not nil.

Parameters:

  • valueName string The name of the value. Used for the error message.
  • value The value to check.
getTime ()
Gets the current time. The function uses the gettime() function of LuaSocket, which provides the current time with milliseconds resolution.

Returns:

    number The current time.
fileExists (filePath)
Checks whether a file exists

Parameters:

  • filePath string The path to the file

Returns:

    bool True if the file exists and can be read, otherwise false.
arrayContains (array, value)
Checks whether an array contains a specific value

Parameters:

  • array tab The array
  • value The value to check

Returns:

    bool True if the array contains the value, otherwise false.
checkArrayValuesAll (array, verifyFunction)
Checks whether all items of an array meet a given condition.

Parameters:

  • array tab The array.
  • verifyFunction func The function which will receive each item of the array and returns whether the item meets its condition (true or false).

Returns:

    bool True if the verification function returns true for all items, otherwise false.

Usage:

  • utils.checkArrayValuesAll({1, 2, 3}, function(v) return v < 4 end) -- returns true
  • utils.checkArrayValuesAll({1, 2, 3}, function(v) return v < 3 end) -- returns false
checkArrayValuesAny (array, verifyFunction)
Checks whether any item of an array meets a given condition.

Parameters:

  • array tab The array.
  • verifyFunction func The function which will receive each item of the array and returns whether the item meets its condition (true or false)..

Returns:

    bool True if the verification function returns true for any item, otherwise false.

Usage:

  • utils.checkArrayValuesAny({1, 2, 3}, function(v) return v < 2 end) -- returns true
  • utils.checkArrayValuesAny({1, 2, 3}, function(v) return v < 1 end) -- returns false
readDataRefInteger (dataRefName, defaultValue)
Reads an integer DataRef from X-Plane. Reading DataRef values is a relatively slow operation and should only be done if necessary.

Parameters:

  • dataRefName string The name of the DataRef.
  • defaultValue optional number The default value to return if the DataRef was not found.

Returns:

    optional number The value of the DataRef or the default value, if the DataRef was not found.
readDataRefFloat (dataRefName, defaultValue)
Reads a float DataRef from X-Plane. Reading DataRef values is a relatively slow operation and should only be done if necessary.

Parameters:

  • dataRefName string The name of the DataRef.
  • defaultValue optional number The default value to return if the DataRef was not found.

Returns:

    optional number The value of the DataRef or the default value, if the DataRef was not found.
checkArrayValuesAllInteger (dataRefName, startIndex, count, verifyFunction)
Checks whether the items within a range of an integer DataRef array meet a given condition. Reading DataRef values is a relatively slow operation and should only be done if necessary.

Parameters:

  • dataRefName string The name of the DataRef.
  • startIndex number The start index of the range to check.
  • count number The count of items to check.
  • verifyFunction func The function which will receive each item and returns whether the item meets its condition (true or false)..

Returns:

    bool True if the verification function returns true for all items within the range, otherwise false. If the DataRef was not found, then false is returned.

Usage:

    utils.checkArrayValuesAllInteger("sim/flightmodel/engine/ENGN_running", 0, 2, function(v) return v == 1 end) -- Checks if engines 1 and 2 are running
checkArrayValuesAnyInteger (dataRefName, startIndex, count, verifyFunction)
Checks whether any item within a range of an integer DataRef array meets a given condition. Reading DataRef values is a relatively slow operation and should only be done if necessary.

Parameters:

  • dataRefName string The name of the DataRef.
  • startIndex number The start index of the range to check.
  • count number The count of items to check.
  • verifyFunction func The function which will receive each item and returns whether the item meets its condition (true or false)..

Returns:

    bool True if the verification function returns true for any item within the range, otherwise false. If the DataRef was not found, then false is returned.

Usage:

    utils.checkArrayValuesAnyInteger("sim/flightmodel/engine/ENGN_running", 0, 2, function(v) return v == 1 end) -- Checks if any engine is running
checkArrayValuesAllFloat (dataRefName, startIndex, count, verifyFunction)
Checks whether the items within a range of a float DataRef array meet a given condition. Reading DataRef values is a relatively slow operation and should only be done if necessary.

Parameters:

  • dataRefName string The name of the DataRef.
  • startIndex number The start index of the range to check.
  • count number The count of items to check.
  • verifyFunction func The function which will receive each item and returns whether the item meets its condition (true or false)..

Returns:

    bool True if the verification function returns true for all items within the range, otherwise false. If the DataRef was not found, then false is returned.

Usage:

    utils.checkArayValuesAllFloat("laminar/B738/flap_indicator", 0, 2, function(v) return v == 0 end) -- Checks if all flaps are up
checkArrayValuesAnyFloat (dataRefName, startIndex, count, verifyFunction)
Checks whether any item within a range of a float DataRef array meets a given condition. Reading DataRef values is a relatively slow operation and should only be done if necessary.

Parameters:

  • dataRefName string The name of the DataRef.
  • startIndex number The start index of the range to check.
  • count number The count of items to check.
  • verifyFunction func The function which will receive each item and returns whether the item meets its condition (true or false)..

Returns:

    bool True if the verification function returns true for any item within the range, otherwise false. If the DataRef was not found, then false is returned.

Usage:

    utils.checkArrayValuesAnyFloat("sim/cockpit2/engine/actuators/throttle_ratio", 0, 2, function(v) return v >= 0.5 end) -- Checks if any thrust lever is advanced 50% or more
generated by LDoc 1.4.6 Last updated 2022-05-28 12:58:52