What Is The Replacement String Syntax?

The % in last argument must be used in cooperation with the second argument which is the pattern, this operator lets you get the match that has been found in cases where you for example use %d, you know it's some number but what number exactly? Or where you match multiple letters. I of course might be wrong but it's the only possible pattern in the third argument.

The way you use it is that you need to use () pattern inside of the second argument pattern, that will let you access the match that has been found from the bracket, you can have multiple brackets and you will access them in the third parameter like this %1 .. %2 .. and so one, those numbers mean bracket order, here are some examples

local String = "SomE oF ThESe LeTTeRS arE UPPERcAsE"

local Result = string.gsub(String, "(%u)", "_%1")
print(Result)

_Som_E o_F _Th_E_Se _Le_T_Te_R_S ar_E _U_P_P_E_Rc_As_E

Here you see that it put an underscore before each uppercase letter, that is because %u pattern stands for uppercase letters, i put it into a bracket and here you see it since it's first bracket, it's order number is 1 so in the third parameter, %1 will be the match + the underscode since i put it there.

Here is how to space out a string after each capital letter

local String = "CatsDoNotLikeBurgersBecauseTheyAreHunters, TheyEatMeat!"

local Result = string.gsub(String, "(%l)(%u)", "%1\32%2")
print(Result)

Cats Do Not Like Burgers Because They Are Hunters, They Eat Meat!

Here the same method with order applied where %1 referred to the first bracket, (%l) and %2 referred to the second one, (%u), i then just put space in between them and done!

With letters inside of [] it's the same! Say you want to add nyo after each syllable letter, simple!

local String = "Some cats can be dangerous, never underestimate their power"

local Result = string.gsub(String, "[(aeiou)]",  "%1nyo")
print(Result)

Sonyomenyo canyots canyon benyo danyongenyoronyounyos, nenyovenyor unyondenyorenyostinyomanyotenyo thenyoinyor ponyowenyor

The method gsub is a function which will return the same string after replacing all the "rules" in the pattern string with the replacement string.

For example, let's say you want to get only the numbers from a string, you could do

local str = "I, don't, like, punctuation!!!!!!"
local newString = string.gsub(str, "%p", "")

print(newString) -- OUTPUT: I dont like punctuation

Essentially, the example above replaced any punctuation (defined by the string pattern %p) and replaced it with an empty string, thereby removing it.

However, gsub will return 2 things: the new string and the no. substitutions.

This can be useful for counting, for example:

local str = "I, don't, like, punctuation!!!!!!"
local _, subs = string.gsub(str, "%p", "") -- using _ as an empty/unused variable name

print(subs) -- OUTPUT: 10

If the replacement is a function, not a string, the arguments passed to the function are any captures that are made. If the function returns a string, the value returned is substituted back into the string. [SOURCE]

Example:

string.gsub("I, don't, like, punctuation!!!!!!", "%w+", print) -- changed the string pattern compared to previous examples

-- As the third argument is "print", it runs the function and we get the output:

--[[ OUTPUT
I
don
t
like
punctuation
--]]

Example 2 This example will replace with lengths of each word

local str = "I dont like punctuation!"
local newString, _ = string.gsub(str, "(%w+)", function(w)
    return string.len(w) 
end)

print(newString) -- OUTPUT: 1 4 4 11!

Obviously you can use this for many other rules/string patterns. I mostly use it for either counting or string manipulation within a textbox, i.e. if I want the textBox to only allow numbers as a form of input.

It's actually very useful, this is a great question!

I hope this has cleared it up for you, feel free to mess around a bit, see what you can discover on your own as this is one of those things that takes practice to understand better.

Also, if you're looking for documentation on this, you can check out LUA's official website:

https://www.lua.org/pil/20.1.html

https://www.lua.org/pil/20.2.html

If I answered your question, please make sure to accept my answer :)