logging

An logging library for Computer Craft

Usage

• Example:

  local logging = require("logging")
  logging:info("Message logged with logging library")
  

• Example with logger:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  logger:info("Message logged with logging library using a logger")
  

debug(...)Source

logs a message at the debug level

Parameters

1. ... string The arguments to log

info(...)Source

logs a message at the info level

Parameters

1. ... string The arguments to log

warn(...)Source

logs a message at the warn level

Parameters

1. ... string The arguments to log

error(...)Source

logs a message at the error level

Parameters

1. ... string The arguments to log

critical(...)Source

logs a message at the critical level

Parameters

1. ... string The arguments to log

log(level, ...)Source

logs a message

Parameters

1. level Level the level of the message
2. ... string The arguments to log

levelsSource

Hols the levels of the root logger

LevelSource

Holds information of an log level.

Usage

• Example:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  local level   = logging.Level.new {
      name            = "My Logger",
      textcolor       = colors.orange,
      backgroundcolor = colors.blue
  }
  
  logger:log(level, "This message will be logged with your custom level")
  

RecordSource

Holds information of the message that is to be logged.

FormatterSource

Used to format a Record instance to a string.

Usage

• Example:

  local logging   = require("logging")
  local formatter = logging.Formatter.new(
      "[%(time) %(name) %(levelname)] %(message)",
      "%Y-%m-%d %H:%M:%S"
  )
  
  local logger = logging.Logger.new {
      name      = shell.getRunningProgram(),
      formatter = formatter
  }
  
  logger:info("This message will be logged with your custom formatter")
  

LoggerSource

Holds all functions related to logging.

Usage

• Example:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  logger:info("This message will be logged")
  

TerminalHandlerSource

An Handler that writes to the terminal.

Usage

• Example:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  -- the logger will have a TerminalHandler by default
  -- but if you want to add another one you can do it like this:
      -- local terminalHandler = logging.TerminalHandler.new(logger.formatter)
      -- logger:addHandler(terminalHandler)
  
  logger:info("This message will be sent to the terminal")
  

FileHandlerSource

An FileHandler that writes to a file.

Usage

• Example:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  local file = fs.open("example.log", "a")
  -- replace "example.log" with the path of your log file
  local fileHandler = logging.FileHandler.new(logger.formatter, file)
  logger:addHandler(fileHandler)
  
  logger:info("This message will be sent to the file")
  
  file.close() -- don't forget to close the file after your script has finished
  

WebsocketHandlerSource

Will send the formatted record message to a websocket.

Usage

• Example:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  local websocket = http.websocket("ws://localhost:8080/")
  -- replace "localhost:8080" with the address of your websocket server
  local websocketHandler = logging.WebsocketHandler.new(logger.formatter, websocket)
  logger:addHandler(websocketHandler)
  
  logger:info("This message will be sent to the websocket")
  
  websocket.close() -- don't forget to close the websocket after your script has finished
  

ColordWebsocketHandlerSource

Will send the formatted record message with 24-bit/true Colors in ansi escape codes to a websocket.

Usage

• Example:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  local websocket = http.websocket("ws://localhost:8080/")
  -- replace "localhost:8080" with the address of your websocket server
  local colordWebsocketHandler = logging.ColordWebsocketHandler.new(logger.formatter, websocket)
  logger:addHandler(colordWebsocketHandler)
  
  logger:info("This message will be sent to the websocket with its color in ansi escape codes")
  
  websocket.close() -- don't forget to close the websocket after your script has finished
  

RawWebsocketHandlerSource

Will send the record with the used formatter to a websocket.

Usage

• Example:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  local websocket = http.websocket("ws://localhost:8080/")
  -- replace "localhost:8080" with the address of your websocket server
  local rawWebsocketHandler = logging.RawWebsocketHandler.new(logger.formatter, websocket)
  logger:addHandler(rawWebsocketHandler)
  
  logger:info("This message will be sent to the websocket in raw format")
  
  websocket.close() -- don't forget to close the websocket after your script has finished
  

RednetHandlerSource

broadcast the formatted record message with rednet.

Usage

