Skip to content

Latest commit

 

History

History
329 lines (248 loc) · 11.9 KB

README_Logger.md

File metadata and controls

329 lines (248 loc) · 11.9 KB

FS22Log LUA Logger Class for FS22

Class Initialization

yourLogger = FS22Log:new(callerName, debugMode, filterOut, filterExclusive)
  • callerName : Name of your mod, or logging section
  • debugMode : one of the DEBUG_MODE below, .WARNINGS suggested for production mode
  • filterOut : names to filter OUT of printed output
  • filterExclusive : names to ONLY print, takes precedence

Class Functions

Print text to the log

yourLogger:print(text, logLevel, filter)
  • text : Text to print
  • logLevel : Log level from LOG_LEVEL below, default is .DEVEL
  • filter : Text string for [filterOut] and [filterExclusive], default is --

Print variable contents to the log - recursively prints tables

yourLogger.printVariable(output, logLevel, filter, depthLimit, prefix, searchTerms)
yourLogger.printVariableIsTable(output, logLevel, filter, depthLimit, prefix, searchTerms)

The IsTable variant will auto-upgrade the logLevel to WARNING when the variable is not a table, and ERROR if the variable is undefined or nil

yourLogger.printVariableOnce(output, logLevel, filter, depthLimit, prefix, searchTerms)

The Once variant will print the variable only once, based on the name given to filter

yourLogger.printVariableIfChanged(output, logLevel, filter, depthLimit, prefix, searchTerms)

The IfChanged variant will print only if the contents of the variable have changed since last time it was called, based on the name given to filter. Note that this is not deep-recursive, only the first level of the table is looked at for changes.

  • output : Variable to print
  • logLevel : Log level from LOG_LEVEL below, default is .DEVEL
  • filter : Text string for [filterOut] and [filterExclusive], default is "--"
  • depthLimit : How deep to traverse tables, default is 2 levels
    • (1 based argument - e.g 2 == show 2 levels total)
  • prefix : Text string for name of variable, defaults to [filter]
  • searchTerms : Terms to search - options:
    • "string"
      • Search for "string" in KEYS only
    • { "string", SEARCH.TYPE }
      • Search for "string" using SEARCH.TYPE fromm below.
    • { {"table", "of", "strings"}, SEARCH.TYPE }
      • Search for all strings in table using SEARCH.TYPE from below.

Top-Level Functions

Print function call arguments

Intercept function calls to print the arguments it's being called with. This method call is similar to how Utils.prependedFunction() works.

Note that if you pass an invalid function, when in debug mode, a valid function with an error message will be returned

originFunction = FS22LogFunction(logLevel, originMod, originFunctionName, originFunction)
  • logLevel : Log level from LOG_LEVEL below, has no function is set to .WARNINGS or .ERRORS or .NONE
  • originMod : Name of your mod for printing purposes
  • originFunctionName : Name of the original function (string)
  • originFunction : Original function (literal)

Run Levels

It is highly recommended that your store this value locally in your mod, and pass it to the constructor / calls to FS22LogFunction() so you can quickly toggle the level for released mods without having to remove all your logging calls.

  • FS22Log.DEBUG_MODE.NONE - Print nothing, ever
  • FS22Log.DEBUG_MODE.ERRORS - Print errors
  • FS22Log.DEBUG_MODE.WARNINGS - Print warnings, suggested or "production" mode
  • FS22Log.DEBUG_MODE.INFO - Print information
  • FS22Log.DEBUG_MODE.DEVEL - Print Development information
  • FS22Log.DEBUG_MODE.VERBOSE - Print Verbose Development information

Log Levels

These correspond to the above run levels. If the error level matches, or is of higher precedence than the current run level, the log message is printed.

  • FS22Log.LOG_LEVEL.ERROR - Errors only
  • FS22Log.LOG_LEVEL.WARNING - Warnings, suggested for "production" mode
  • FS22Log.LOG_LEVEL.INFO - Information level
  • FS22Log.LOG_LEVEL.DEVEL - Development information
  • FS22Log.LOG_LEVEL.VERBOSE - Verbose Development information

