Luaスクリプト機能

$Date: 2012/03/21 02:55:22 $

ライブラリ関数

ヤマハルーターのLuaスクリプトで利用できるライブラリ関数について説明します。標準のLua言語にあってもヤマハルーターでは利用できない関数は、ここに掲載していません。

それぞれの書式の中で、点線で囲まれた部分は省略可能であることを示します。

インデックス

基本関数

assert(value , message)

• value … 任意の型
• message … 文字列型

valueが偽、つまり、nilかfalseの場合にはエラーを発行し、スクリプトの実行を停止します。その他の場合は戻り値として引数をすべて返し、スクリプトの実行が継続されます。messageはエラーの場合に表示される文字列であり、省略した場合は"assertion failed!"という文字列が表示されます。

collectgarbage(opt , arg)

• opt … 文字列型
• arg … 数値型(FIXNUM)

この関数はガベージコレクション動作を制御します。optに与える文字列で以下のような動作をします。

• "stop": ガベージコレクションを停止する。
• "restart": 停止しているガベージコレクションを再開する。
• "collect": フルガベージコレクションを実行する。
• "count": Luaが使用しているメモリサイズをキロバイト単位で返す。
• "step": ガベージコレクションをargステップだけ実行する。ガベージコレクションが完了したときには戻り値としてtrueが返る。
• "setpause": ガベージコレクションのpauseパラメータを設定する。戻り値としては、古いpauseパラメータの値が返る。
• "setstepmul": ガベージコレクションのstep multiplierパラメータを設定する。戻り値としては、古いstep multiplierパラメータの値が返る。

dofile(filename)

• filename … 文字列型

filenameで指定されたファイルを読み出し、Luaスクリプトとして実行します。

標準のLua言語と異なり、filenameは省略できません。

each(arg...)

• arg … 任意の型

この関数は標準のLua言語には存在しません。_RT_LUA_VERSIONが"1.03"以降のファームウェアで使用することができます。

戻り値としてイテレータ関数を返す関数で、一般for文とともに用いることで、引数を巡回することができます。

特殊なケースとして、引数が一つだけでテーブル型の場合は、その引数を配列とみなして先頭から順に要素を巡回します。

for v in each(1, 2, "a", "b") do
  print(v)
end
t = {1, 2, "a", "b"}
for v in each(t) do
  print(v)
end
    

error(message , level)

• message … 文字列型
• level … 数値型(FIXNUM)

messageをエラーメッセージとして表示し、Luaスクリプトの実行を停止します。この関数は呼び出し元には戻りません。

levelでは、エラーの発生場所として表示する行番号を制御できます。levelを省略した場合、あるいは1を与えた場合には、error関数を呼び出した行がエラーの発生場所となります。2を与えた場合には、error関数を呼び出している関数を呼び出した行がエラーの発生場所となります。以降、3、4と値が増えるにつれ、関数の呼び出し関係が深くなっていきます。0を与えると、エラーの発生行を表示しません。

function f1(x) f2(x) end
function f2(x) f3(x) end
function f3(x) f4(x) end
function f4(x)
  if x == 1 then
    error("", 1)       -- f4()でエラー
  elseif x == 2 then
    error("", 2)       -- f3()でエラー
  elseif x == 3 then
    error("", 3)       -- f2()でエラー
  elseif x == 4 then
    error("", 4)       -- f1()でエラー
  else
    error("", 5)       -- トップレベルでエラー
  end
end
    

getfenv(func)

• func … 関数型もしくは数値型(FIXNUM)

funcが関数のときは、その関数の環境を返します。

funcが数値のときは、その値をスタックレベルとみなし、環境を返す関数を指定します。すなわち、以下のようになります。

• funcが1 … getfenvを呼び出している関数
• funcが2 … getfenvを呼び出している関数を呼び出している関数
• funcが3 … getfenvを呼び出している関数を呼び出している関数を呼び出している関数

funcが0のときは、グローバル環境を返します。funcを省略したときには、1が与えられたものとします。

getmetatable(object)

• object … 任意の型

objectがメタテーブルを持たない場合はnilを返します。objectがメタテーブルに"_metateble"をキーとする要素を持つ場合には、その要素の値を返します。その他の場合には、objectのメタテーブルを返します。

ipairs(table)

• table … テーブル型

戻り値として、(イテレータ関数、table、0)の三つ組みを返す関数で、一般for文とともに用いることで、テーブルの中で数値(FIXNUM)をキーとする要素を巡回することができます。

以下の例では、テーブルtの数値キーと値、(1, t[1])、(2, t[2])、…を順にprintで表示します。

for i, v in ipairs(t) do
  print(i, v)
end
    

ipairsは配列を対象とする関数なので、文字列等、数値(FIXNUM)以外をキーとする要素は取り出せません。また、0、負の数をキーとする要素も取り出せません。すべての要素を取り出すには、pairs関数を使用します。

load(func , chunkname)

• func … 関数型
• chunkname … 文字列型

関数funcを用いてチャンクをロードします。funcは呼び出されるたびに文字列を返す関数です。funcが空文字列、nilのいずれかを返すか、あるいは何も返さなかったらそこでチャンクは終了したものとみなされ、それまで返された文字列をすべて連結、コンパイルした関数がloadの戻り値として返されます。チャンクのコンパイルでエラーが発生したときには、nilとエラーメッセージ文字列が返されます。

chunknameはチャンクの名前としてエラーメッセージやデバッグ情報として用いられます。省略したときには、"=(load)"が用いられます。

loadfile(filename)

• filename … 文字列型

ファイルfilenameからチャンクを読み出し、関数を返します。戻り値等はloadと同様です。

標準のLua言語ではfilenameが省略できますが、ヤマハルーターの実装ではfilenameは省略できません。

loadstring(string , chunkname)

• string … 文字列型

文字列stringをチャンクとみなし、関数を返します。戻り値、chunknameの意味等はloadと同様です。

以下の例は、文字列で与えられたチャンクをロードし、実行するときの常套句です。

assert(loadstring(str))()
    

loadstring(str)で文字列strをコンパイルし、関数にします。assertを使うのは、strにエラーがあった場合にそれを捕まえるためです。最後のカッコ()で、コンパイルされた関数を実行しています。

next(table , key)

• table … テーブル型
• key … 任意の型

テーブルtableで、keyをキーとする要素の次の要素のキーと値を返します。keyが省略されるか、nilが与えられたときには、最初の要素のキーと値を返します。keyをキーとする要素がテーブルの最後の要素であったときには、nilを返します。

next(t) == nilであれば、tはまったく要素を持たないテーブルです。これは、テーブルが空かどうかを検査するときに使えるテクニックです。

テーブル内の要素の順番は規定されていません。キーが数値の場合でも、nextで巡回する順序はやはり規定されていません。そのため、nextでどのような順序で要素が返されるかは予想できません。数値のキーに対して数値順でアクセスしたいときにはipairsを用います。

nextを順に呼び出している途中で、テーブルに新しい要素を追加したときには、次のnextの動作は不定となります。すでに存在している要素の値を変更することは問題ありません。また、要素を削除することも問題はありません。

pairs(table)

• table … テーブル型

戻り値として、(next、table、nil)の三つ組みを返す関数で、一般for文とともに用いることで、テーブルの要素を巡回することができます。

以下の例では、テーブルtのすべての要素のキーと値をprintで表示します。

for k, v in pairs(t) do
  print(k, v)
end
    

pairsを呼び出している間にテーブルに変更を加えるときの注意点は、nextを参照してください。

pcall(func, ...)

• func … 関数型

関数funcを、保護されたモードで呼び出します。残りの引数は、fを呼び出すときの引数です。

通常は関数の実行中にエラーが発生するとスクリプト全体が停止しますが、保護されたモードでは、funcの実行中にエラーが発生しても、スクリプト全体は停止せず、pcallの戻り値としてエラーの発生状況を通知します。

pcallの最初の戻り値がtrueであったときは、funcの実行中にエラーは発生していません。pcallは残りの戻り値として、funcの戻り値を返します。

pcallの最初の戻り値がfalseであったときは、funcの実行中にエラーが発生しています。2番目の戻り値はエラーメッセージです。

print(...)

任意の数の引数を受け取り、それをコンソールに出力し、最後に改行します。引数はtostring関数により文字列表現に変換されます。

print関数の出力フォーマットを制御する方法はありません。フォーマットを制御しながら出力したい場合には、string.format関数とio.write関数を組み合わせて使用します。

rawequal(value1, value2)

• value1 … 任意の型
• value2 … 任意の型

メタメソッドを用いずに、value1とvalue2を比較します。trueまたはfalseを返します。

rawget(table, key)

• table … テーブル型
• key … 任意の型

メタメソッドを用いずに、テーブルtableのkeyをキーとする要素の値(table[key])を返します。

rawset(table, key, value)

• table … テーブル型
• key … nil以外の任意の型
• value … 任意の型

メタメソッドを用いずに、テーブルtableのkeyをキーとする要素(table[key])に値valueを代入します。関数の戻り値はtableです。

select(num, ...)