• Example:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  rednet.open("right") -- replace "right" with the side your modem is connected to
  local rednetHandler = logging.RednetHandler.new(logger.formatter)
  logger:addHandler(rednetHandler)
  
  logger:info("This message will be send over rednet")
  

RednetRecieverSource

An Reciever that recives messages from Rednet.

Usage

• Example limited to a single channel and no background process:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  local rednetReciever = logging.RednetReciever.new()
  
  while true do
      rednetReciever:receive(logger)
  end
  

• Example with coroutine's:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  local rednetReciever = logging.RednetReciever.new()
  logger:addReciever(rednetReciever)
  
  -- the main loop can be modified to do all kinds of stuff.
  local main_loop = coroutine.create(function()
      while true do
          logger:info("im very useful")
          sleep(5)
      end
  end)
  
  local coroutines = logger:getRecieverCoroutines()
  table.insert(coroutines, main_loop)
  
  while true do
      local tEventData = table.pack(os.pullEventRaw())
  
      for _, c in pairs(coroutines) do
          coroutine.resume(c, table.unpack(tEventData))
      end
  end
  

Types

ColordWebsocketHandler

Will send the formatted record message with 24-bit/true Colors in ansi escape codes to a websocket.

Usage

• Example:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  local websocket = http.websocket("ws://localhost:8080/")
  -- replace "localhost:8080" with the address of your websocket server
  local colordWebsocketHandler = logging.ColordWebsocketHandler.new(logger.formatter, websocket)
  logger:addHandler(colordWebsocketHandler)
  
  logger:info("This message will be sent to the websocket with its color in ansi escape codes")
  
  websocket.close() -- don't forget to close the websocket after your script has finished
  

ColordWebsocketHandler.new(formatter, websocket)Source

Create's a new ColordWebsocketHandler instance.

Parameters

1. formatter Formatter The formatter to use
2. websocket Websocket The websocket to send the message to.

Returns

1. ColordWebsocketHandler instance

ColordWebsocketHandler.handle(record)Source

Handles a record.

Parameters

1. record Record The record to handle.

FileHandler

An FileHandler that writes to a file.

Usage

• Example:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  local file = fs.open("example.log", "a")
  -- replace "example.log" with the path of your log file
  local fileHandler = logging.FileHandler.new(logger.formatter, file)
  logger:addHandler(fileHandler)
  
  logger:info("This message will be sent to the file")
  
  file.close() -- don't forget to close the file after your script has finished
  

FileHandler.new(formatter, file)Source

Create's a new FileHandler instance.

Parameters

1. formatter Formatter The formatter to use.
2. file table The file to write to. (use fs.open to open a file)

Returns

1. FileHandler instance

FileHandler.handle(record)Source

Handles a record.

Parameters

1. record Record The record to handle.

Formatter

Used to format a Record instance to a string.

Usage

• Example:

  local logging   = require("logging")
  local formatter = logging.Formatter.new(
      "[%(time) %(name) %(levelname)] %(message)",
      "%Y-%m-%d %H:%M:%S"
  )
  
  local logger = logging.Logger.new {
      name      = shell.getRunningProgram(),
      formatter = formatter
  }
  
  logger:info("This message will be logged with your custom formatter")
  

Formatter.fmtSource

The format string used to format the record. defaults to [%(time) %(name) %(levelname)] %(message)

• placeholders:
  • %(name) Name of the logger
  • %(levelname) Name of the Log level
  • %(message) The Message to log
  • %(time) The real live time formatted by datefmt
  • %(localtime) The minecraft time formatted by datefmt
  • %(day) The minecraft day (os.day())
  • %(computerid) The ID of the computer (os.getComputerID())
  • %(computerlabel) The label of the computer (os.getComputerLabel())
  • %(thread) The memory address of the current thread

Formatter.datefmt = "%H:%M:%S"Source

The date format, it works like the format in os.date()

Formatter.new(fmt, datefmt)Source

Create's a new Formatter instance.

Parameters

1. fmt string The format string
2. datefmt string The format string for the date

Returns

1. Formatter instance

Formatter.format(record)Source

Formats a Record instance to a string.

Parameters

1. record Record The record to format

Returns

1. string The formatted string

