Quantcast
Download
(18 Kb)
Download
Updated: 02/04/20 09:54 PM
Compatibility:
Harrowstorm (5.3.0)
Dragonhold (5.2.5)
Scalebreaker (5.1.5)
Elsweyr (5.0.5)
Updated:02/04/20 09:54 PM
Created:12/30/18 04:39 PM
Monthly downloads:14,133
Total downloads:97,660
Favorites:94
MD5:
5.2.5
LibSFUtils  Popular! (More than 5000 hits)
Version: 23
by: Shadowfen [More]
A library of common convenience functionality that I use with most of my addons.


Colors

Convenience color tables
Defines values for : junk, normal, fine, superior, epic, legendary
as well as some other colors that I commonly use

sfutil.colors - master table of colors in both hex and rgb
sfutil.hex - an alias table for just the hex color values
sfutil.rgb - an alias table for just the rgb color values


Strings

function sfutil.str(...)
Concatenate varargs to a string. Uses table concatenation to combine the parameters to be slightly more efficient to multiple uses of the .. string concatenator.
function sfutil.dstr(delim, ...)
Concatenate varargs to a delimited string. Uses table concatenation to combine the parameters separated by the specified delimiter to be slightly more efficient to multiple uses of the .. string concatenator.
function sfutil.GetIconized(prompt, promptcolor, texturefile, texturecolor)
Create a string containing an optional icon (of optional color) followed by a text prompt. (Without the parameters, it simply prepares and optionally colorizes text.)
The prompt parameter is a string or a localization string id.
The color parameters are all hex colors.
function sfutil.ColorText(prompt, promptcolor)
Create a string containing a text prompt and a text color. The text color is optional, but if you do not provide it, you just get the same text back that you put in.
The prompt parameter is a string or a localization string id.
The color parameter is a hex color.
function sfutil.bool2str(bool)
Turn a boolean value into a string suitable for display. Returns the string "true" or "false".
This function uses sfutil.isTrue() to decide if bool is true - which will have different results from the lua standard definition of "true". Lua decides that anything not false (or nil) must be true (including 0). This function decides that anything not true (or 1) is false.

Function Wrapping

function sfutil.WrapFunction(namespace, functionName, wrapper)
Used to be able to wrap an existing function with another so that subsequent calls to the function will actually invoke the wrapping function.

The wrapping function should accept a function as the first parameter, followed by the parameters expected by the original function. It will be passed in the original function so the wrapping function can call it (if it chooses).

Can be called with or without the namespace parameter (which defines the namespace where the original function is defined). If the namespace parameter is not provided then assume the global namespace _G.

Examples:
WrapFunction(myfunc, mywrapper)
will wrap the global function myfunc to call mywrapper

WrapFunction(TT, myfunc, mywrapper)
will wrap TT.myfunc with a call to mywrapper

Saved Variables and Defaults

(All of the Saved Variables functions work on the variables for the
current server that you are logged in on.)


Note: You should only ever use one of the functions getToonSavedVars(), getAcctSavedVars(),
or getAllSavedVars() because they are loading saved variables from files (that only get changed
when you log out or /reloadui) and so are very slow and you don't want to waste time doing it
multiple times for no good reason.


function sfutil.getToonSavedVars(saveFile, saveVer, saveDefaults)
Get saved variables table toon only. In addition to calling the appropriate ZO_SavedVars function, it will call sfutil.defaultMissing().
Note: This does NOT automatically add an accountWide variable to the table if it is not already there!
function sfutil.getAcctSavedVars(saveFile, saveVer, saveDefaults)
Get saved variables table account-wide only. In addition to calling the appropriate ZO_SavedVars function, it will call sfutil.defaultMissing().
function sfutil.getAllSavedVars(saveFileName, saveVer, saveAWDefaults, saveToonDefaults)
Get saved variables tables when we deal with both toon and account-wide settings.