Search Types

Types for the search feature

  • FS22Log.SEARCH.KEYS - Search keys only
  • FS22Log.SEARCH.VALUES - Search values only
  • FS22Log.SEARCH.BOTH - Search both keys and values
  • FS22Log.SEARCH.KEYS_AND_VALUES - Search both keys and values

Examples

Some examples of the enhanced logger in action

Logger Class

These are from the logger class

Class initiated

local myLoggerVanilla = FS22Log:new(
    "demoSample",
    FS22Log.DEBUG_MODE.VERBOSE
)

Simple text

myLoggerVanilla:print("Test String", nil, "test_string")
~~ demoSample:DEVEL:test_string | Test String

Simple Variable

local testVarString = "Hello There."

myLoggerVanilla:printVariable(undefinedVar, nil, "undefined_variable")
myLoggerVanilla:printVariable(testVarString, nil, "test_string_variable")
~~ demoSample:DEVEL:undefined_variable | undefined_variable :: nil
~~ demoSample:DEVEL:test_string_variable | test_string_variable :: Hello There.

Simple Variable - IsTable

local testVarString = "Hello There."

myLoggerVanilla:printVariableIsTable(undefinedVar, nil, "undefined_variable")
myLoggerVanilla:printVariableIsTable(testVarString, nil, "test_string_variable")

Note that the logLevel has been automatically upgraded

~~ demoSample:ERROR:undefined_variable_is_table | undefined_variable_is_table :: nil
~~ demoSample:WARNING:test_string_variable_is_table | test_string_variable_is_table :: Hello There.

Table Output

myLoggerVanilla:printVariable(DemoSampleData, nil, "sample_data", 3)
~~ demoSample:DEVEL:sample_data | sample_data.1 :: table: 00B31338
~~ demoSample:DEVEL:sample_data | _sample_data.1.type    :: donut
~~ demoSample:DEVEL:sample_data | _sample_data.1.name    :: Cake
~~ demoSample:DEVEL:sample_data | _sample_data.1.id      :: 1
~~ demoSample:DEVEL:sample_data | _sample_data.1.batters :: table: 00B31130
~~ demoSample:DEVEL:sample_data | __sample_data.1.batters.batter :: table: 00B31518
~~ demoSample:DEVEL:sample_data | _sample_data.1.topping :: table: 00B31248
~~ demoSample:DEVEL:sample_data | __sample_data.1.topping.1 :: table: 00B31158

...

~~ demoSample:DEVEL:sample_data | __sample_data.3.topping.3 :: table: 00B31A00
~~ demoSample:DEVEL:sample_data | __sample_data.3.topping.4 :: table: 00B31BE0

Searching Tables Output

myLoggerVanilla:printVariable(DemoSampleData, nil, "sample_data_search_fail", 4, nil, {"badArgument!"})
myLoggerVanilla:printVariable(DemoSampleData, nil, "sample_data_search", 4, nil, {{"batter", "Chocolate"}, FS22Log.SEARCH.VALUES})
~~ demoSample:DEVEL:sample_data_search_fail | ERROR: Incorrect search terms, see logger documentation
~~ demoSample:DEVEL:sample_data_search | Searching for: {batter,Chocolate} [VALUES]
~~ demoSample:DEVEL:sample_data_search | ___sample_data_search.1.topping.5.type :: Chocolate with Sprinkles
~~ demoSample:DEVEL:sample_data_search | ___sample_data_search.1.topping.6.type :: Chocolate
~~ demoSample:DEVEL:sample_data_search | ___sample_data_search.2.topping.4.type :: Chocolate
~~ demoSample:DEVEL:sample_data_search | ___sample_data_search.3.topping.3.type :: Chocolate

Function Argument Printer

function AddTest(a, b)
    print("Original AddTest called: " .. tostring(a) .. " + " .. tostring(b) .. " = " .. tostring(a+b))
end

function SubTest(a, b)
    print("Original SubTest called: " .. tostring(a) .. " - " .. tostring(b) .. " = " .. tostring(a-b))