• num … 1以上の数値型(FIXNUM)、もしくは文字列"#"

numの値が1以上の数値Nのときには、残りの引数の先頭からN番目以降の引数をすべて返します。numが文字列"#"であったときは、残りの引数の数を返します。

select(3, "a", "b", "c", "d")    ⇒ "c", "d"
select("#", "a", "b", "c", "d")  ⇒ 4
    

selectは、関数の可変数引数を扱うときに使用すると便利です。以下の例では、可変数引数を持つ関数fの引数を一つずつ、関数gの引数として渡しています。

function f(...)
  for i = 1, select("#", ...) do
    g((select(i, ...)))
  end
end
    

setfenv(func, table)

• func … 関数型もしくは数値型(FIXNUM)
• table … テーブル型

funcが関数のときは、tableをその関数の環境として設定します。

funcが数値のときは、その値をスタックレベルとみなし、環境を返す関数を指定します。すなわち、以下のようになります。

• funcが1 … setfenvを呼び出している関数
• funcが2 … setfenvを呼び出している関数を呼び出している関数
• funcが3 … setfenvを呼び出している関数を呼び出している関数を呼び出している関数

funcが0のときは、グローバル環境を設定します。funcを省略したときには、1が与えられたものとします。

setfenvの戻り値は環境を設定した関数になります。グロバール環境を設定した場合には、戻り値はありません。

setmetatable(table, metatable)

• table … テーブル型
• metatable … テーブル型

テーブルtableにメタテーブルmetatableを設定します。metatableがnilの場合には、tableからメタテーブルを削除します。いずれの場合も、テーブルtableがもともとメタテーブルを持っていて、そのメタテーブルが__metatable要素を持っている場合にはエラーになります。

tonumber(value , base)

• value … 任意の型
• base … 数値型(2〜36)

valueを数値に変換します。valueが数値型であれば、そのままの値を返します。valueが文字列型であり、数値の文字列表現とみなせるものであれば、その数値を返します。その他の場合はnilを返します。

baseは文字列を数値に変換するときの基底数であり、2から36までが指定できます。たとえば、baseが2であれば文字列は2進数と解釈され、10であれば10進数、16であれば16進数と解釈されます。baseを省略したときには基底数は10とします。

baseが指定され、10もしくは16以外の数である場合は、関数の戻り値は-2147483648〜2147483647の範囲内にある必要があります。baseが省略されるか、10または16が指定されている場合には、数値型で表せる任意の数値を戻り値として返せます。

また、文字列の先頭に"0x"がある時には、特別な扱いがされます。この場合、基底数が10であっても、"0x"に引き続く文字列は16進数であると解釈されます。基底数が16の場合も同様に"0x"を除いた部分を16進数と解釈します。基底数が10もしくは16以外のときには、文字列の先頭の"0x"を16進数を示す記号とは解釈しません。よって、基底数が34未満で文字"x"が数値の表現とはならない場合には、"0x"があると数値として解釈できず、nilを返します。

a = tonumber(11)       --- a = 11
a = tonumber("11")     --- a = 11
a = tonumber("11", 2)  --- a = 3
a = tonumber("11", 16) --- a = 17
a = tonumber("0x11")   --- a = 17
    

tostring(value)

• value … 任意の型

valueをそれぞれの型に応じたフォーマットで文字列に変換します。

a = tostring(11)  --- a = "11"
a = tostring(true) --- a = "true"
a = tostring(false) --- a = "false"
a = tostring(nil) --- a = "nil"
a = tostring({}) --- a = "table: 00907590"
    

type(value)

• value … 任意の型

valueの型を文字列で返します。それぞれの型で返される文字列は以下のとおりです。

• 数値型(FIXNUM) … "number"
• 数値型(BIGNUM) … "number", "bignum"
• 文字列型 … "string"
• 論理型 … "boolean"
• nil型 … "nil"
• テーブル型 … "table"
• 関数型 … "function"
• スレッド型 … "thread"
• ユーザーデータ型 … "userdata"

unpack(table , i , j)

• table … テーブル型
• i, j … 数値型(FIXNUM)

テーブルtableの、キーiからjまでの要素の値を複数値として返します。iがjより大きい場合には何も返しません。該当するキーに値がないところはnilが返ります。

iを省略した場合は1、jを省略した場合は長さ演算子#で定義されるテーブルの要素数になります。

xpcall(func, handler)

• func … 関数型
• handler … 関数型

xpcallはpcallとよく似ており、エラー処理関数を指定できるところだけが異なります。

xpcallは、handlerをエラー処理関数として関数funcを保護モードで呼び出します。funcの実行中にエラーが発生した場合には、handlerが呼び出されます。

xpcallの最初の戻り値がtrueだった場合には、funcの実行中にエラーは発生していません。xpcallの2番目以降の戻り値としてfuncの戻り値が返されます。

xpcallの最初の戻り値がfalseだった場合には、funcの実行中にエラーが発生し、handlerが呼び出されています。xpcallの2番目以降の戻り値はhandlerの戻り値です。

グローバル変数

定義済みのグローバル変数を列挙します。

文字列操作

string.byte(str, i, j)

• str … 文字列型
• i, j … 数値型(FIXNUM)

文字列strのi文字目からj文字目までの文字を、それぞれ内部文字コードの数値に変換し、複数値として返します。

文字列の先頭は1文字目であり、iを省略したときには1となります。jを省略したときには、iと同じ値、つまり、戻り値はi文字目の1文字だけとなります。

ヤマハルーターのLuaスクリプトでは、文字列の内部コードはASCIIおよびシフトJISです。

a, b = string.byte("ab", 1, 2) -- a=97, b=98
a, b = string.byte("ab")       -- a=97, b=nil
a, b = string.byte("ab", 2)    -- a=98, b=nil
a, b = string.byte("あ", 1, 2) -- a=130, b=160
    

string.char(...)

与えられた引数の数と同じ長さの文字列で、それぞれの文字は対応する引数の値を内部コードとする文字となっているものを返します。引数は、0個以上の数値(FIXNUM)でなくてはなりません。引数が0個のときは長さ0の文字列を返します。

ヤマハルーターのLuaスクリプトでは、文字列の内部コードはASCIIおよびシフトJISです。

s = string.char(97, 98)   -- s = "ab"
s = string.char(130, 160) -- s = "あ"
s = string.char()         -- s = ""
    

string.dump(func)

• func … 関数型

与えられた関数のバイナリ表現を含む文字列を返します。この文字列は、loadstringの引数として与えることができ、その場合、関数のコピーを得ることができます。関数は上位値を持たないLua関数である必要があります。

string.find(str, pattern, init, plain)

• str … 文字列型
• pattern … 文字列型または正規表現オブジェクト
• init … 数値型(FIXNUM)
• plain … 論理型

文字列strの先頭から、パターンpatternに合致する部分を探します。合致する部分が見つかったときには、文字列の先頭が1として、その部分の先頭、最後の位置の2つの数値を戻り値として返します。合致する部分が見つからないときにはnilを返します。

また、patternがキャプチャを持っている場合には、キャプチャされた文字列は、位置を表す2つの数値に続く戻り値として返されます。

3つ目の引数initを指定した場合には、パターンpatternを探し始める場所を先頭ではなく、init文字目から始めることができます。initには負の数も指定でき、その場合は末尾から何文字目、という形になります。

4つめの引数plainにtrueを指定した場合には、patternはパターンではなく単なる文字列であると解釈されます。したがって、patternに単純に一致する部分を探すようになります。

patternが正規表現オブジェクトで、かつplainがtrueの場合にはnilを返します。

a, b = string.find("ABCDE", "BC")        -- a=2, b=3
a, b = string.find("ABCDE", "%a*")       -- a=1, b=5
a, b = string.find("ABCDE", /\a*/)       -- a=1, b=5
a, b = string.find("あいうえお", "いう") -- a=3, b=6
a, b, c = string.find("ABCDE", "B(.)D")  -- a=2, b=4, c="C"
    

string.format(format, ...)

• format … 文字列型

引数の値を文字列formatの指示に従い整形した文字列を返します。C言語のsprintf関数によく似た関数です。

formatは、残りの引数を文字列に変換するための変換指示句を含む文字列です。変換指示句は、パーセント%で始まり、変換指示子(d、x、X、c、s、q、%、z)で終わります。変換指示句によって出力される文字列のことをフィールドと呼びます。パーセントと変換指示子の間には、フラグ、フィールド幅、精度をこの順で置いてもよいことになっています。

string.formatは、formatを読み出しながら、その指示に従いフィールドを生成していきます。変換指示句ではない文字は、そのまま出力されます。

formatに変換指示句があったときには、対応する順番の引数を読み出し、変換指示句の指示通りの文字列に変換して出力します。変換指示句はそれぞれ特定の型の引数を要求し、それ以外の型の引数が与えられたときはエラーとなります。

フラグは、引数の変換の仕方を指定します。以下のフラグが使用できます。

#

o変換の場合、出力結果の先頭が必ず0になるよう、必要であれば先頭に0が補われます。x、X変換の場合には、値が0でなければ先頭に0xまたは0Xが補われます。