Level

Holds information of an log level.

Usage

• Example:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  local level   = logging.Level.new {
      name            = "My Logger",
      textcolor       = colors.orange,
      backgroundcolor = colors.blue
  }
  
  logger:log(level, "This message will be logged with your custom level")
  

Level.level = 0Source

Holds the log level.

Level.textcolorSource

Holds the textcolor of the level defaults to colors.white

Level.backgroundcolorSource

Holds the backgroundcolor of the level defaults to colors.black

Level.new(name, level, textcolor, backgroundcolor)Source

Create's a new Level instance.

Parameters

1. name string The name of the level
2. level number The level weight (optional, defaults to 0)
3. textcolor number The textcolor of the level (optional, defaults to colors.white)
4. backgroundcolor number The backgroundcolor of the level (optional, defaults to colors.black)

Returns

1. Level instance

Logger

Holds all functions related to logging.

Usage

• Example:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  logger:info("This message will be logged")
  

Logger.level = 0Source

The level that the logger will log at.

Logger.recieversSource

Holds all recievers

Logger.new(name, level, formatter)Source

Create's a new Logger instance.

Parameters

1. name string The logger name.
2. level number The level weight.
3. formatter Formatter The formatter to use.

Returns

1. Logger instance

Logger.addHandler(handler)Source

Adds a new handler to the logger.

Parameters

1. handler table The handler to add.

Logger.removeHandler(handler)Source

Removes the given handler from the logger. dont forget to close files, websockets, etc.

Parameters

1. handler table The handler to remove.

Logger.registerLevel(level)Source

This function adds a level to the internal levels list of the logger. currently this function is useless since you dont need to add levels for them to work.

Parameters

1. level Level The level.

Logger:removeDefaultHandler()Source

Removes the default TerminalHandler from the logger.

Logger.handel(record)Source

Handels a record.

Parameters

1. record Record The record to handle.

Logger.log(level, ...)Source

logs a message

Parameters

1. level Level the level of the message
2. ... string The arguments to log

Logger.addReciever(reciever)Source

add a reciever to the logger

Parameters

1. reciever table the reciever to add

Logger.getRecieverCoroutines()Source

Returns coroutines for all recievers that recive messages.

Returns

1. table coroutines

Usage

• Example:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  -- in this example we have a reciever that recives messages from rednet
  local rednetReciever = logging.RednetReciever.new()
  logger:addReciever(rednetReciever)
  
  -- the main loop can be modified to do all kinds of stuff.
  local main_loop = coroutine.create(function()
      while true do
          logger:info("im very useful")
          sleep(5)
      end
  end)
  
  local coroutines = logger:getRecieverCoroutines()
  table.insert(coroutines, main_loop)
  
  while true do
      local tEventData = table.pack(os.pullEventRaw())
  
      for _, c in pairs(coroutines) do
          coroutine.resume(c, table.unpack(tEventData))
      end
  end
  

Logger.debug(...)Source

logs a message at the debug level

Parameters

1. ... string The arguments to log

Logger.info(...)Source

logs a message at the info level

Parameters

1. ... string The arguments to log

Logger.warn(...)Source

logs a message at the warn level

Parameters

1. ... string The arguments to log

Logger.error(...)Source

logs a message at the error level

Parameters

1. ... string The arguments to log

Logger.critical(...)Source

logs a message at the critical level

Parameters

1. ... string The arguments to log

RawWebsocketHandler

Will send the record with the used formatter to a websocket.

Usage

• Example:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  local websocket = http.websocket("ws://localhost:8080/")
  -- replace "localhost:8080" with the address of your websocket server
  local rawWebsocketHandler = logging.RawWebsocketHandler.new(logger.formatter, websocket)
  logger:addHandler(rawWebsocketHandler)
  
  logger:info("This message will be sent to the websocket in raw format")
  
  websocket.close() -- don't forget to close the websocket after your script has finished
  

RawWebsocketHandler.new(formatter, websocket)Source

Create's a new RawWebsocketHandler instance.

Parameters

1. formatter Formatter The formatter to use
2. websocket Websocket The websocket to send the message to.

Returns

