string.gsub (s, pattern, repl [, n])

pattern のすべて (n が指定されている場合は最初の n 個) のオカレンスを、repl で指定された置き換えストリングで置き換えた s のコピーを返します。repl には、ストリング、表、または関数を指定できます。gsub はまた、2 番目の値として一致が発生した回数も返します。

repl がストリングであれば、その値が置き換えに使用されます。文字 % は、エスケープ文字として機能します。repl の中の形式 %n (n は 1 から 9) のシーケンスは、n 番目にキャプチャーされたサブストリングの値を表します (次を参照)。シーケンス %0 は、一致の全体を表します。シーケンス %% は、1 個の % を表します。

repl が表であれば、その表は、最初のキャプチャーをキーとして使用して、一致ごとに照会されます。パターンにキャプチャーが指定されていなければ、一致の全体がキーとして使用されます。

repl が関数であれば、一致があるたびにこの関数が呼び出され、 そのとき、キャプチャーされたすべてのサブストリングが順番に引数として渡されます。パターンにキャプチャーが指定されていなければ、一致の全体が唯一の引数として渡されます。

表の照会または関数呼び出しによって返された値がストリングまたは数値であれば、それが置き換えストリングとして使用されます。そうでなくて、false またはnull であれば、置き換えは行われません (つまり、ストリングの中にオリジナルの一致が保持されます)。

以下にいくつかの例を示します。

     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"