end

InvalidFunction = FS22LogFunction(FS22Log.DEBUG_MODE.DEVEL, "demoSample", "InvalidFunction", InvalidFunction)
AddTest         = FS22LogFunction(FS22Log.DEBUG_MODE.DEVEL, "demoSample", "AddTest", AddTest)

-- Note, WARNINGS is below the printable threshold, so this call produces no additional output.
SubTest         = FS22LogFunction(FS22Log.DEBUG_MODE.WARNINGS, "demoSample", "SubTest", SubTest)

InvalidFunction()
AddTest(1, 2)
SubTest(5, 1)
~~ demoSample:InvalidFunction | Original Function Not Found
~~ demoSample:InvalidFunction | Invalid function call (no original)

~~ demoSample:AddTest | Called With: [1], [2]
Original AddTest called: 1 + 2 = 3

Original SubTest called: 5 - 1 = 4

Dynamic run level

This is a very simplified example of using a dynamic run level to show log text while developing but not displaying them in released code, all while not having to remove the log functions from your code.

local myDebug = FS22Log.DEBUG_MODE.VERBOSE -- Development
--local myDebug = FS22Log.DEBUG_MODE.WARNINGS -- Release

local myLoggerVanilla = FS22Log:new(
    "demoSample",
    myDebug
)

-- These will show for development, but not in release mode
myLoggerVanilla:printVariable(testVarString, FS22Log.LOG_LEVEL.INFO, "test_string_variable")

AddTest = FS22LogFunction(myDebug, "demoSample", "AddTest", AddTest)

VSCode Snippets

This is a set of VSCode snippets to ease the use of the logger even more.

  "Logger: variable": {
    "prefix": [":printVariable"],
    "body": [
      ":printVariable(${1:inputTable}, FS22Log.LOG_LEVEL.${2|VERBOSE,DEVEL,INFO,WARNING,ERROR|}, \"${3:filterString}\", ${4|nil,1,2,3,4|}, nil, ${5|nil,{\"searchTable\"},\"searchText\"|})"
    ],
    "description": "Print a variable"
  },
  "Logger: variableIsTable": {
    "prefix": [":printVariableIsTable"],
    "body": [
      ":printVariableIsTable(${1:inputTable}, FS22Log.LOG_LEVEL.${2|VERBOSE,DEVEL,INFO,WARNING,ERROR|}, \"${3:filterString}\", ${4|nil,1,2,3,4|}, nil, ${5|nil,{\"searchTable\"},\"searchText\"|})"
    ],
    "description": "Print a variable"
  },
  "Logger: variableOnce": {
    "prefix": [":printVariableOnce"],
    "body": [
      ":printVariableOnce(${1:inputTable}, FS22Log.LOG_LEVEL.${2|VERBOSE,DEVEL,INFO,WARNING,ERROR|}, \"${3:filterString}\", ${4|nil,1,2,3,4|}, nil, ${5|nil,{\"searchTable\"},\"searchText\"|})"
    ],
    "description": "Print a variable (only once)"
  },
  "Logger: variableIfChanged": {
    "prefix": [":printVariableIfChanged"],
    "body": [
      ":printVariableIfChanged(${1:inputTable}, FS22Log.LOG_LEVEL.${2|VERBOSE,DEVEL,INFO,WARNING,ERROR|}, \"${3:filterString}\", ${4|nil,1,2,3,4|}, nil, ${5|nil,{\"searchTable\"},\"searchText\"|})"
    ],
    "description": "Print a variable (if changed)"
  },
  "Logger: string": {
    "prefix": [":print"],
    "body": [
      ":print(\"${1:text}\", FS22Log.LOG_LEVEL.${2|VERBOSE,DEVEL,INFO,WARNING,ERROR|}, \"${3:filterString}\")"
    ],
    "description": "Print a variable"
  }

Distribution & Licensing Terms

(c)JTSage Modding & FSG Modding. You may reuse or alter this code to your needs as necessary with no prior permission. No warranty implied or otherwise.