0

数値の変換(d、x、X)の場合に、変換した値の左側を空白文字ではなく0で埋めます。フラグ0とフラグ-が同時に指定された場合には、フラグ0は無視されます。

-

変換した文字列を、フィールドの中で左揃えにします。このフラグが指定されていない場合には右揃えとなります。

フィールド幅は、変換後の文字列を出力する最小の幅を10進数の数値で指定します。変換後の文字列長がフィールド幅より短い場合は文字列の左側(フラグ-が指定された場合は右側)が空白文字または0で埋められます。文字列長がフィールド幅より長い場合には、文字列は切り詰められずそのまま出力されます。

精度は、ピリオド.とそれに続く10進数という形で指定します。数値の変換(d、x、X)の場合には、出力される最小の桁数を指定します。文字列変換(s)の場合には、文字列から出力される最大文字数を指定します。

変換指示子には以下の種類があります。

d

数値型の引数を、10進表記に変換します。
負数の場合は先頭にマイナス-を追加します。

x、X

数値型の引数を、16進表記に変換します。
xの場合はabcdefを、Xの場合はABCDEFを使用します。
負数の場合は、4294967296(10進)を加算した正数として表示します。

c

数値型の引数を、その値を256で割った余りを内部コードとする文字に変換します。

s

文字列型の引数を、文字列の先頭から終端まで出力します。精度が指定されている場合には、その文字数だけが出力されます。

q

文字列型の引数を、文字列の先頭から終端まで出力します。そのときに、Lua言語のインタプリタが読み出せる形に、ダブルクォート、改行、NUL文字、バックスラッシュが適切にエスケープされます。

%

文字%を出力します。変換される引数はありません。フラグ、フィールド幅、精度を指定してはならず、変換指定句全体は必ず%%という形になります。

s = string.format("%d, %x", 10, 10)                    -- s="10, a"
s = string.format("%dab%d", 10, 20)                    -- s="10ab20"
s = string.format("[%4d], [%-4d], [%04d]", 10, 10, 10) -- s="[  10], [10  ], [0010]"
    

string.gmatch(str, pattern)

• str … 文字列型
• pattern … 文字列型または正規表現オブジェクト

文字列strに対して、呼び出されるごとにパターンpatternのキャプチャを順に返すイテレータ関数を返します。パターンにキャプチャが含まれていないときには、イテレータ関数の戻り値はパターンに合致する文字列全体となります。

string.gmatchは一般for文とともに使うことで、文字列から条件に合う部分を次々に抜き出して処理することができます。

以下の例では、文字列から単語を抜き出し、1行に一つずつ表示しています。

s = "hello world from Lua"
for w in string.gmatch(s, "%a+") do
  print(w)
end
    

また、次の例では、key=value形式の文字列を探し、テーブルtにそれを設定しています。

t = {}
s = "from=world, to=Lua"
for k, v in string.gmatch(s, "(%w+)=(%w+)") do
  t[k] = v
end
    

string.gsub(str, pattern, repl, n)

• str … 文字列型
• pattern … 文字列型または正規表現オブジェクト
• repl … 文字列型、テーブル型、関数型のいずれか
• n … 数値型(FIXNUM)

文字列strに対して、パターンpatternに合致する部分をすべて引数replの指示通りに置き換えた新しい文字列と、patternが見つかった数を返します。文字列strは一切変更されません。

4番目の引数nを指定した場合には、置き換えは最初のn個だけ実行されます。省略した場合は、見つかった置き換えはすべて実行されます。

replが文字列型の場合、replそのものが置き換え文字列となります。replの中の以下の文字列は特別な意味を持ちます。

%0

patternに合致する部分全体を表わす。

%1〜%9

patternの中の、指定した順番のキャプチャに合致する文字列を表わす。

%%

パーセント文字そのものを表わす。

replがテーブル型の場合、pattern中の最初のキャプチャをキーとするreplの要素の値が置き換え文字列となります。patternがキャプチャを含まない場合、patternに合致する部分全体がキーとなります。

replが関数型の場合、pattern中のすべてのキャプチャを引数としてreplが呼び出され、その戻り値が置き換え文字列となります。patternがキャプチャを含まない場合、patternに合致する部分全体が引数となります。

replがテーブル型もしくは関数型の場合、テーブルの要素の値もしくは関数の戻り値が文字列型であれば、それがそのまま置き換え文字列となります。数値型(FIXNUM)の場合は、文字列に変換したものが置き換え文字列になります。

テーブルの要素の値もしくは関数の戻り値がfalseあるいはnilの場合には、置き換えは実行されず、元の文字列がそのまま残ります。他の値になった場合には、エラーです。

x, y = string.gsub("HELLO world", /o/i, "o")
-- x = "HELLo world", y = 2

x, y = string.gsub("hello world", "(%w+)", "%1 %1")
-- x = "hello hello world world", y = 2

x, y = string.gsub("hello world from Lua", /(\w+)\s*(\w+)/, "%2 %1")
-- x = "world hello Lua from", y = 2

t = { name = "lua", version = "5.1" }
x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
-- x = "lua-5.1.tar.gz"

function f(s)
  if s == "hello" then
    return "bye"
  elseif s == "world" then
    return "universe"
  else
    return "unknown"
  end
end
x = string.gsub("hello world", "(%w+)", f) -- x = "bye universe"
    

string.len(str)

• str … 文字列型

文字列strの長さを返します。Lua言語での「文字列の長さ」はバイト長です。空文字列""の長さは0となります。

x = string.len("ABCDE")      -- x = 5
x = string.len("")           -- x = 0
x = string.len("あいうえお") -- x = 10
    

string.lower(str)

• str … 文字列型

文字列str中の英大文字を小文字に変換した文字列を新しく作成し、それを返します。str自体は一切変更されません。

変換対象となるのはASCIIコードの範囲内の英大文字だけです。シフトJISの英大文字は変換されません。

x = string.lower("AB01CD")     -- x = "ab01cd"
x = string.lower("ＡＢ01ＣＤ") -- x = "ＡＢ01ＣＤ"
    

string.match(str, pattern, n)

• str … 文字列型
• pattern … 文字列型または正規表現オブジェクト
• n … 数値型(FIXNUM)

文字列strからパターンpatternに合致する部分を先頭から探し、見つかった場合にはpattern中のキャプチャをすべて返します。patternにキャプチャが存在しない場合には、patternに合致する部分全体の文字列を返します。patternに合致する部分が見つからない場合にはnilを返します。

3番目の引数nを指定した場合には、patternはstrのn文字目から探し始めます。省略した場合は1文字目からとなります。nには負の数も指定でき、その場合は末尾から何文字目、という形になります。

patternが正規表現オブジェクトで、オプションとしてgが指定されているときには、文字列中に見つかった部分で、重複していないものをすべて返します。その他の場合には、最初に見つかった部分だけを返します。

x = string.match("hello world", "%w+")    -- x = "hello"
x = string.match("hello world", " (%w+)") -- x = "world"
x = string.match("hello world", "%w+", 2) -- x = "ello"
x,y,z,w = string.match("hello world", /\w\w/g) -- x = "he", y = "ll", z = "wo", w = "rl"
x = {string.match("hello world", /\w\w/g)} -- x = { "he", "ll", "wo", "rl" }
    

string.regexp(str, option)

• str … 文字列型
• option … 文字列型

この関数は_RT_LUA_VERSIONが"1.03"以降のファームウェアで使用することができます。

文字列strを正規表現とみなして、それに対応する正規表現オブジェクトを返します。正規表現オブジェクトは、string.find関数やstring.match関数、string.gmatch関数、string.gsub関数、string.split関数、rt.syslogwatch関数のパターンとして利用できます。

文字列に正規表現として誤りがある場合は、nilとエラー文字列を返します。

文字列optionは、正規表現のコンパイルオプションを指定します。optionは以下の文字の組み合わせで指定します。

• i ... 英文字の大文字、小文字を区別しない。
• s ... 「.」が改行文字の直後にも合致する。
• x ... 正規表現中の空白文字と「#」から改行までを無視する。
• m ... 「^」「$」が文字列中の改行文字の前後にも合致する。
• U ... 「*」「+」などの長さ指定記号ができるだけ短い文字列に合致しようとする。一方、「*?」「+?」などはできるだけ長い文字列に合致しようとする。

上記以外の文字がoptionに含まれていた場合は、正規表現オブジェクトが利用されるときのオプションとなります。

string.regexp関数は、正規表現糖衣構文として記述することで呼び出すことも可能です。

x = string.regexp("hello", "i")
x = /hello/i
    

string.rep(str, n)

• str … 文字列型
• n … 数値型(FIXNUM)

文字列strをn個、連結した文字列を返します。

x = string.rep("ab", 5) -- x = "ababababab"
    

string.reverse(str)

• str … 文字列型

文字列strを逆順にした文字列を返します。なお、シフトJISの文字列を指定することはできません。

x = string.reverse("hello world") -- x = "dlrow olleh"
    

