Question

Returns a copy of s
in which all occurrences of the pattern have been
replaced by a replacement string specified by repl,
which may be a string, a table, or a function.
gsub also returns, as its second value,
the total number of substitutions made.

If repl is a string, then its value is used for replacement.
The character % works as an escape character:
any sequence in repl of the form %n,
with n between 1 and 9,
stands for the value of the n-th captured substring (see below).
The sequence %0 stands for the whole match.
The sequence %% stands for a single %.

If repl is a table, then the table is queried for every match,
using the first capture as the key;
if the pattern specifies no captures,
then the whole match is used as the key.

If repl is a function, then this function is called every time a
match occurs, with all captured substrings passed as arguments,
in order;
if the pattern specifies no captures,
then the whole match is passed as a sole argument.

If the value returned by the table query or by the function call
is a string or a number,
then it is used as the replacement string;
otherwise, if it is false or nil,
then there is no replacement
(that is, the original match is kept in the string).

The optional last parameter n limits
the maximum number of substitutions to occur.
For instance, when n is 1 only the first occurrence of
pattern is replaced.

Here are some examples:

 x = string.gsub("hello world", "(%w+)", "%1 %1")
 --> x="hello hello world world"
 
 x = string.gsub("hello world", "%w+", "%0 %0", 1)
 --> x="hello hello world"
 
 x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
 --> x="world hello Lua from"
 
 x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
 --> x="home = /home/roberto, user = roberto"
 
 x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
 return loadstring(s)()
 end)
 --> x="4+5 = 9"
 
 local t = {name="lua", version="5.1"}
 x = string.gsub("$name%-$version.tar.gz", "%$(%w+)", t)
 --> x="lua-5.1.tar.gz"