Added functions and improved module code

Added GetAll, IsBlocked, SetMaximumQueueSize and GetMaximumQueueSize
Added API reference
Added Lua extension module that adds a Lua hook
Added Azure Pipelines config
Bumped minor version

azure-pipelines.yml

@@ -0,0 +1,142 @@
+variables:
+  MODULE_NAME: spew
+  DEPENDENCIES: $(System.DefaultWorkingDirectory)/dependencies
+  GARRYSMOD_COMMON: $(System.DefaultWorkingDirectory)/dependencies/garrysmod_common
+  GARRYSMOD_COMMON_BRANCH: master
+  GARRYSMOD_COMMON_REPOSITORY: https://github.com/danielga/garrysmod_common.git
+  PROJECT_GENERATOR_VERSION: 2
+  REPOSITORY_DIR: $(System.DefaultWorkingDirectory)
+  DISABLE_X86_64_BUILD: true
+trigger:
+  tags:
+    include:
+    - '*'
+jobs:
+- job: windows
+  displayName: Windows
+  pool:
+    name: Azure Pipelines
+    vmImage: windows-2019
+  timeoutInMinutes: 10
+  variables:
+    BOOTSTRAP_URL: https://raw.githubusercontent.com/danielga/garrysmod_common/master/build/bootstrap.ps1
+    BUILD_SCRIPT: $(System.DefaultWorkingDirectory)/dependencies/garrysmod_common/build/build.ps1
+    COMPILER_PLATFORM: vs2019
+    PROJECT_OS: windows
+    PREMAKE5: $(System.DefaultWorkingDirectory)/dependencies/windows/premake-core/premake5.exe
+    PREMAKE5_URL: https://github.com/premake/premake-core/releases/download/v5.0.0-alpha15/premake-5.0.0-alpha15-windows.zip
+  steps:
+  - powershell: 'Invoke-Expression ((New-Object System.Net.WebClient).DownloadString("$env:BOOTSTRAP_URL"))'
+    displayName: Bootstrap
+  - powershell: '& "$env:BUILD_SCRIPT"'
+    displayName: Build
+  - task: CopyFiles@2
+    displayName: 'Copy files to $(Build.ArtifactStagingDirectory)'
+    inputs:
+      SourceFolder: '$(System.DefaultWorkingDirectory)/projects/windows/vs2019'
+      Contents: '*/Release/*.dll'
+      TargetFolder: '$(Build.ArtifactStagingDirectory)'
+      CleanTargetFolder: true
+      flattenFolders: true
+      preserveTimestamp: true
+  - task: PublishBuildArtifacts@1
+    displayName: 'Publish build artifacts'
+    inputs:
+      ArtifactName: windows
+- job: linux
+  displayName: Linux
+  pool:
+    name: Azure Pipelines
+    vmImage: ubuntu-16.04
+  timeoutInMinutes: 10
+  variables:
+    BOOTSTRAP_URL: https://raw.githubusercontent.com/danielga/garrysmod_common/master/build/bootstrap.sh
+    BUILD_SCRIPT: $(System.DefaultWorkingDirectory)/dependencies/garrysmod_common/build/build.sh
+    COMPILER_PLATFORM: gmake
+    PREMAKE5: $(System.DefaultWorkingDirectory)/dependencies/linux/premake-core/premake5
+    PROJECT_OS: linux
+    PREMAKE5_URL: https://github.com/premake/premake-core/releases/download/v5.0.0-alpha15/premake-5.0.0-alpha15-linux.tar.gz
+    CC: gcc-9
+    CXX: g++-9
+    AR: gcc-ar-9
+    NM: gcc-nm-9
+    RANLIB: gcc-ranlib-9
+  steps:
+  - bash: 'curl -s -L "$BOOTSTRAP_URL" | bash'
+    displayName: Bootstrap
+  - bash: |
+      sudo apt-get update && sudo apt-get install -y g++-9-multilib
+      $BUILD_SCRIPT
+    displayName: Build
+  - task: CopyFiles@2
+    displayName: 'Copy files to $(Build.ArtifactStagingDirectory)'
+    inputs:
+      SourceFolder: '$(System.DefaultWorkingDirectory)/projects/linux/gmake'
+      Contents: '*/Release/*.dll'
+      TargetFolder: '$(Build.ArtifactStagingDirectory)'
+      CleanTargetFolder: true
+      flattenFolders: true
+      preserveTimestamp: true
+  - task: PublishBuildArtifacts@1
+    displayName: 'Publish build artifacts'
+    inputs:
+      ArtifactName: linux
+- job: macosx
+  displayName: macOS
+  pool:
+    name: Azure Pipelines
+    vmImage: macOS-10.15
+  timeoutInMinutes: 10
+  variables:
+    BOOTSTRAP_URL: https://raw.githubusercontent.com/danielga/garrysmod_common/master/build/bootstrap.sh
+    BUILD_SCRIPT: $(System.DefaultWorkingDirectory)/dependencies/garrysmod_common/build/build.sh
+    COMPILER_PLATFORM: gmake
+    PREMAKE5: $(System.DefaultWorkingDirectory)/dependencies/macosx/premake-core/premake5
+    PROJECT_OS: macosx
+    PREMAKE5_URL: https://github.com/premake/premake-core/releases/download/v5.0.0-alpha15/premake-5.0.0-alpha15-macosx.tar.gz
+    MACOSX_SDK_URL: https://github.com/phracker/MacOSX-SDKs/releases/download/10.15/MacOSX10.7.sdk.tar.xz
+    MACOSX_SDK_DIRECTORY: $(System.DefaultWorkingDirectory)/dependencies/macosx/MacOSX10.7.sdk
+    SDKROOT: $(System.DefaultWorkingDirectory)/dependencies/macosx/MacOSX10.7.sdk
+  steps:
+  - bash: 'curl -s -L "$BOOTSTRAP_URL" | bash'
+    displayName: Bootstrap
+  - bash: |
+      sudo xcode-select -s "/Applications/Xcode_11.7.app/Contents/Developer"
+      $BUILD_SCRIPT
+    displayName: Build
+  - task: CopyFiles@2
+    displayName: 'Copy files to $(Build.ArtifactStagingDirectory)'
+    inputs:
+      SourceFolder: '$(System.DefaultWorkingDirectory)/projects/macosx/gmake'
+      Contents: '*/Release/*.dll'
+      TargetFolder: '$(Build.ArtifactStagingDirectory)'
+      CleanTargetFolder: true
+      flattenFolders: true
+      preserveTimestamp: true
+  - task: PublishBuildArtifacts@1
+    displayName: 'Publish build artifacts'
+    inputs:
+      ArtifactName: macosx
+- job: publish
+  displayName: Publish to GitHub Releases
+  pool:
+    name: Azure Pipelines
+    vmImage: ubuntu-18.04
+  timeoutInMinutes: 5
+  dependsOn:
+    - windows
+    - linux
+    - macosx
+  steps:
+  - task: DownloadBuildArtifacts@0
+    displayName: 'Download build artifacts'
+    inputs:
+      downloadType: specific
+      parallelizationLimit: 12
+  - task: GitHubRelease@1
+    displayName: 'Publish GitHub release $(build.sourceBranchName)'
+    inputs:
+      gitHubConnection: 'GitHub danielga'
+      releaseNotesSource: inline
+      assets: '$(System.ArtifactsDirectory)/**'
+      addChangeLog: false