string.split(str, pattern, n)

• str … 文字列型
• pattern … 文字列型または正規表現オブジェクト
• n … 数値型(FIXNUM)

この関数は_RT_LUA_VERSIONが"1.03"以降のファームウェアで使用することができます。

文字列strを、パターンpatternに合致する部分で分割したものを返します。返される文字列群に、patternに合致する部分は含まれません。

4番目の引数nを指定した場合には、分割は最初のn回だけ実行されます。省略した場合は、見つかった分割はすべて実行されます。

x = { string.split("hello world", /\s+/) } -- x = { "hello", "world" }

str = "hello world"
for w in each(str:split(/\s+/)) do
    print(w)
end
    

string.sub(str, i, j)

• str … 文字列型
• i, j … 数値型(FIXNUM)

文字列strのi文字目からj文字目までの部分文字列を返します。i、jには負の数を指定することもでき、その場合は末尾から何文字目、という形になります。jを省略した場合には-1、つまりstrの末尾までとなります。

x = string.sub("ABCDE", 2, 4)  -- x = "BCD"
x = string.sub("ABCDE", 3)     -- x = "CDE"
x = string.sub("ABCDE", 2, -2) -- x = "BCD"
x = string.sub("ABCDE", -2)    -- x = "DE"
    

string.upper

• str … 文字列型

文字列str中の英小文字を大文字に変換した文字列を新しく作成し、それを返します。str自体は一切変更されません。

変換対象となるのはASCIIコードの範囲内の英小文字だけです。シフトJISの英小文字は変換されません。

x = string.upper("ab01cd")     -- x = "AB01CD"
x = string.upper("ａｂ01ｃｄ") -- x = "ａｂ01ｃｄ"
    

パターン

パターンは、string.match関数などで文字列を検索するために使用されるものです。Lua独自のパターンと正規表現が利用できます。

正規表現は_RT_LUA_VERSIONが"1.03"以降のファームウェアで扱うことができます。

パターンは、特別な意味を持つ特殊文字と、それ以外の通常文字から構成されます。通常文字は、それ自身に合致します。たとえば、aは、a自身に合致します。特殊文字を含まないパターンは、その文字列そのままが対象文字列中から検索されます。

パターンで使用する特殊文字は以下のとおりです。

正規表現の場合は、[…]による文字集合の中で、以下に示すPOSIX文字集合が利用できます。

[:NAME:]とするとNAMEの文字集合となり、[:^NAME:]とすると補集合となります。

キャプチャ

パターンは、カッコで囲まれたサブパターンを含むことができ、これをキャプチャと呼びます。パターンが合致したときには、キャプチャに相当する部分文字列は保存され、後で使用することができるようになります。キャプチャの順序は開きカッコの出現順です。たとえば、パターン"(a*(.)%w(%s*))"において、最初のキャプチャはa*(.)%w(%s*)に相当する部分文字列であり、2番目のキャプチャは.に、3番目のキャプチャは%s*に相当する部分文字列となります。

Luaパターンの特殊なケースとして、空っぽのキャプチャ()は、その場所の文字列の中での位置をキャプチャします。たとえば、パターン"()aa()"を文字列"flaaap"に適用した場合、3と5がキャプチャされます。この空っぽのキャプチャは正規表現では使えません。

正規表現糖衣構文

正規表現は、Luaの正式な型ではなく、ユーザーデータ型の一種です。正規表現オブジェクト(正規表現を実現するためのデータ等が格納されたユーザーデータ型の値)は、string.regexp関数の戻り値として与えられますが、以下のような記述方法で簡潔に表現することも可能です。

正規表現と正規表現糖衣構文は_RT_LUA_VERSIONが"1.03"以降のファームウェアで扱うことができます。

• /  /で正規表現文字列(string.regexp関数の第一引数)を囲み、後ろの/の直後にオプション文字列(string.regexp関数の第二引数)を置く
• 正規表現文字列、オプション文字列ともに、引用符は付けない
• 正規表現文字列中に/を含める場合は、\/と記述する。\そのものは\\と記述する
• 正規表現文字列では、常に式展開が行われる
• 正規表現文字列は複数行にわたって記述することもできる。最初の/の直後が改行だった場合、長い文字列と同じようにその改行は無視される
• オプション文字列には、英文字だけが許される
• オプション文字列が空文字列の場合は、後ろの/の後ろには何も書かない

/abc[def]ghi/i <==> string.regexp([=[abc[def]ghi]=], "i")
    

関数で文字列を一つだけ引数にとる場合には関数名の後ろのカッコが省略できますが、引数が正規表現の場合にはカッコは省略できません。正規表現糖衣構文の先頭のスラッシュ(/)が割り算記号であると解釈されるためです。

str = "hello world"
a, b = str:split(/\s/)  --- 成功
a, b = str:split "%s"   --- 成功
a, b = str:split /\s/   --- エラー、/ は割り算記号として扱われる
    

正規表現糖衣構文は、数値や文字列のようにデータを直接プログラム中に記述しているわけではなく、あくまでstring.regexp関数の呼び出しを簡潔に記述しているだけです。正規表現文字列等にエラーがある場合でも、実際にその文を実行してみるまではエラーは分かりません。

テーブル操作

table.concat(tbl, sep, i, j)

• tbl … テーブル型
• sep … 文字列型
• i、j … 数値型(FIXNUM)

テーブルを配列として扱う関数です。

テーブルtblの各要素の値を、tbl[i]からtbl[j]まで、sepを区切り文字として連結した文字列を返します。tbl[i]からtbl[j]までの値は文字列型か数値型でなければならず、数値型の場合はtonumber関数を適用した文字列を連結します。

sepを省略した場合は空文字列となります。iを省略した場合は1、jを省略した場合はtblの長さとなります。もし、jの方がiより大きい場合は、戻り値は空文字列となります。

t = { "hello", "world", "from", "Lua" }
s = table.concat(t, ";") -- s = "hello;world;from;Lua"
    

table.insert(tbl, pos, value)

• tbl … テーブル型
• pos … 数値型(FIXNUM)
• value … 任意の型

テーブルを配列として扱う関数です。

値valueを持つ要素を、テーブルtblのpos番目に挿入します。pos番目以降の要素は一つずつ後ろにずらされます。posを省略したときには、要素はテーブルの最後に追加されます。

table.insertは戻り値を何も返しません。。

t = { "A", "B" }
table.insert(t, 2, "C") -- t = { "A", "C", "B" }
table.insert(t, "D")    -- t = { "A", "C", "B", "D" }
    

table.maxn(tbl)

• tbl … テーブル型

テーブルtblの持つ要素のキーのうち、正の数値(FIXNUM)であるものの中で最大のものを返します。tblが正の数値(FIXNUM)のキーの要素を持たない場合は0を返します。

この関数は結果を求めるためにテーブルを線形にすべて巡回します。そのため、大きなテーブルに対しては実行時間が長くかかります。テーブルが配列である場合は、長さ演算子#を用いたほうがよいでしょう。

t = { [1] = "A", [100] = "B", x = "C", [3] = "D" }
x = table.maxn(t) -- x = 100
    

table.remove(tbl, pos)

• tbl … テーブル型
• pos … 数値型(FIXNUM)

テーブルを配列として扱う関数です。

テーブルtblからpos番目の要素を削除し、その後ろの要素を一つずつ前に詰めます。posを省略したときには、最後の要素を削除します。

table.removeは戻り値を何も返しません。

table.sort(table, comp)

• tbl … テーブル型
• comp … 関数型

テーブルを配列として扱う関数です。

テーブルtblをソートします。ソートの対象となるのは、tbl[1]からtbl[n](ただし、n = #tbl)です。compは、ソートの際の大小比較に用いる関数であり、tblの要素の値を2つ引数にとり、最初の引数が2番目の引数より小さかったらtrue、そうでなければfalseを返さなければなりません。compが省略された場合は、通常の比較演算子である<に相当する関数が使用されます。

ソートのアルゴリズムは安定ではありません。すなわち、値が等しいとみなせる要素が複数あったときに、ソートの前後でそれらの順序は変わっているかもしれません。

table.sortは戻り値を何も返しません。

t = { 2, 4, 3, 1 }
table.sort(t)     -- t = { 1, 2, 3, 4 }
    

数学関数

_RT_LUA_VERSIONが"1.01"以降のファームウェアで使用可能です。

math.abs(x)

• x … 数値型

xの絶対値を返します。

x = -1
y = math.abs(x)     -- y = 1
    

math.fmod(x, y)

• x, y … 数値型

除算の丸め方向を、除算演算子(/)とは異なり、0方向へ丸めるとした場合の、xをyで除したときの剰余を返します。

x = 5
y = -2
z1 = 5 % -2           -- z1 = -1
z2 = math.fmod(x, y)  -- z2 = 1
    

math.max(v, v...)

• v … 数値型

引数のうち、最大の値を返します。

x = 5
y = -2
z = 3
w = 1
r = math.max(x, y, z, w)    -- r = 5
    

math.min(v, v...)

• v … 数値型

引数のうち、最小の値を返します。

x = 5
y = -2
z = 3
w = 1
r = math.min(x, y, z, w)    -- r = -2
    

math.random(m, n)

• m, n … 数値型(1〜4294967295)

m以上、n以下の範囲の擬似乱数を返します。擬似乱数の種はmath.randomseed関数で指定します。

mを省略した場合は1とみなします。nは省略できません。

math.randomseed(os.time())
r = math.random(100)        -- r = 1〜100
r = math.random(1000, 2000) -- r = 1000〜2000
    

math.randomseed(s)

• s … 数値型(1〜4294967295)

math.random関数が生成する擬似乱数の種を指定します。

擬似乱数の種が同一の場合、math.random関数はまったく同じ乱数列を返します。乱数として意味を持たせるためには、以下の例のようにos.time関数を使うなどして、スクリプトの起動ごとに異なる種が与えられるようにしてください。

math.randomseed(os.time())
r = math.random(100)        -- r = 1〜100
r = math.random(1000, 2000) -- r = 1000〜2000
    

入出力

入出力ライブラリには2つの種類があります。一つは、ファイルハンドルを明示せず、デフォルトの入出力ファイルに対して操作を行うものであり、もう一つはファイルハンドルを明示して操作を行うものです。

ファイルハンドルとは、io.input、io.output、io.openの3つの関数の戻り値であり、ライブラリがファイルを操作する場合に必要な情報をセットしたuserdata型のデータです。ファイルハンドルを明示しない操作では、対象となるファイルはio.inputおよびio.outputで指定され、テーブルioの要素である関数によって入出力動作が行われます。一方、ファイルハンドルを明示する操作は、io.openの戻り値であるファイルハンドルに対するメソッドとして定義されています。

標準のLua言語では、あらかじめ定義されたファイルハンドルとしてio.stdin、io.stdout、io.stderrの3つが利用できますが、ヤマハルーターではこれらは利用できません。また、io.inputやio.outputも、これらを初期値として持つことはできず、初期値は何もファイルに結び付けられていない状態となります。

file:close()

ファイルハンドルfileに対するメソッドであり、fileをクローズします。

fileのクローズに成功した場合はtrueを返します。そうでない場合は、nil、エラーメッセージ(文字列)、エラーコード(数値)の3つを返します。

f = io.open("FILE.txt")
f:read(), f:write(),…
f:close()
    

io.close(file)

• file … ファイルハンドル

ファイルハンドルfileをクローズします。fileを省略した場合は、io.outputで指定したデフォルト出力ファイルをクローズします。

ファイルのクローズに成功した場合はtrueを返します。そうでない場合は、nil、エラーメッセージ(文字列)、エラーコード(数値)の3つを返します。

io.output("FILE.txt")
io.write(),…
io.close()
    

file:flush()

ファイルハンドルfileに対するメソッドであり、fileに対して行われた書込み操作のうち、まだ実際にはメディア等に書き込まれておらず、OS内のバッファにとどまっているデータを、メディア等に書き込みます。

書き込むべきデータが残っていなかったか、データの書き込みに成功した場合はtrueを返します。そうでない場合は、nil、エラーメッセージ(文字列)、エラーコード(数値)の3つを返します。

f = io.open("FILE.txt", "w")
f:write(),…
f:flush()
    

io.flush()

io.outputで指定されたデフォルト出力ファイルに対して行われた書込み操作のうち、まだ実際にはメディア等に書き込まれておらず、OS内のバッファにとどまっているデータを、メディア等に書き込みます。

書き込むべきデータが残っていなかったか、データの書き込みに成功した場合はtrueを返します。そうでない場合は、nil、エラーメッセージ(文字列)、エラーコード(数値)の3つを返します。

io.output("FILE.txt")
io.write(),…
io.flush()
    

io.input(file)

• file … 文字列型もしくはファイルハンドル

fileが文字列の場合は、それをファイル名とみなしてオープンし、標準入力ファイルとします。fileがファイルハンドルの場合は、それをそのまま標準入力ファイルとします。いずれの場合も、新しく利用できる標準入力ファイルのファイルハンドルを返します。fileが省略された場合は、現在利用できる標準入力ファイルのファイルハンドルを返します。

指定したファイルがオープンできないなどの場合はエラーとなります。

io.input("FILE.txt")
io.read()…
    

file:lines()

ファイルハンドルfileに対するメソッドであり、fileから一行ずつ読み出してくるイテレータ関数を返します。ファイルの終端に達したときには、イテレータ関数はnilを返しますがファイルはクローズしません。

一般for文と一緒に使うことで、ファイルを一行ずつ処理するコードを以下のように書くことができます。

f = io.open("FILE.txt")
for line in f:lines() do
  -- "FILE.txt"を一行ずつ処理するコード
end
    

io.lines(filename)

• filename … 文字列型

filenameを指定した場合は、そのファイルをオープンしてから、ファイルの内容を一行ずつ返すイテレータ関数を返します。ファイルの終端に達したときには、イテレータ関数はnilを返し、ファイルをクローズします。

filenameを省略した場合は、io.inputで指定するデフォルト入力ファイルに対して、一行ずつ内容を返すイテレータ関数を返します。ファイルの終端に達したときには、イテレータ関数はnilを返しますがファイルはクローズしません。

一般for文と一緒に使うことで、ファイルを一行ずつ処理するコードを以下のように書くことができます。

for line in io.lines("FILE.txt") do
  -- "FILE.txt"を一行ずつ処理するコード
end
    

io.open(filename, mode)

• filename … 文字列型
• mode … 文字列型

ファイルfilenameをmodeに指定されたモードでオープンし、ファイルハンドルを返します。ファイルのオープンに失敗した場合は、nil、エラーメッセージ(文字列)、エラーコード(数値)の3つを返します。

modeは文字列であり、以下のいずれかでなければなりません。modeを省略した場合は、"r"であると解釈されます。

テキストモードでは、以下の通り改行コードの変換処理が行われます。

• 読み出しの場合、ファイルに含まれる文字列の"\r\n"を"\n"に変換します。
• 書き込みおよび追記の場合、入力された文字列の"\n"を"\r\n"に変換します。

改行コードを変換しない場合はバイナリモードでオープンします。

--[[
ファイルをコピーする関数
source, destination: ファイル名を表す文字列
]]
function file_copy(source, destination)
  local fhs, fhd, buf, estr, ecode
  fhs, estr, ecode = io.open(source, "r")
  if fhs == nil then
    return nil, estr, ecode
  end
  fhd, estr, ecode = io.open(destination, "w")
  if fhd == nil then
    fhs:close()
    return nil, estr, ecode
  end
  repeat
    buf = fhs:read(1000)
    if buf then
      fhd:write(buf)
    end
  until buf == nil
  fhd:close()
  fhs:close()
  return true
end
    

io.output(file)

• file … 文字列型もしくはファイルハンドル

fileが文字列の場合は、それをファイル名とみなしてオープンし、標準出力ファイルとします。fileがファイルハンドルの場合は、それをそのまま標準出力ファイルとします。いずれの場合も、新しく利用できる標準出力ファイルのファイルハンドルを返します。fileが省略された場合は、現在利用できる標準出力ファイルのファイルハンドルを返します。

指定したファイルがオープンできない場合はエラーとなります。

io.output("FILE.txt")
io.write("Hello, world")  -- "FILE.txt"に、"Hello, world"と書き込む
    

file:read(format, ...)

• format … 文字列型もしくは数値型(FIXNUM)

ファイルハンドルfileに対するメソッドであり、fileからformatに沿った形でデータを読み出して返します。データが読み出せた場合は、それを文字列として返しますが、データが読み出せない場合はnilを返します。戻り値の個数は、引数の個数と同じです。

formatは以下のいずれかである必要があります。formatを省略した場合は、"*l"が一つだけ指定されたものとみなされます。

• "*a" : ファイル全体を読み込み、文字列として返す。ファイルの終端にあるときには空文字列を返す。
• "*l" : 次の一行を読み込み、文字列として返す。ファイルの終端にあるときにはnilを返す。
• 数値 : 指定したバイト数だけ文字を読み込み、文字列として返す。ファイルの終端にあるときにはnilを返す。数値が0の場合は、何も読み込まずに空文字列を返すが、ファイルの終端であるときだけはnilを返す。

io.read(format, ...)

• format … 文字列型もしくは数値型(FIXNUM)

io.inputで指定する標準入力ファイルに対して読み出しを行います。formatの意味や戻り値などはすべてfile:readと同じです。

io.type(file)

• file … 任意の型

fileがファイルハンドルであるかどうかを調べます。

fileがオープンされているファイルに対するファイルハンドルである場合は、文字列"file"を返します。クローズされているファイルに対するファイルハンドルである場合は、文字列"closed file"を返します。fileがファイルハンドルでない場合には、nilを返します。

file:write(value, ...)

• value … 文字列型

ファイルハンドルfileに対するメソッドであり、指定したデータをfileに文字列として書き出します。

io.write(value, ...)

• value … 文字列型

指定したデータをio.outputで指定した標準出力ファイルに文字列として書き出します。

ビット演算

_RT_LUA_VERSIONが"1.01"以降のファームウェアで使用可能です。

bit.band(v, v...)

• v … 数値型(0〜4294967295)

与えられた引数32ビット符号無し整数とみなし、そのビットごとの論理積をとった値を返します。

x = 0x5a
y = 0xaf
z = bit.band(x, y) -- z = 0x0a
    

bit.btest(v, v...)

• v … 数値型(0〜4294967295)

与えられた引数32ビット符号無し整数とみなし、そのビットごとの論理積をとった値が0であればfalseを、そうでなければtrueを返します。

x = 0x01
y = 0x02
z = bit.btest(x, y)   -- z = false

x = 0x01
y = 0x03
z = bit.btest(x, y)   -- z = true
    

bit.bor(v, v...)

• v … 数値型(0〜4294967295)

与えられた引数を32ビット符号無し整数とみなし、そのビットごとの論理和をとった値を返します。

x = 0x5a
y = 0xa5
z = bit.bor(x, y)  -- z = 0xff
    

bit.bxor(v, v...)

• v … 数値型(0〜4294967295)

与えられた引数を32ビット符号無し整数とみなし、そのビットごとの排他的論理和をとった値を返します。

x = 0x5a
y = 0xff
z = bit.bxor(x, y)  -- z = 0xa5
    

bit.bnot(v)

• v … 数値型(0〜4294967295)

与えられた引数を32ビット符号無し整数とみなし、そのビットごとの論理否定をとった値を返します。

x = 0x5a
z = bit.bnot(x, y)  -- z = 0xffffffa5
    

bit.bshift(v, s)

• v … 数値型(0〜4294967295)
• s … 数値型(FIXNUM)

vを32ビット符号無し整数とみなし、sだけシフトした値を返します。sの符号が正の場合は左シフト、負の場合は右シフトとなります。

sの絶対値が32以上の場合は、戻り値は0となります。

x = 0x5a
y = 4
z = bit.bshift(x, y)  -- z = 0x05a0

x = 0x05a0
y = -8
z = bit.bshift(x, y)  -- z = 0x0005
    

bit.brotate(v, s)

• v … 数値型(0〜4294967295)
• s … 数値型(-31〜31)

vを32ビット符号無し整数とみなし、sだけ回転した値を返します。sの符号が正の場合は左方向への回転、負の場合は右方向への回転となります。

x = 0x12345678
y = 4
z = bit.brotate(x, y)  -- z = 0x23456781

x = 0x12345678
y = -8
z = bit.brotate(x, y)  -- z = 0x78123456
    

ヤマハルーターAPI

基本ライブラリ

rt.command(cmd)

• cmd … 文字列型

文字列cmdをルーターのコマンドとして実行します。cmdの長さは4095バイト以内でないといけません。

戻り値には、コマンドの実行結果が返ります。最初の戻り値として、コマンドが正しく実行できればtrueが、何らかのエラーが発生していればfalseが返ります。2つ目の戻り値には、コマンドの出力、あるいはエラーメッセージが文字列として返ります。何も返す文字列がない場合にはnilが返ります。2つ目の戻り値の文字列の文字コードは、console characterコマンドの設定に従います。

ルーターのコマンド出力では、改行は"\r\n"の2文字で表されます。

rt.commandでは、すべてのコマンドを管理ユーザー権限で実行します。

以下のコマンドは、rt.commandからは実行できません。

• administrator
• administrator password
• administrator password encrypt
• clear configuration
• cold start
• copy config
• copy exec
• delete config
• delete exec
• execute batch
• exit
• http revision-up go
• less で始まるコマンドや ’|’ で less を連結したコマンド
• login password
• login password encrypt
• lua use
• luac
• mail notify
• mail server pop
• mail server smtp
• mail server timeout
• mail template
• quit
• remote setup
• telnet

以下のコマンドは、通常とは動作が異なります。

• ping、ping6コマンド

  COUNTオプションを指定しなかった場合、通常であれば、Ctrl-Cで中断されるまでICMP Echoパケットを送信し続けますが、rt.commandから実行された場合には、COUNTオプションを省略するとCOUNTオプションに1が指定されたものとして、1回だけICMP Echoを送信します。COUNTオプションがあれば、指定回数だけICMP Echoを送信します。

rtn, str = rt.command("show status lan2")
-- rtn = true
-- str = [[
LAN2
説明:
IPアドレス:		192.168.2.1/24
イーサネットアドレス:	00:a0:de:12:34:56
動作モード設定:		Auto Negotiation (Link Down)
最大パケット長(MTU):	1500 オクテット
…
]]
rtn, str = rt.command("show status tunnel 9999")
-- rtn = false
-- str = "エラー: パラメータが範囲を越えています\r\n"
    

rt.mail(param)

• param … テーブル型

テーブルparamで指定したパラメータに従ってメールを送信します。

rt.mailが呼び出されると、1秒待機してからメールを送信します。メール送信が完了すると、trueを返します。サーバーと通信できない場合などにはfalseを返します。

paramに指定できるパラメータは以下のとおりです。

cmd = "show techinfo"
mail_table = {
  smtp_address = "mx.example.jp",
  from = "foo@example.jp",
  to = "bar@example.jp",
  subject = cmd
}

rtn, str = rt.command(cmd)
if rtn and str then
  mail_table.text = cmd .. "の実行結果\r\n\r\n" .. str
  rt.mail(mail_table)
end

    

rt.sleep(seconds)

• seconds … 数値型(1〜864000)

rt.sleepを呼び出すと、seconds秒後に関数から返ってきます。secondsは1から864000の間の数値でなくてはなりません。

関数の戻り値は0です。rt.sleepはLuaスクリプトの実行を遅延させたい場合に用います。関数の実行中、呼び出し元のLuaタスクはほとんどCPUを消費しません。

while true do
  …
  rt.sleep(600) -- 10分おきに何らかの処理を繰り返す
end
    

rt.syslog(type, text)

• type … 文字列型
• text … 文字列型

textをログとして記録します。また、syslog serverコマンドなどが設定されていれば、SYSLOGとしても出力します。textは231バイト以内でなければなりません。

typeはログの種類で、以下のいずれかでなくてはなりません。

• "notice" … NOTICEタイプ
• "info" … INFOタイプ
• "debug" … DEBUGタイプ
• "log_only" … INFOタイプだがSYSLOGサーバーへは送信しない

戻り値には、論理型と文字列型の2つが返ります。最初の論理型の戻り値はログ出力の成功、失敗を表し、2番目の戻り値はエラーメッセージとなります。typeにnotice/debugを指定した場合は、対応するsyslog notice/debugコマンドの設定がoffになっていると ログ出力は失敗し、falseが返ります。typeにinfoを指定した場合は、対応するsyslog infoコマンドの設定に関わらず常にログ出力を行いますが、SYSLOGサーバーへの送信はsyslog infoコマンドの設定がonになっている場合にのみ行われます。

rt.syslog("info", "[Lua] This is a LOG")
    

rt.syslogwatch(pattern, n, seconds)

• pattern … 文字列型または正規表現オブジェクト
• n … 数値型(1〜1000)
• seconds … 数値型(1〜864000)

ルーターのログに、パターンpatternに合致する行がn回新しく記録されるか、seconds秒が経過するとこの関数は終了し、処理が戻ってきます。ログのタイムスタンプ部分はpatternの比較対象とはなりません。

nは1〜1000の数値で、省略したときは1とみなします。secondsは1〜864000の数値で、省略時はpatternに合致するログが現れるまで永遠に待ちます。

戻り値としては、patternに合致した回数、および、合致したログ(タイムスタンプつき)を格納した配列が返されます。secondsの満了により返ってくる場合には、それまでに合致した回数とログが返されます。一度も合致するログがなかった場合には、回数は0となり、2つ目の戻り値はnilとなります。

一行のログにpatternが複数回合致するようなケースでも、合致回数は1と数えます。

rt.syslogwatchを呼び出している間は、ログの記録がなければ呼び出し元のLuaタスクはほとんどCPUを消費しません。

pattern = "IP Tunnel%[(%d+)%] Down"
while true do
  rtn, array = rt.syslogwatch(pattern, 1, 600)
  if rtn > 0 then
    io.output("FILE.txt")
    io.write(string.format("トンネルダウン: %s\n", string.match(array[1], pattern)))
    io.close()
  end
end
    

ハードウェアライブラリ

rt.hw.open(resource, type)

• resource … 文字列型
• type … 文字列型

resourceで指定したハードウェアをオープンしてLuaスクリプトで制御可能な状態にし、そのディスクリプタを返します。
resourceとして指定できるのは下記のいずれかです。

• "buzzer1" ... ブザー
• "status-led1" ... STATUS ランプ（RTX1200、RTX810、SRT100のみ）
• "donwload-led1" ... DOWNLOAD ランプ（RTX1200のみ）
• "alarm-led1" ... ALARM ランプ（RTX1200のみ）
• "wan-led1" ... WAN ランプ（NVR500のみ）
• "thermometer1" ... 温度計（RTX1200のみ）
• "cpu1" ... CPU

• "keyboard1" ... USBキーボードや USBバーコードリーダーなど
  （制限事項）
  • USBキーボードとして認識されるもののみ制御可能です
  • USBポートを複数持つ機種でも、同時に制御できるのは1台のみとなります

ハードウェアのオープンに成功した場合、1つ目の戻り値としてディスクリプタが返り、2つ目の戻り値はnilになります。ハードウェアのオープンに失敗した場合、1つ目の戻り値はnilになり、2つ目の戻り値にエラー内容を示す文字列が返ります。

typeはUSBキーボードのタイプを示す文字列で、typeはUSBキーボード"keyboard1"を制御する場合にのみ 指定可能です。他のハードウェアのオープン時に指定した場合、当関数はエラー終了します。
typeとして指定できるのは下記のいずれかです。

• "jp" ... 日本語106キー型
• "us" ... 英語101キー型

typeを省略した場合には、"jp"が指定されたものとしてキーボードを制御します。

当関数でオープンしたハードウェアは、呼び出し元のLuaタスクが占有するため、hwd:closeでクローズするまでは他のLuaタスクから制御することができません。 なお、温度計 "thermometer1"と CPU "cpu1"以外のハードウェアに関しては、Luaタスクが占有しているときは他のルーターの機能からも制御することができなくなるため、ハードウェア本来の動作はしなくなるため注意が必要です。

-- 1分毎にCPU負荷率を調べ、80%を超えていたら、ブザーを鳴らす。

threshold = 80
sleep_sec = 60

while (true) do
	cpu, err = rt.hw.open("cpu1")
	if (cpu) then
		load = cpu:read()
		cpu:close()
	end

	if (load.load_1m > threshold) then
		bz, str = rt.hw.open("buzzer1")
		if (bz) then
			bz:tone("B3")
		end
	else
		if (bz) then
			bz:off()
			bz:close()
		end
	end

	rt.sleep(sleep_sec)
end
    

以下は_RT_LUA_VERSIONが"1.02"以降のファームウェアで使用可能です。

hwd:close()

ディスクリプタhwdに対するメソッドであり、hwdをクローズしてハードウェアの制御を終了します。

bz、str = rt.hw.open("buzzer1")
bz:tone("B2")
rt.sleep(10)
bz:off()
bz:close()
    

hwd:tone(tune)

ブザーのディスクリプタhwdに対するメソッドであり、tuneで指定した音程のブザー音を鳴らします。

• tune … 文字列型

tuneは音程を表す文字列で、"C1" のように、C、D、E、F、G、A、Bのうちのアルファベットと 1桁の数字との組合せで指定します。 "C1"の"C"は音階を表し、Cから順に ド、レ、ミ、ファ、ソ、ラ、シ に対応します。 また、"1"は音の高さを表し、数値が1つ大きくなるとブザー音は1オクターブ高くります。 出力できる音程は表のとおりです。

bz, str = rt.hw.open("buzzer1")
bz:tone("B2")…
    

hwd:on()

LEDのディスクリプタhwdに対するメソッドであり、LEDを点灯させます。

led, str = rt.hw.open("status-led1")
led:on()…
    

hwd:blink(interval_on, interval_off)

• interval_on … 数値型
• interval_off … 数値型

LEDのディスクリプタhwdに対するメソッドであり、LEDを点滅させます。

interval_on/interval_offは、LEDの点滅における点灯/消灯の時間（ミリ秒）であり、それぞれ100ミリ秒単位で100から3000の範囲で指定できます。100で割り切れない値が指定された場合10の位以下は切り捨てられます。

led, str = rt.hw.open("status-led1")
led:blink(500, 500)…
    

hwd:off()

ディスクリプタhwdに対するメソッドであり、hwdがブザーのディスクリプタの場合には鳴っているブザーを停止します。hwdがLEDのディスクリプタの場合には点灯もしくは点滅しているLEDを消灯します。

led = rt.hw.open("status-led1")
led:on()
led:off()…
    

hwd:read(n)

• n … 数値型

ディスクリプタhwdに対するメソッドであり、hwdが温度計のディスクリプタの場合にはルーター筐体内の温度計の値を読み取り、戻り値には数値型で温度が返ります。hwdがCPUのディスクリプタの場合にはCPU負荷率を取得し、戻り値には、各測定間隔のCPU負荷率を格納したテーブルが返ります。 テーブルの内容は表のとおりです。

_RT_LUA_VERSIONが"1.04"以降のファームウェアでは、hwdが USBキーボードの場合、キーボードからの出力をnで指定した文字数だけ読み取ります。 戻り値には、キーボードから読み取った文字が返ります。

なお、hwdが温度計、CPUのディスクリプタの場合には、nを指定することはできません。

[CPU負荷率を読み取る例]
cpu, err = rt.hw.open("cpu1")
if cpu then
  val_t = cpu:read()
  cpu:close()
  print("5分間のCPU負荷率 : " .. tostring(val_t.load_5m) .. "％")
else
  print(err)
end


[キーボードから文字を読み取る例]
kbd, err = rt.hw.open("keyboard1", "jp")
if kbd then
  data = kbd:read(5)
  kbd:close()
  print(data)
else
  print(err)
end
    

以下は_RT_LUA_VERSIONが"1.04"以降のファームウェアで使用可能です。

hwd:getc(NOWAIT)

• NOWAIT … 論理型

USBキーボードのディスクリプタhwdに対するメソッドであり、キーボードからの出力を1文字読み取ります。

NOWAITにfalseを指定した場合には、ノーウェイトでキー入力を読み取ることができます。

kbd, str = rt.hw.open("keyboard1")
if kbd then
  str = ""

  data = kbd:getc()
  while data ~= '\n' do
    if data then
	    str = str .. data
      data = kbd:getc()
    end
  end

  kbd:close()
  print(str)
else
  print(str)
end
    

hwd:getchar()

USBキーボードのディスクリプタhwdに対するメソッドであり、キーボードからの出力を1文字読み取ります。

NOWAITを指定することができない点以外はhwd:getc関数と同様に使用することができます。

hwd:gets()

USBキーボードのディスクリプタhwdに対するメソッドであり、キーボードからの出力を改行までの1行を読み取ります。

kbd, str = rt.hw.open("keyboard1")
if kbd then
  data = kbd:gets()
  if data then
    print(data)
  end
  kbd:close()
end
    

通信ライブラリ

_RT_LUA_VERSIONが"1.02"以降のファームウェアで使用可能です。

rt.httprequest(param)

• param … テーブル型

テーブルparamで指定したパラメータに従ってHTTPによるデータの送受信を行います。

rt.httprequestが呼び出されると、パラメータの内容に沿ったHTTP RequestがHTTPサーバーに対して送信され、それに対するResponseが受信されると関数から処理が戻ります。関数からの戻り値として、HTTP通信の実行結果とサーバーから受信したデータを格納したテーブルが返されます。

paramに指定できるパラメータは以下のとおりです。

また、戻り値は以下のようなテーブルとなる。

OS

os.clock()

実行中のLuaスクリプトが開始されてから現在の時刻までの秒数を返します。

Lua言語の標準仕様ではos.clockは実行中のLuaスクリプトで消費されたCPU時間のおおよその秒数を返すことになっていますが、ヤマハルーターの実装は異なっています。この実装は将来、標準仕様に変更される可能性があります。

t1 = os.clock()
do
  … -- 時間のかかる処理
end
t2 = os.clock()
print("実行時間", t2 - t1) -- 実行時間の表示
    

os.date(format, time)

• format … 文字列型
• time … 数値型(FIXNUM)

指定された時刻を表す文字列またはテーブルを返します。timeは、os.timeの戻り値であり、これがあるときにはその時刻を対象とします。timeが省略された場合は、関数が呼び出されたときの現在時刻を対象とします。

formatは、時刻の戻り値への変換方法を定義します。

formatの先頭が'!'であるときには、時刻はUTC(協定世界時)として変換されます。それ以外の場合には、timezoneコマンドで指定されたタイムゾーンの時刻として変換されます。

先頭にあるかもしれない'!'を取り除いた後のformatが、"*t"という文字列である場合には、時刻は以下の文字列をキーとする要素を持つテーブルへと変換されます。

• year … 西暦の年を表す4桁の数値
• month … 月を表す数値(1〜12)
• day … 日を表す数値(1〜31)
• hour … 時を表す数値(0〜23)
• min … 分を表す数値(0〜59)
• sec … 秒を表す数値(0〜59)
• wday … 曜日を表す数値(1〜7で、1が日曜、2が月曜、‥、7が土曜)
• yday … 1年の中の何日目かを表す数値(1〜366)
• isdst … 常にfalse

formatが"*t"以外の形であるときには、C言語のstrftime関数のフォーマット文字列として動作します。

formatを省略した場合には、"%c"が与えられたものとして現在時刻を文字列に変換します。

os.difftime(time2, time1)

• time2 … 数値型(FIXNUM)
• time1 … 数値型(FIXNUM)

時刻time1からtime2までの経過時間を秒で返します。time1、time2ともに、os.timeの戻り値でなければなりません。

t1 = os.time()
do
  … -- 時間のかかる処理
end
t2 = os.time()
print("実行時間", os.difftime(t2, t1)) -- 実行時間の表示
    

os.exit([code])

• code … 数値型(FIXNUM)

Luaスクリプトの実行を終了します。codeは終了コードであり、0が正常終了です。この関数は呼び出し元には戻ってきません。

function f(x)
  if x < 1 or x > 100 then
    print("Error")
    os.exit(0)
  end
…
end
    

os.getenv(varname)

• varname … 文字列型

環境変数varnameの値を文字列で返します。varnameが定義されていないときはnilを返します。

user = os.getenv("USER")
if user then
  print("USER:", user)
else
  print("USER: undefined")
end
    

os.remove(filename)

• filename … 文字列型

filenameで指定したファイルを削除します。ディレクトリを削除する場合は、中が空になっていないといけません。

ファイルを削除できた場合はtrueが、失敗した場合はfalseとエラーメッセージ(文字列)が返ります。

os.remove("FILE.txt")
    

os.rename(oldname, newname)

• oldname … 文字列型
• newname … 文字列型

oldnameで指定したファイルのファイル名をnewnameに変更します。ファイルが存在するディレクトリは変更できません。

ファイル名を変更できた場合はtrueが、失敗した場合はfalseとエラーメッセージ(文字列)が返ります。

os.rename("FILE.txt", "NEW-FILE.txt")
    

os.time(tbl)

• tbl … テーブル型

指定された時刻を表す数値を返します。tblは時刻を表すテーブルで、必須の要素として、year、month、dayを持っていなければなりません。また、hour、min、secを持つこともできます。isdstはあっても無視されます。各要素の意味は、os.dateを参照してください。tblが省略された場合は、関数が呼び出されたときの現在時刻を返します。

os.timeの戻り値は、os.dateおよびos.difftimeの引数としてのみ、意味を持ちます。

t1 = os.time()
do
  … -- 時間のかかる処理
end
t2 = os.time()
print("実行時間", os.difftime(t2, t1)) -- 実行時間の表示
    

モジュール

モジュールとは、ライブラリ関数を提供するための機構です。この文書で説明しているライブラリ関数群も、多くはモジュールの機構で提供されています。

ユーザーが新規にモジュールを作成する場合は、モジュールファイルを作成する必要があります。モジュールファイルは通常のLuaスクリプトですが、以下の点が異なります。

• ファイルの先頭でmodule関数を呼び出している。
• 環境変数LUA_PATHが示すディレクトリに置いてある。

このようになっているモジュールファイルは、他のLuaスクリプトからrequire関数で読み込むことができ、モジュールファイルで定義したライブラリ関数等を利用できるようになります。

ヤマハルーターの実装では、C言語で記述したモジュールを作成、呼び出すことはできません。

module(name, func...)

• name … 文字列型
• func … 関数型

モジュールを作成します。通常、モジュールファイルの先頭でmodule関数を呼び出し、ファイルをモジュールファイルとします。

文字列nameはモジュールの名前です。通常は、モジュールファイルの名前から拡張子(.lua)を削除したものと同じ名前にしておきます。

グローバル環境下でnameを名前とするテーブルが新たに作成され、そのテーブルがモジュールファイルの新しい環境となります。これにより、モジュールファイル内で定義した関数等は、requireでモジュールを読み込んだLuaスクリプトからは、nameの要素としてアクセスできることになります。

[ルーターコマンド]
set LUA_PATH="/lua/module/\?.lua;"
set PWD="/lua"

[/lua/module/mod1.lua]
module("mod1")
value = 100
function func(x)
  return x + 1
end

[/lua/script.lua]
require("mod1")
print(mod1.value) -- モジュールmod1の変数valueを表示
x = mod1.func(10) -- モジュールmod1の関数funcを呼び出し
    

funcは、環境の切り替え後に作成されたモジュールを引数として呼び出されます。funcは0個以上、任意の数が指定できます。

moduleは環境をグローバル環境から独自の環境に切り替えます。一般のライブラリ関数はグローバル環境に名前が登録されているため、そのままではモジュールファイルの中では利用できません。それを避けるために、funcにpackage.seeall関数を指定すると、package.seeallの効果でモジュールファイルの中でも一般ライブラリ関数が使用できるようになります。

[ルーターコマンド]
set LUA_PATH="/lua/module/\?.lua;"
set PWD="/lua"

[/lua/module/mod2.lua]
module("mod2", package.seeall)
function func(x)
  return string.format("%08x", x) -- package.seeallの効果でライブラリ関数が呼び出せる
end

[/lua/script.lua]
require("mod2")
x = mod2.func(10) -- モジュールmod2の関数funcを呼び出し
    

require(name)

• name … 文字列型

モジュールファイルを読み込みます。nameはモジュール名であり、モジュールファイルの名前の一部です。

モジュールファイルは、環境変数LUA_PATHにしたがって探索されます。LUA_PATHは、複数の場所をセミコロン(;)で区切って並べ、先頭から探索します。個々の場所の探索では、LUA_PATH中の文字(?)をnameで指定したモジュール名で置き換えてファイルがあるかどうかを探索します。

たとえば、モジュール名"foo"を以下のLUA_PATHで探索する場合、./foo.lua、/lua/module/foo.lua、/lua/module/foo/init.luaの順にファイルを探します。

set LUA_PATH="./\?.lua;/lua/module/\?.lua;/lua/module/\?/init.lua"
    

package.seeall(name)

• name … 文字列型

モジュールnameの中から一般ライブラリ関数が呼び出せるようにします。moduleの2番目以降の引数として指定することで機能を果たします。

コルーチン

Lua言語では言語レベルでコルーチンをサポートしており、coroutine.*ライブラリ関数群を通して利用できます。コルーチンはイテレータ、無限リストなどの継続状況を持つプログラムの記述を容易にします。

以下は、フィボナッチ数列を求めるのにコルーチンを使用した例です。フィボナッチ数列を求める関数はその定義から再帰を用いて簡潔に記述できますが、順列を追っていくと再帰呼び出しの回数が爆発的に増えるためにあまり実用的ではありません。コルーチンを使用すれば、無限に順列を追っていくことができます。

-- 以下は、フィボナッチ数列を再帰で求める関数

function fib(n)
  if n < 2 then
    return n
  else
    return fib(n - 1) + fib(n - 2)
  end
end

-- 以下の関数は、n以下のフィボナッチ数列を順に返す関数を戻り値とする

function generatefib(n)
  return coroutine.wrap(function ()
    local a, b = 1, 1
    while a <= n do
      coroutine.yield(a)
      a, b = b, a + b
    end
  end)
end

-- 1000以下のフィボナッチ数列を出力する
for i in generatefib(1000) do print(i) end
    

coroutine.create(func)

• func … 関数型

関数funcを本体とするコルーチンを作成し、そのコルーチン(スレッド型)を返します。

coroutine.resume(co, val1,...)

• co … スレッド型
• val1 … 任意の型

コルーチンcoを開始、または再開します。最初にcoroutine.resumeを呼んだ場合はコルーチンの開始であり、コルーチンの本体である関数が、val1, ...を引数として呼ばれます。中断されているコルーチンに対してcoroutine.resumeを呼んだ場合はコルーチンの再開であり、val1, ...はcoroutine.yieldの戻り値になります。

コルーチンの実行中にエラーが発生しなければ、coroutine.resumeは、最初の戻り値としてtrue、引き続く戻り値としてcoroutine.yieldの引数か、あるいは本体の関数の戻り値を返します。コルーチンの実行中にエラーが発生した時は、最初の戻り値としてfalse、2番目の戻り値にエラーメッセージの文字列を返します。

coroutine.running()

動作中のコルーチン(スレッド型)を返します。動作中のコルーチンがない場合はnilを返します。

coroutine.status(co)

• co … スレッド型

コルーチンcoの状態を文字列で返します。

• "running" : コルーチンは動作中である。
• "suspended" : コルーチンは一度も動作したことがないか、coroutine.yieldにより停止中である。
• "normal" : コルーチンはアクティブだが動作していない。これは、さらに別のコルーチンにより再開されたコルーチンの状態に当てはまる。
• "dead" : 本体の関数が終了したか、エラーで停止した。

coroutine.wrap(func)

• func … 関数型

関数funcを本体とするコルーチンを作成し、そのコルーチンを再開する関数を返します。戻り値の関数に与えられた引数は、coroutine.resumeと同じ意味を持ちます。戻り値はcoroutine.resumeのそれから最初の論理型を除いたものになります。コルーチンの実行中にエラーが発生したときは、エラーが伝播します。すなわち、スクリプト全体がエラーで停止します。

coroutine.yield(...)

コルーチンの実行を中断します。与えられた引数は、coroutine.resumeの戻り値となります。また、新しく再開するために呼び出されたcoroutine.resumeの引数が、coroutine.yieldの戻り値となります。