1. RawWebsocketHandler instance

RawWebsocketHandler.handle(record)Source

Handles a record.

Parameters

1. record Record The record to handle.

Record

Holds information of the message that is to be logged.

Record.new(level, message, name)Source

Create's a new Record instance.

Parameters

1. level Level The level of the record
2. message number The message to be logged
3. name number The name of the used logger

Returns

1. Record instance

RednetHandler

broadcast the formatted record message with rednet.

Usage

• Example:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  rednet.open("right") -- replace "right" with the side your modem is connected to
  local rednetHandler = logging.RednetHandler.new(logger.formatter)
  logger:addHandler(rednetHandler)
  
  logger:info("This message will be send over rednet")
  

RednetHandler.channelSource

Holds the channel where the message is to be send defaults to rednet.CHANNEL_BROADCAST

RednetHandler.protocol = "logging"Source

Holds the rednet protocol that should be used

RednetHandler.new(formatter, channel, protocol)Source

Create's a new RednetHandler instance.

Parameters

1. formatter Formatter The formatter to use
2. channel number or the computer ID to send the message to (optional, defaults to rednet.CHANNEL_BROADCAST)
3. protocol string The protocol to use (optional, defaults to "logging")

Returns

1. RednetHandler instance

RednetHandler.handle(record)Source

Handles a record.

Parameters

1. record Record The record to handle.

RednetReciever

An Reciever that recives messages from Rednet.

Usage

• Example limited to a single channel and no background process:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  local rednetReciever = logging.RednetReciever.new()
  
  while true do
      rednetReciever:receive(logger)
  end
  

• Example with coroutine's:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  local rednetReciever = logging.RednetReciever.new()
  logger:addReciever(rednetReciever)
  
  -- the main loop can be modified to do all kinds of stuff.
  local main_loop = coroutine.create(function()
      while true do
          logger:info("im very useful")
          sleep(5)
      end
  end)
  
  local coroutines = logger:getRecieverCoroutines()
  table.insert(coroutines, main_loop)
  
  while true do
      local tEventData = table.pack(os.pullEventRaw())
  
      for _, c in pairs(coroutines) do
          coroutine.resume(c, table.unpack(tEventData))
      end
  end
  

RednetReciever.protocol = "logging"Source

Holds the rednet protocol that should be used

RednetReciever.new(protocol)Source

Create's a new RednetReciever instance.

Parameters

1. protocol string The protocol to listen to. (optional, defaults to "logging")

Returns

1. RednetReciever instance

RednetReciever.receive(logger)Source

Recives message from rednet.

Parameters

1. logger Logger The logger to use.

TerminalHandler

An Handler that writes to the terminal.

Usage

• Example:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  -- the logger will have a TerminalHandler by default
  -- but if you want to add another one you can do it like this:
      -- local terminalHandler = logging.TerminalHandler.new(logger.formatter)
      -- logger:addHandler(terminalHandler)
  
  logger:info("This message will be sent to the terminal")
  

TerminalHandler.new(formatter)Source

Create's a new TerminalHandler instance.

Parameters

1. formatter Formatter The formatter to use.

Returns

1. TerminalHandler instance

TerminalHandler.handle(record)Source

Handles a record.

Parameters

1. record Record The record to handle.

WebsocketHandler

Will send the formatted record message to a websocket.

Usage

• Example:

  local logging = require("logging")
  local logger  = logging.Logger.new(shell.getRunningProgram())
  
  local websocket = http.websocket("ws://localhost:8080/")
  -- replace "localhost:8080" with the address of your websocket server
  local websocketHandler = logging.WebsocketHandler.new(logger.formatter, websocket)
  logger:addHandler(websocketHandler)
  
  logger:info("This message will be sent to the websocket")
  
  websocket.close() -- don't forget to close the websocket after your script has finished
  

WebsocketHandler.new(formatter, websocket)Source

Create's a new WebsocketHandler instance.

Parameters

1. formatter Formatter The formatter to use
2. websocket Websocket The websocket to send the message to.

Returns

1. WebsocketHandler instance

WebsocketHandler.handle(record)Source

Handles a record.

Parameters

1. record Record The record to handle.