includes/modules/spewx.lua

@@ -0,0 +1,21 @@
+require("spew")
+
+local function PassMessagesToHook()
+    local messages = spew.GetAll()
+    if not messages then
+        return
+    end
+
+    for i = 1, #messages do
+        local msg = messages[i]
+        hook.Run("Spew", msg.Timestamp, msg.Type, msg.Level, msg.Group, Color(msg.Color.r, msg.Color.g, msg.Color.b, msg.Color.a), msg.Message)
+    end
+end
+
+function spew.EnableHook()
+    hook.Add("Think", "spew.PassMessagesToHook", PassMessagesToHook)
+end
+
+function spew.DisableHook()
+    hook.Remove("Think", "spew.PassMessagesToHook")
+end

premake5.lua

@@ -13,7 +13,6 @@ CreateWorkspace({name = "spew"})
 	CreateProject({serverside = true})
 		IncludeSDKCommon()
 		IncludeSDKTier0()
-		IncludeLuaShared()
 
 	CreateProject({serverside = false})
 		IncludeSDKCommon()

readme.md

@@ -2,6 +2,153 @@
 
 A Garry's Mod module that intercepts the engine's messages and passes them to Lua. Also able to prevent them from printing.
 
+## API reference
+
+When return types or parameters are enclosed in square brackets, they are nillable returns or optional parameters and will contain the default value, in the case of parameters.
+
+### Types
+
+```lua
+Message = { -- Contains a log message and all its metadata.
+    time = number, -- Timestamp of the message.
+    type = number, -- Represents the type of the message.
+    level = number, -- Message level, interacts with the "developer" convar.
+    group = string, -- Contains the message group name.
+    color = { -- Message color.
+        r = number, -- Amount of red of the message color.
+        g = number, -- Amount of green of the message color.
+        b = number, -- Amount of blue of the message color.
+        a = number -- Amount of alpha of the message color.
+    },
+    message = string -- Contains the log message.
+}
+
+Messages = {Message} -- 'Messages' is an array of 'Message'
+```
+
+### Constants
+
+```lua
+-- Holds the 'spew' module version in a string form.
+-- Example: "spew 1.0.0"
+string spew.Version
+```
+
+```lua
+-- Holds the 'spew' module version in a numeric form, LuaJIT style.
+-- Example: 10000
+number spew.VersionNum
+```
+
+```lua
+-- Type enum for simple messages.
+number spew.MESSAGE
+```
+
+```lua
+-- Type enum for warning messages.
+number spew.WARNING
+```
+
+```lua
+-- Type enum for assert messages.
+number spew.ASSERT
+```
+
+```lua
+-- Type enum for error messages.
+number spew.ERROR
+```
+
+```lua
+-- Type enum for log messages.
+number spew.LOG
+```
+
+### Functions
+
+```lua
+-- Get up to the specified number of messages from the queue.
+-- NOTE: Avoid retrieving messages one by one in loops.
+-- 'count' is a number, containing the number of messages to retrieve.
+-- Returns an array of 'Message' if messages are available, otherwise returns 'nil'.
+[Messages] spew.Get([count = 1])
+```
+
+```lua
+-- Get all the messages in the queue.
+-- Returns an array of 'Message' if messages are available, otherwise returns 'nil'.
+[Messages] spew.GetAll()
+```
+
+```lua
+-- Block a certain type of messages from being logged.
+-- When -1 is passed, all message types are blocked.
+-- Recommended to use the enums for message types, as their value can change anytime in the future.
+-- 'message_type' is a number, representing the message type to be blocked.
+-- Returns true if the operation was successful, false otherwise.
+boolean spew.Block([message_type = -1])
+```
+
+```lua
+-- Unblock a certain type of messages from being logged.
+-- When -1 is passed, all message types are unblocked.
+-- Recommended to use the enums for message types, as their value can change anytime in the future.
+-- 'message_type' is a number, representing the message type to be unblocked.
+-- Returns true if the operation was successful, false otherwise.
+boolean spew.Unblock([message_type = -1])
+```
+
+```lua
+-- Returns the blocked state of a certain type of messages.
+-- Recommended to use the enums for message types, as their value can change anytime in the future.
+-- 'message_type' is a number, representing the message type to get state of.
+-- Returns true if the message type is blocked, false otherwise.
+boolean spew.IsBlocked(message_type)
+```
+
+```lua
+-- Sets the maximum log queue size.
+-- After this amount of logs, older messages are dequeued.
+-- 'max_queue_size' is a number, representing the maximum log queue size.
+spew.SetMaximumQueueSize(max_queue_size)
+```
+
+```lua
+-- Returns the maximum log queue size.
+-- After this amount of logs, older messages are dequeued.
+number spew.GetMaximumQueueSize()
+```
+
+These functions are only available when the Lua extension module `spewx` is required.
+
+```lua
+-- Enables the Lua hook "Spew".
+-- spew.Get and spew.GetAll will be unreliable when this hook is enabled, as it uses these same functions to work, causing the log queue to be consumed.
+-- Uses the "Think" hook to dispatch log messages, hence it will seem to be disabled when used in a dedicated server with no players. This limitation can be bypassed by setting the "sv_hibernate_think" convar to 1.
+spew.EnableHook()
+```
+
+```lua
+-- Disables the Lua hook "Spew".
+spew.DisableHook()
+```
+
+### Hooks
+
+This hook is only available when the Lua extension module `spewx` is required.
+
+```lua
+-- Hook called when a message is logged.
+-- 'timestamp' is a number representing the time it was logged at.
+-- 'type' is a number, equal to one of the type enums.
+-- 'level' is a number, with which the "developer" convar interacts.
+-- 'group' is a string, with the name of the message group.
+-- 'message' is a string, containing the log message.
+-- Example: hook.Add("Spew", "logger", function(...) end)
+Spew(timestamp, type, level, group, color, message)
+```
+
 ## Compiling
 
 The only supported compilation platform for this project on Windows is **Visual Studio 2017**. However, it's possible it'll work with *Visual Studio 2015* and *Visual Studio 2019* because of the unified runtime.