Toon and account-wide can have different default tables (but don't have to). If you only specify one default table it will be used for both account-wide and toon.

An "accountWide" variable will be automatically added to the toon table if it does not already exist, because the currentSavedVars() function works off of that. It is used to designate whether the settings for account-wide are currently in effect or the toon settings are in effect.
function sfutil.currentSavedVars(aw, toon, newAcctWideVal)
Return the currently active table of saved variables.
If newAcctWideVal is not nil, then the toon.accountWide value will be set to the new value before deciding which of the tables aw or toon will be returned (based on if toon.accountWide evaluates to true or false).
function sfutil.defaultMissing(svtable, defaulttable)
Recursively initialize missing values in a table from a defaults table. Existing values in the svtable will remain unchanged. This function is needed because the ZO_SavedVars functions do not recurse into a table inside the defaulttable if the table itself exists in svtable.

Basic Utility Functions

function sfutil.isTrue(val)
Returns true if val was some value equivalent to true or 1. Any other value will return false.
(This is different from the lua standard definition of "true". Lua decides that anything not false (or nil) must be true (including 0).
This function decides that anything not true (or 1) is false.)
function sfutil.nilDefault( val, defaultval )
Return the value of val; unless it is nil when we then will return defaultval instead of the nil.

The lua standard "var = val or default" does not do the same job, because if val evaluates to false according to lua then the default value would still be assigned.
Here we specifically only want the default value if val == nil.

Messages and Debug

function sfutil.initSystemMsgPrefix(addon_name, hexcolor)
Create a prefix to use in front of your messages (so that users can tell your messages from some other addon's). (If you are not using addonChatter.)
function sfutil.systemMsg(prefix, text, hexcolor)
Send a message to the chat window prefixed by the prefix that you pass in.
function sfutil.addonChatter:New(addon_name)
Create an addonChatter table and set up the prefix to use in front of your messages (so that users can tell your messages from some other addon's messages).
function sfutil.addonChatter:systemMessage(...)
Print normal messages to chat
function sfutil.addonChatter:debugMsg(...)
Print debug messages to chat if debug messages are enabled.
function sfutil.addonChatter:enableDebug()
Turn on the printing of debug messages.
function sfutil.addonChatter:disableDebug()
Turn off the printing of debug messages.
function sfutil.addonChatter:toggleDebug()
Toggle on/off the printing of debug messages
function sfutil.addonChatter:getDebugState()
Return the string "true" if debug messages are enabled. Otherwise return the string "false".

Slash Commands

function sfutil.addonChatter:slashHelp(title, cmdstable)
Display in chat a table of slash commands with descriptions (using the addonChatter you have previously created)
Localization


function sfutil.LoadLanguage(localization_strings, defaultLang)
Add strings to the string table for the client language (or the default language if the client language did not have strings defined for it). The localization_strings parameter is a table of tables of localization strings, and defaultLang defaults to "en" if not provided.

For example: You could have the following string table defined:

local localization_strings = {

de = {
AC_IAKONI_TAG= "Iakoni's Gear Changer",
AC_IAKONI_CATEGORY_SET_1= "Set#1",
AC_IAKONI_CATEGORY_SET_1_DESC= "#1 Set aus dem AddOn Iakoni's Gear Changer",
AC_IAKONI_CATEGORY_SET_2= "Set#2",
AC_IAKONI_CATEGORY_SET_2_DESC= "#2 Set aus dem AddOn Iakoni's Gear Changer",
AC_IAKONI_CATEGORY_SET_3= "Set#3",
AC_IAKONI_CATEGORY_SET_3_DESC= "#3 Set aus dem AddOn Iakoni's Gear Changer",
},

en = {
AC_IAKONI_TAG= "Iakoni's Gear Changer",
AC_IAKONI_CATEGORY_SET_1= "Set#1",
AC_IAKONI_CATEGORY_SET_1_DESC= "#1 Set from Iakoni's Gear Changer",
AC_IAKONI_CATEGORY_SET_2= "Set#2",
AC_IAKONI_CATEGORY_SET_2_DESC= "#2 Set from Iakoni's Gear Changer",
AC_IAKONI_CATEGORY_SET_3= "Set#3",
AC_IAKONI_CATEGORY_SET_3_DESC= "#3 Set from Iakoni's Gear Changer",
},

zh = {
AC_IAKONI_TAG= "Iakoni's Gear Changer",
AC_IAKONI_CATEGORY_SET_1= "装备配置#1",
AC_IAKONI_CATEGORY_SET_1_DESC= "#1 号装备配置 Iakoni's Gear Changer",
AC_IAKONI_CATEGORY_SET_2= "装备配置#2",
AC_IAKONI_CATEGORY_SET_2_DESC= "#2 号装备配置 Iakoni's Gear Changer",
AC_IAKONI_CATEGORY_SET_3= "装备配置#3",
AC_IAKONI_CATEGORY_SET_3_DESC= "#3 号装备配置 Iakoni's Gear Changer",
},
}

and then in your initialization function call:
LibSFUtils.LoadLanguage(localization_strings,"en")
or you can split the definitions of
AC_localization_strings["en"], AC_localization_strings["de"], and AC_localization_strings["zh"]
into separate files (strings.lua for the default, de.lua, zh.lua, etc) and then include your default language lua file (strings.lua), and $(language).lua in your addon manifest. This way you can only load the strings for two languages (at most) instead of all of them you have available.

Version Checker
Used to check if the dependent libraries that are loaded have at least a minimum version. (These functions depend on the libraries using the
Code:
## AddOnVersion: 23
marker in the library's manifest (.txt file).
These functions are designed to work with the LibDebugLogger, however you can provide your own version of a logger by providing a object table that at least provides the functions
Code:
 <mylogger>:Error(<format>,...)
,
Code:
<mylogger>:Warn(<format>,...)
and
Code:
<mylogger>:Info(<format>,...)
.
When working with the LibDebugLogger, it will send error messages to the logger when a library is found with an older version than required, a warning message if a required library is missing, and an info message if no version information is available for the library.

Code:
local VC = LibSFUtils.VersionChecker
function VC:New(addonName) (or VC(addonName)
Create a new instance of a version checker.
function VC:Enable(logger)
Enable the VersionChecker instance and set the logger that the instance is to use.
For instance, you would call
Code:
myVC:Enable(LibDebugLogger("myAddon"))
.
function VCisable()
Disable the VersionChecker instance so that none of the other VC functions do anything.
function VC:NewCheckVersion(libname, expectedVersion)
Check if the library is 1) loaded, and 2) has a version that is equal to or greater than the version you expect to have.
function VC:NoVersion(libname)
Specify that you know that no version information is available for the library - (only an info message).
function LibSFUtils.GetAddonIndex(libname)
This utility function will return the ZOS addon index for the library named libname (if it is loaded). If it is not loaded, it will return -1.
function LibSFUtils.GetAddonVersion(name)
This utility function will return the addon version (as specified in the manifest ##AddOnVersion: line) for the library named libname (if it is loaded). If it is not loaded, it will return -1. If it is loaded but does not have a ##AddOnVersion: then it will return 0.
Example of use:
Code:
    function myaddon.checkLibraryVersions()
        local vc = SF.VersionChecker("myaddon")
        local logger = LibDebugLogger.Create("rChat")
        vc:Enable(logger)
        vc:CheckVersion("LibAddonMenu-2.0", 30)
        vc:CheckVersion("LibMediaProvider-1.0", 12)
        vc:CheckVersion("libChat2", 12)
        vc:CheckVersion("LibSFUtils", 23)
        vc:CheckVersion("LibDebugLogger",128)
    end
    
    local function OnAddonLoaded(_, addonName)

        --Protect
        if addonName ~= myaddon.name then return end
        
        myaddon.checkLibraryVersions()
        -- do important stuff
    end
23
  • Added new functions for checking the versions of loaded libraries. These functions will work in conjunction with LibDebugLogger (or some other logger) to print messages to the specified logger if a library is either not loaded or does not meet the minimum version requirement for the library to be used with an addon. See ReadMe for more details.
  • Split related functions into separate source files for convenience. There are no changes to the API or functionality in doing so - only in making the code easier to inspect and change.

22
  • Some new functions for delimited string splitting and color marker stripping or correction.
    LibSFUtils.gsplit(str, pat)
    Split a string into sections using a pattern as a delimiter
    When delimiter starts or ends the string, an empty string is considered
    to be before/after the delimiter. When two or more delimiters are together,
    there is considered to be empty strings between them.
    Returns table of strings that were separated by delimiters
    (The delimiters are NOT included in the table.)

    LibSFUtils.getAllColorDelim(str)
    Get the positions of all of the color markers (|c and |r) in a string
    Return a table where each entry has the index into the string (start)
    and the type of marker (code = "c" or "r", lower case)
    Havok allows "|" escape character for "|" (user input) so we must handle doubled pipes for chat.
    Returns the markertable for the markers that are in the string
    (can be empty but never nil)

    LibSFUtils.regularizeColors(markertable, str)
    Evaluate and correct the color markers in the string so that
    empty colors are marked for removal, "|c" markers are
    always balanced by "|r" markers, and we don't have extra "|r"
    markers
    Uses the source string and a marker table as produced by
    getAllColorDelim(). The marker table is modified by this function.
    Returns the modified markertable for the markers that are in (or should be in) the string

    LibSFUtils.stripColors(markertable,str)
    Strip all of the color markers out of the string.
    Uses the source string and a marker table as produced by
    getAllColorDelim().
    Returns a string which is the source string with all of the color
    markers removed.

    LibSFUtils.colorsplit(markertable, str)
    Splits the string into sections corresponding the color markers themselves
    and the text around the markers. Doing a table.concat() will join the contents
    of the returned table into a properly color-marked string.
    Returns the table of sections

21
  • Added a LibSFUtils.LibVersion variable which contains the current version number of the library. This can be used by addons that depend on this library to ensure that a minimum version of the library is loaded and accessible.

20
  • Added functions supporting an array of sounds since I now have more than one addon doing it.
  • Update defaultMissing() to properly check for a nil value and return the default if found.

19
  • API Bump

18
  • API bump

17
  • More adjustments to the LibSFUtil enhanced version of SafeAddString() to support the LoadLanguage() function.

16
  • Modified and tested the LibSFUtil enhanced version of SafeAddString() to support the LoadLanguage() function.
  • Fixed error in loading of default language strings in LoadLanguage().

15
  • Removed dependency on LibStub. This library can no longer be accessed through LibStub.
  • Added new ##IsLibrary to manifest.
  • Added new Localization function LoadLanguage().

    function sfutil.LoadLanguage(localization_strings, defaultLang)
    Add strings to the string table for the client language (or
    the default language if the client language did not have strings
    defined for it). The localization_strings parameter is a table of tables
    of localization strings, and defaultLang defaults to "en" if not
    provided.

    An example of a localization_strings table might be:

    MyAddon.localization_strings = {
    ["en"] = {
    MYADDON_RANDOM_TEXT = "This is a test",
    },
    ["de"] = {
    MYADDON_RANDOM_TEXT = "Dies ist ein Test",
    },
    ["fr"] = {
    MYADDON_RANDOM_TEXT = "C'est un test",
    },
    }

    Then the sfutil.LoadLanguage(MyAddon.localization_strings, "en") would load
    the appropriate strings table for the client language, or the "en" strings
    if there isn't a table for the language (say it was "jp").
  • Added a deep copy function for a table - deepCopy(orig) returns new table.

14
  • API Bump

13
  • Hybridize library to provide both LibStub access for addons still using it while providing direct access for addons that have transitioned away from using LibStub. The LibSFUtils library will still depend on LibStub to provide backwards compatibility until LibStub support/access is discontinued (basically when I've converted all of my addons to the new paradigm).
    While LibStub access is still supported, users of it typically have something like
    Code:
    local SF = LibStub("LibSFUtils")
    New users of the library should not do this however. Instead, you should use the direct access method such as
    Code:
    local SF = LibSFUtils
    Current addons using this library should convert their LibStub("LibSFUtils") to the second version of this line (to minimize the amount of changes required to their own code).

12
  • First release as a standalone library.
  • Added the slashHelp() function to addonChatter. This will allow you to pass in a table of slash commands and descriptions and have them printed to chat with colorization and the [...] addon prefix.
    For example,
    Code:
    chatter:slashHelp("my title", { 
        { "/xx.init", "Reinitialize"}, 
        {"/xx cute", "Display cute remark"} } )
    Will display
    [myaddon] my title
    [myaddon] /xx.init = Reinitialize
    [myaddon] /xx cute = Display cute remark
    in the chat window.
  • Breaking change Removed sfutil.copy() - deep table copy as ZO_DeepTableCopy(source, dest) can be used instead.
  • Wrote documentation.

11
  • Beta as an standalone library.
Optional Files (0)


Archived Files (11)
File Name
Version
Size
Uploader
Date
22
15kB
Shadowfen
01/17/20 10:24 AM
21
13kB
Shadowfen
01/01/20 03:19 PM
20
12kB
Shadowfen
12/10/19 08:41 PM
19
11kB
Shadowfen
10/20/19 05:04 PM
18
11kB
Shadowfen
08/15/19 11:46 PM
17
66kB
Shadowfen
05/19/19 06:37 PM
16
11kB
Shadowfen
05/11/19 08:53 AM
15
52kB
Shadowfen
05/02/19 10:54 PM
14
9kB
Shadowfen
02/25/19 10:13 PM
13
9kB
Shadowfen
12/31/18 12:20 PM
12
9kB
Shadowfen
12/30/18 04:39 PM


Post A Reply Comment Options
Unread 05/05/19, 07:43 PM  
Shadowfen
AddOn Author - Click to view AddOns

Forum posts: 43
File comments: 326
Uploads: 10
Originally Posted by fostot
I actually have completely uninstalled and reinstalled using Minion and i still get the same error. Clearly something isn't right . I get the same error mentioned before. Maybe you forgot to upload the new Slasher version to EsoUI that removes the need for LibStub?? As you mentioned it shouldn't be needed now and I still see it trying to use it.
Okay, I've just remade and reuploaded the archive for Slasher-1.5 so if you could uninstall and reinstall one more time, and let me know if it works...
Report comment to moderator  
Reply With Quote
Unread 05/05/19, 04:08 PM  
fostot

Forum posts: 0
File comments: 18
Uploads: 0
I actually have completely uninstalled and reinstalled using Minion and i still get the same error. Clearly something isn't right . I get the same error mentioned before. Maybe you forgot to upload the new Slasher version to EsoUI that removes the need for LibStub?? As you mentioned it shouldn't be needed now and I still see it trying to use it.
Report comment to moderator  
Reply With Quote
Unread 05/05/19, 02:15 PM  
Shadowfen
AddOn Author - Click to view AddOns

Forum posts: 43
File comments: 326
Uploads: 10
Originally Posted by dlrgames
The new version of the lib isn't working for me. Slasher throws an error on login and Fast Ride doesn't activate.
The problem is that you likely have outdated addons or have not installed the library addons separately.
For Slasher, it is likely that you have an out-of-date LibSFUtils that still requires LibStub (which is no longer provided).

For Fast Ride, you should make sure that you have installed LibAddonMenu-2.0 as a separate standalone addon (just install it from Minion). The latest version of that addon is required for this version of FastRide (and the latest version of LibAddonMenu-2.0 is only available separately - it is not included with other Addons now).
Report comment to moderator  
Reply With Quote
Unread 05/03/19, 08:21 AM  
dlrgames
AddOn Author - Click to view AddOns

Forum posts: 1
File comments: 29
Uploads: 1
The new version of the lib isn't working for me. Slasher throws an error on login and Fast Ride doesn't activate.
Report comment to moderator  
Reply With Quote
Unread 12/31/18, 11:21 AM  
Baertram
 
Baertram's Avatar
AddOn Author - Click to view AddOns

Forum posts: 2625
File comments: 3037
Uploads: 57
Oh right, you are using it already. This changes things a bit Yes, you'd need to adopt your addons using the lib then to not use LibStub and only use your lib's "global variable name" + change the lib to have "global variable name".

Originally Posted by Shadowfen
Originally Posted by Baertram
Hey Shadowfen,

What I heard from other devs (untested):
New libraries should not use LibStub anymore but ONLY apply the ##AddOnVersion: tag in the manifest txt file.

As you are using "##AddOnVersion" in the manifest txt file of your library you normally do not need to use LibStub anymore. So you could remove the ##DependsOn: LibStub line!

You could simply strip it from your library and the game will assure that the ##AddOnVersion given will be loaded with the maximum value (the part which libStub was doing before).
How do you then use the library in addons? Does that still require LibStub?

Edit:
While it might not need LibStub to control which version got loaded, it seems that it is still required until I either change the library's namespace to match what was being passed into LibStub:NewLibrary() or else I change all of the addons which use the library to use the library's real namespace instead of the LibStub string. So, not really a quick change.

(Also, it is not a new library - just a newly published library. )
Report comment to moderator  
Reply With Quote
Unread 12/30/18, 08:42 PM  
Shadowfen
AddOn Author - Click to view AddOns

Forum posts: 43
File comments: 326
Uploads: 10
Originally Posted by Baertram
Hey Shadowfen,

What I heard from other devs (untested):
New libraries should not use LibStub anymore but ONLY apply the ##AddOnVersion: tag in the manifest txt file.

As you are using "##AddOnVersion" in the manifest txt file of your library you normally do not need to use LibStub anymore. So you could remove the ##DependsOn: LibStub line!

You could simply strip it from your library and the game will assure that the ##AddOnVersion given will be loaded with the maximum value (the part which libStub was doing before).
How do you then use the library in addons? Does that still require LibStub?

Edit:
While it might not need LibStub to control which version got loaded, it seems that it is still required until I either change the library's namespace to match what was being passed into LibStub:NewLibrary() or else I change all of the addons which use the library to use the library's real namespace instead of the LibStub string. So, not really a quick change.

(Also, it is not a new library - just a newly published library. )
Last edited by Shadowfen : 12/30/18 at 09:05 PM.
Report comment to moderator  
Reply With Quote
Unread 12/30/18, 07:59 PM  
Baertram
 
Baertram's Avatar
AddOn Author - Click to view AddOns

Forum posts: 2625
File comments: 3037
Uploads: 57
Hey Shadowfen,

What I heard from other devs (untested):
New libraries should not use LibStub anymore but ONLY apply the ##AddOnVersion: tag in the manifest txt file.

As you are using "##AddOnVersion" in the manifest txt file of your library you normally do not need to use LibStub anymore. So you could remove the ##DependsOn: LibStub line!

You could simply strip it from your library and the game will assure that the ##AddOnVersion given will be loaded with the maximum value (the part which libStub was doing before).
Last edited by Baertram : 12/30/18 at 07:59 PM.
Report comment to moderator  
Reply With Quote
Post A Reply



Category Jump: