Luaスクリプト機能

$Date: 2023/10/05 10:55:09 $

ライブラリ関数

ヤマハルーターの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 … 数値型(0〜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, log)

• cmd … 文字列型
• log … 文字列型

文字列cmdをルーターのコマンドとして実行します。cmdの長さは4095バイト以内でないといけません。またcmdにはパイプ ("|") やリダイレクト記号 (">", ">>") を含むことができます。cmdに指定できるコマンドは1つのみで、複数のコマンドを指定することはできません。

logにoffを指定すると、実行したコマンドと実行の成否 (true/false) が、SYSLOGに出力されなくなります。logを省略、またはonを指定した場合、従来と同様に実行したコマンドと実行の成否 (true/false) が、DEBUGタイプでSYSLOGに出力されます。
logは_RT_LUA_VERSIONが"1.07"以上のファームウェアで指定可能です。

戻り値には、コマンドの実行結果が返ります。最初の戻り値として、コマンドが正しく実行できれば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
• import sshd authorized-keys
• less で始まるコマンドや ’|’ で less を連結したコマンド
• login password
• login password encrypt
• lua use
• luac
• mail notify
• mail server pop
• mail server smtp
• mail server timeout
• mail template
• pri loopback active
• pri loopback passive
• quit
• remote setup
• scp
• ssh
• 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 ランプ（SRT100、FWX120、RTX810、RTX830、RTX1200、RTX1210、RTX1220、RTX1300、RTX3510 のみ）
• "donwload-led1" ... DOWNLOAD ランプ（RTX1200、RTX1210、RTX1220、RTX1300 のみ）
• "func-led1" ... FUNC ランプ（RTX3510 のみ）
• "alarm-led1" ... ALARM ランプ（RTX1200、RTX1210、RTX1220、RTX1300、RTX3500、RTX3510、RTX5000のみ）
• "wan-led1" ... WAN ランプ（NVR500のみ）
• "thermometer1" ... 温度計（RTX1200、RTX1210、RTX1220、RTX3500、RTX5000のみ）
• "cpu1" ... CPU
• "cpu2" ... マルチコア CPU の CPU1（ NVR510、NVR700W、RTX830、RTX1300、RTX3500、RTX3510、RTX5000のみ ）
• "cpu3" ... マルチコア CPU の CPU2（ RTX1300、RTX3500、RTX3510、RTX5000のみ ）
• "cpu3" ... マルチコア CPU の CPU3（ RTX1300、RTX3500、RTX3510、RTX5000のみ ）

• "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
    

HTTPライブラリ

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

rt.httprequest(param)

• param … テーブル型

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

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

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

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

ソケット通信ライブラリ

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

ソケット通信ライブラリは、LuaSocketのC言語で記述されたライブラリ関数を移植したものです。LuaSocketのバージョンは 2.0.2 です。

LuaSocketはC言語で書かれたライブラリ関数と、Lua言語で書かれたライブラリ関数に分かれています。C言語で書かれたライブラリ関数が、ソケットシステムコールを呼び出すような低レベルの関数を用意しているのに対して、Lua言語で書かれたライブラリ関数は、HTTPやFTP、SMTP等のアプリケーションを利用するための関数を用意しています。
ルーターにはLuaSocketのC言語で書かれたライブラリ関数をAPIとして移植しているため、Lua言語のライブラリ関数についてもLuaSocketのホームページで公開されているスクリプトをそのまま使用することができません。以下にあるヤマハルーター用LuaSocketモジュールファイルを使用してください。 また、Lua言語で書かれたライブラリ関数についてはLuaSocketのリファレンスをご覧ください。

ヤマハルーター用LuaSocketモジュールファイル

本ライブラリでは、ソケットオブジェクトを生成し、オブジェクト単位での通信を行います。オブジェクトはプロトコル毎に性質が異なり、特定の関数によって状態を遷移させます。

• TCP
  使用するオブジェクトは次の通りです。TCPでは、俗にコネクションを待ち受ける側をサーバー、TCPの通信を開始する側をクライアントと言いますが、オブジェクトのサーバー、クライアントはそれらとは異なる概念となっていますので注意が必要です。

  マスターオブジェクト：	rt.socket.tcpにて生成されるオブジェクト。
  サーバーオブジェクト：	TCPコネクションを待ち受け可能な状態となったオブジェクト。 マスターオブジェクトがtcp:listenをコールしコネクションの待ち受け状態になるとサーバーオブジェクトに遷移する。
  クライアントオブジェクト：	リモートホストとのコネクションが確立し、データの送受信が可能な状態となったオブジェクト。マスターオブジェクトがtcp:connectをコールしてクライアントオブジェクトに遷移するか、サーバーオブジェクトでtcp:acceptを実行し、接続が確立した際にクライアントオブジェクトを返す。

• UDP
  UDPのオブジェクトは次の2つです。

  connectedオブジェクト：	特定のホストとのみ通信を行うオブジェクト。unconnectedオブジェクトがsetpeernameで接続相手を指定するとconnectedオブジェクトに遷移する。このオブジェクトでは、送受信にはudp:send/udp:receiveを使用しなければならない。
  unconnectedオブジェクト：	rt.socket.udpにて生成されるオブジェクト。送受信にはudp:sendto/udp:receivefromを使用し、不特定のホストと通信が可能である。

• MIME
  Base64やQuoted-Printableによるエンコード、デコードや、送信メッセージへの改行の挿入、改行コードの変換を行う関数群です。

注意事項

• NATおよびIPマスカレードを設定したインタフェースの外側からLuaSocketで指定したポートにアクセスする場合には、静的NAT(または静的マスカレード)の設定が必要となります。
• 誤動作を避けるため、LuaSocketで指定するポート番号と、ルーターの各機能が使用するポート番号が重複しないようにしてください。
  ルーターに搭載されている機能が使用するポート番号は次の通りです。機種毎に搭載する機能に違いがあり、また機能を使用する・しないによっても実際に使用されるポート番号は異なりますが、機種や設定内容に依存しないように、一覧に掲載されているポート番号は避けるようにしてください。
  ※ 表中の (*) は 使用するポート番号がコマンドで変更が可能であることを表します。

  プロトコル	機能名	ポート番号
  TCP	www設定	80 (*)
  	TELNETサーバー	23 (*)
  	SSHサーバー	22 (*)
  	BGP	179
  	PPTP	1723
  	SIP	5060
  	ONFS	49501, 49502 (*)
  	TCP (Socket)	49152〜65535 (vRX), 1024〜5000 (vRX以外の機種)
  	UDP	UDP ECHO	7
  生存通知		9
  DNS		53、始点ポート：10000〜10999 (*)
  DHCPサーバー		67
  DHCPクライアント		68
  TFTPサーバー		69
  SNMP		161
  IKE		500
  SYSLOG		514 (*)
  RIP		520
  RIPng		521
  DHCP6クライアント		546
  DHCP6エージェント		547
  RADIUS		1645
  L2TP		1701
  UPnP		1900
  ネットボランチDNS		2002 (*)
  MGCP		2427〜2433
  NATトラバーサル		4500
  データコネクト拠点間接続		4502
  RTP		5004〜5059 (*)
  SIP		5060
  生存通知2		8512
  QoS連携(負荷通知、帯域検出)		59140 (*)
  UDP (Socket)		49152〜65535 (vRX), 21024〜25000 (vRX以外の機種)

• ソケット通信ライブラリのAPIが返すエラーメッセージは機種によって異なることがあります。

rt.socket.tcp()

TCPのマスターオブジェクトを生成します。

生成したマスターオブジェクトは、この後tcp:listenを呼び出してサーバーオブジェクトに遷移したり、tcp:connectを呼び出してクライアントオブジェクトに遷移したりします。

オブジェクトの生成に成功した場合、生成したオブジェクト(ユーザーデータ型)を返します。オブジェクトの生成に失敗した場合は、nil、エラーメッセージの2つを返します。

-- TCPオブジェクトを生成し、コネクションを待ち受ける
tcp = rt.socket.tcp()
tcp:setoption("reuseaddr", true)
res, err = tcp:bind("192.168.100.1", 11111)
if not res and err then
  print(err)
  os.exit(1)
end
res, err = tcp:listen()
if not res and err then
  print(err)
  os.exit(1)
end

while 1 do
  control = assert(tcp:accept())

  raddr, rport = control:getpeername()
  print("remote host address:" .. raddr .. " port:" .. rport)

  -- 受信待ちタイムアウトを30秒に設定
  control:settimeout(30)
  while 1 do
    msg, err, partial = control:receive()

    if (msg) then
      -- 受信データを処理する(例として、ここではコンソールに出力している)
      print(msg)

      -- レスポンスを送信
      sent, err = control:send("response\n")
      if (err) then
        print("send error(" .. err .. ")")
        control:close()
        break
      end
    else
      if (err ~= "closed") then
        print(os.date() .. "receive error(" .. err .. ")")
        if (partial) then
          print("receive partial data(" .. partial .. ")")
        end
      end
      control:close()
      break;
    end
  end
end
    

-- TCPオブジェクトを生成し、リモートホストへ接続、転送を行う

-- リモートホストのIPアドレス、ポート番号
host = "192.168.100.1"
port = 11111

tcp = rt.socket.tcp()

res, err = tcp:connect(host, port)
if not res then
  print("connect error(" .. err .. ")")
  os.exit(1)
end

print("Connected remote host:" ..host.. " port:" .. port)

lhost, lport = tcp:getsockname()
print("Local host:" ..lhost.. " port:" ..lport)

tcp:settimeout(5)
tcp:setoption("tcp-nodelay", true)

-- データを送信する
sent, err = tcp:send("test\n")
if (err) then
  print("send error(" .. err .. ")")
  tcp:close()
  os.exit(1)
end

-- サーバーからのレスポンスを受信
data, err, partial = tcp:receive()
if (err) then
  print("receive error("..err..")")
  if (partial) then
    print("receive partial data("..partial..")")
  end
  tcp:close()
  os.exit(1)
end

-- 受信データを処理する(例として、ここではコンソールに出力している)
print(data)

tcp:close()
    

rt.socket.udp()

UDPのunconnectedオブジェクトを生成します。

オブジェクトの生成に成功した場合、生成したオブジェクト(ユーザーデータ型)を返します。オブジェクトの生成に失敗した場合は、nil、エラーメッセージの2つを返します。

-- UDPオブジェクトを生成し、リモートホストからのデータ送信を待つ
host = "192.168.100.1"
port = 22222

udp = rt.socket.udp()
res, err = udp:setsockname(host, port)
if (err) then
  print("setsockname error(" .. err .. ")")
  udp:close()
  os.exit(1)
end

lhost, lport = udp:getsockname()
print("Bind to host:" ..lhost.. " and port:" ..lport)

while 1 do
  dgram, ip, port = udp:receivefrom()
  if (dgram ~= nil) then
    -- 受信データを処理する
    -- (例として、ここではコンソールに出力し、受信した文字列をそのまま相手に返している)
    print("Received '" .. dgram .. "' from " .. ip .. ":" .. port)
    udp:sendto(dgram, ip, port)
  else
    print(ip)
    udp:close()
    os.exit(0)
  end
end
    

-- UDPオブジェクトを生成し、リモートホストとの通信を行う
udp = rt.socket.udp()
udp:setpeername("192.168.100.1", 22222)

rhost, rport = udp:getpeername()
print("remote host:" .. rhost .. " port:" .. rport)

-- データを送信
res, err = udp:send("test")
if (err) then
  print("send error(" .. err .. ")")
  udp:close()
  os.exit(1)
end

udp:settimeout(10) -- 受信タイムアウトを10秒に設定

-- 相手からのレスポンスを受信
dgram, err = udp:receive()
if (not dgram) and err then
  print("receive error(" .. err .. ")")
  udp:close()
  os.exit(1)
end
-- 受信データを処理する(例として、ここではコンソールに出力している)
print(dgram)

udp:close()
    

rt.socket.select(recvt, sendt, timeout)

ソケットの状態変化を監視し、読み込みまたは書き出しが可能な状態となったオブジェクトの配列を返します。

• recvt … テーブル型
• sendt … テーブル型
• timeout … 数値型(FIXNUM)

recvtには読み込み可能な状態を待つオブジェクト(ユーザーデータ型)の配列を指定し、sendtには書き出し可能な状態を待つオブジェクト(ユーザーデータ型)の配列を指定します。状態変化を待つオブジェクトがない場合には、nilまたは空のテーブルを指定します。
timeoutには状態変化を待つ秒数を指定します。timeoutを省略した場合、または負数を指定した場合は無期限に状態変化を待ちます。

成功した場合、読み込み準備が完了したオブジェクトのテーブル、書き出し準備が完了したオブジェクトのテーブルの２つを返します。このテーブルは整数とオブジェクトの２つがキーとなっており、どのオブジェクトの状態が変化したか一意に分かるようになっています。
エラーが発生した場合、nil、nil、エラーメッセージの３つを返します。

-- 複数のポートでコネクションを待ち受ける
function create(addr, port)
  s = rt.socket.tcp()
  s:setoption("reuseaddr", true)
  res, err = s:bind(addr, port)
  if not res and err then
    print(err)
    os.exit(1)
  end
  res, err = s:listen()
  if not res and err then
    print(err)
    os.exit(1)
  end

  return s
end

server1 = create("192.168.100.1", 11111)
server2 = create("192.168.100.1", 11112)

while 1 do
  rcv, snd, err = rt.socket.select({server1, server2}, nil)

  if rcv[server1] then
    server = server1
  elseif rcv[server2] then
    server = server2
  else
    print("select error:"..err)
    os.exit(1)
  end

  control = assert(server:accept())

  raddr, rport = control:getpeername()
  print("remote host address:" .. raddr .. " port:" .. rport)

  -- 統計情報をクリア
  res = control:setstats(0, 0)

  -- 受信待ちタイムアウトを30秒に設定
  control:settimeout(30)

  while 1 do
    msg, err, partial = control:receive()

    if (msg) then
      -- 受信データを処理する(例として、ここではコンソールに出力している)
      print(msg)

      -- レスポンスを送信
      sent, err = control:send("response\n")
      if (err) then
        print("send error(" .. err .. ")")
        control:shutdown()
        break
      end
    else
      if (err ~= "closed") then
        print(os.date() .. "receive error(" .. err .. ")")
        if (partial) then
          print("receive partial data(" .. partial .. ")")
        end
      end
      control:shutdown()
      break;
    end
  end

  rcv, snd, alive = control:getstats()
  -- 統計情報を表示
  print("receive: " .. rcv .. "bytes, send: " .. snd .. "bytes, alive time: " .. alive .. "sec")

end
    

rt.socket.dns.toip(address)

ホスト名をIPv4アドレスに変換します。

• hostname … 文字列型

hostnameには、IPv4アドレスまたはホスト名を指定します。

成功した場合、IPv4アドレスとリゾルバから受け取った情報(テーブル型)の2つを返します。リゾルバから受け取った情報は次のテーブルに格納されます。失敗した場合は、nil、エラーメッセージの2つを返します。

host = "example.com" -- ホスト名を指定
ip, tbl = rt.socket.dns.toip(host)
if ip then
  print(ip) -- 成功した場合、IPアドレスが返される
end
    

rt.socket.dns.tohostname(ip)

IPv4アドレスをホスト名に変換します。

• ip … 文字列型

ipには、IPv4アドレスまたはホスト名を指定します。

成功した場合、ホスト名とリゾルバから受け取った情報(テーブル型)の2つを返します。リゾルバから受け取った情報は次のテーブルに格納されます。失敗した場合は、nil、エラーメッセージの2つを返します。

ip = "10.0.0.1" -- IPアドレスを指定
host, tbl = rt.socket.dns.tohostname(ip)
if host then
  print(host) -- 成功した場合、ホスト名が返される
end
    

rt.socket.dns.gethostname()

機器のホスト名を返します。
ネットボランチDNS や、ip hostコマンドで設定されたルーター自身のホスト名を返します。

成功した場合には機器のホスト名を返します。失敗した場合は、nil、エラーメッセージの2つを返します。

host, err = rt.socket.dns.gethostname(host)
if host then
  print(host) -- 成功した場合、ルーター自身のホスト名が返される
end
    

rt.socket.sleep(seconds)

呼び出し元の Lua タスクをスリープさせます。

• seconds … 数値型(FIXNUM)

rt.socket.sleepを呼び出すと、seconds秒後に関数から返ってきます。

-- 10分置きにUDPパケットを送信する
udp = rt.socket.udp()
udp:setpeername("192.168.100.1", 22222)

while true do
-- データを送信
  res, err = udp:send("notification")
  if (err) then
    print("send error(" .. err .. ")")
    udp:close()
    os.exit(1)
  end

  rt.socket.sleep(600)
end

udp:close()
    

rt.socket.gettime()

ルーターが起動してから経過した秒数を返します。

t1 = rt.socket.gettime()
-- 何かしらの処理をする。
...
t2 = rt.socket.gettime() - t1
print("execute time:" .. t2)
    

rt.socket.newtry(finalizer)

例外エラーを投げる前に処理を行う関数を生成します。

• finalizer … 関数型

finalizerは、例外エラーを投げる前に保護モードで呼び出される関数です。nilを指定した場合、エラー発生時には何もしません。

例外エラーが発生した際の処理を行う関数を返します。

c = rt.socket.tcp()
sample = rt.socket.protect(function()
    -- エラー発生時にclose()を呼ぶ関数の生成
    local try = rt.socket.newtry(function() c:close() end)
    -- エラー発生時には必ずソケットが閉じられる
    try(c:connect("192.168.100.1", 8888))
    try(c:send("test\r\n"))
    local answer = try(c:receive())
    -- 受信データを処理する
    ...
    return c:close()
end)

ret, err = sample()
if not ret and err then
    print(err)
end
    

rt.socket.protect(func)

関数funcを、保護されたモードで呼び出します。

• func … 関数型

funcには、newtryやassert、errorを呼んで例外エラーを投げる関数を指定します。

例外エラーを投げない同等の処理を行う関数を返します。その関数は、エラーの場合、nil、エラーメッセージの２つを返します。

こちらの設定例を参照してください。

rt.socket.skip(num, ret1, ret2, ..retN)

指定した数の引数を破棄し、残りの引数を返します。

• num … 数値型(FIXNUM)
• retN … 任意の型

ret1, ret2.. と列挙した引数のうち、先頭からnum個の引数を破棄し、残りのret[num+1]からretNまでの引数を返します。この関数を使用すると、不要な関数の戻り値を格納するためにダミー変数を用意する必要がなくなります。

num+1 番目以降の引数がある場合、num+1番目以降の引数を全て返します。numと引数の数が同じ場合や、numより引数の数が少ない場合には何も返しません。

-- パターンに合致した位置を表す数値を破棄し、キャプチャされた文字列だけを返す。
r = rt.socket.skip(2, string.find("ABCDE", "B(.)D"))
print(r)

-- コンソールにはキャプチャされた以下の文字が表示される。
-- C
    

rt.socket._VERSION()

ソケット通信ライブラリとして使用しているLuaSocketのバージョンを返します。

tcp:accept()

TCPのオブジェクトtcpのメソッドであり、TCPクライアントからの接続を待ち、コネクションが完了した後クライアントオブジェクトを返します。

tcp:acceptは、サーバーオブジェクトで使用することができます。

成功した場合、クライアントオブジェクト(ユーザーデータ型)を返します。失敗した場合には、nil、エラーメッセージ(文字列)の2つを返します。

こちらの使用例を参照してください。

tcp:bind(address, port)

TCPのオブジェクトtcpのメソッドであり、オブジェクトにIPアドレス、ポート番号を割り当てます。

• address … 文字列型
• port … 数値型(0〜65535)

addressにはオブジェクトに割り当てるIPv4アドレスを指定します。"*"を指定した場合、全てのインタフェースに割り当てます。また、portにはオブジェクトに割り当てるポート番号を指定します。 portに0を指定した場合、システムが自動的に使用するポートを割り当てます。vRXの場合は49152〜65535、vRX以外の機種の場合は1024〜5000の範囲から割り当てます。

DHCPサーバーからIPアドレスが割り当てられるなど動的にIPアドレスが決定される場合には、addressに"*" を指定してください。

tcp:bindは、マスターオブジェクトで使用することができます。

成功した場合、1を返します。失敗した場合には、nil、エラーメッセージの2つを返します。

こちらの使用例を参照してください。

tcp:listen(backlog)

TCPのオブジェクトtcpのメソッドであり、TCPオブジェクトを接続待ち状態にします。

• backlog … 数値型(0〜128)

backlogには保留中の接続のキューの最大長を指定します。省略時のデフォルト値は 32 です。

tcp:listenは、マスターオブジェクトで使用することができ、成功した場合にはサーバーオブジェクトへ遷移します。

成功した場合、1を返します。失敗した場合には、nil、エラーメッセージの2つを返します。

こちらの使用例を参照してください。

tcp:close()

TCPのオブジェクトtcpのメソッドであり、TCPオブジェクトを閉じます。

オブジェクトで使用するソケットを閉じ、オブジェクトに割り当てられていたアドレス、ポート番号は他のアプリケーションで使用できるようになります。

tcp:closeは、マスターオブジェクト、サーバーオブジェクト、クライアントオブジェクトで使用することができます。

この関数の戻り値は 1 です。

こちらの使用例を参照してください。

tcp:connect(address, port)

TCPのオブジェクトtcpのメソッドであり、リモートホストへの接続を行います。

• address … 文字列型
• port … 数値型(1〜65535)

addressには接続するリモートホストのIPv4アドレスまたはホスト名を指定し、portにはリモートホストのポート番号を指定します。

接続に成功した場合、関数を呼び出したマスターオブジェクトはクライアントオブジェクトに遷移します。

tcp:connectは、マスターオブジェクトで使用することができます。

成功した場合、1を返します。失敗した場合には、nil、エラーメッセージの2つを返します。

こちらの使用例を参照してください。

tcp:getpeername()

TCPのオブジェクトtcpのメソッドであり、接続したリモートホストの情報を取得します。

tcp.getpeernameは、クライアントオブジェクトで使用することができます。

成功した場合、接続したリモートホストのIPv4アドレス、ポート番号の2つを返します。失敗した場合には、nil、エラーメッセージの2つを返します。

こちらの使用例を参照してください。

tcp:getsockname()

TCPのオブジェクトtcpのメソッドであり、オブジェクトに割り当てられたIPアドレスおよびポート番号を取得します。

tcp:getsocknameは、マスターオブジェクト、サーバーオブジェクト、クライアントオブジェクトで使用することができます。

成功した場合、オブジェクトに割り当てられたIPv4アドレス、ポート番号の2つを返します。失敗した場合には、nil、エラーメッセージの2つを返します。

こちらの使用例を参照してください。

tcp:getstats()

TCPのオブジェクトtcpのメソッドであり、オブジェクトで送受信したバイト数および生存時間(秒)といった統計情報を取得します。

tcp:getstatsは、マスターオブジェクト、サーバーオブジェクト、クライアントオブジェクトで使用することができます。

戻り値は、受信バイト数、送信バイト数、オブジェクトの生存時間の順で返します。

こちらの使用例を参照してください。

tcp:receive(pattern, prefix)

TCPのオブジェクトtcpのメソッドであり、オブジェクトからデータを読み込みます。

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

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

• "*a" : 接続が閉じるまでデータを読み込む。
• "*l" : 改行コード(LF:0x0A)を終端とした1行のを読み込む。改行コード(CR:0x0D、LF:0x0A)は戻り値には含まれない。
• 数値 : 指定したバイト数だけデータを読み込み、文字列型で返す。

prefixを指定した場合、受信データの前にprefixで指定した文字列が付加されて返されます。prefixを省略した場合には、受信データの前には何も付加されません。

tcp:receiveは、クライアントオブジェクトで使用することができます。

成功した場合には、受信データ(文字列型)を返します。失敗した場合には、nil、エラーメッセージ、エラーが発生するまでに受信したデータ(文字列型)の3つを返します。受信途中でコネクションが閉じられた場合には、エラーメッセージとして"closed"が返されます。

こちらの使用例を参照してください。

tcp:send(data, top, tail)

TCPのオブジェクトtcpのメソッドであり、接続した相手へデータを送信します。

• data … 文字列型
• top … 数値型(FIXNUM)
• tail … 数値型(FIXNUM)

dataには送信するデータを指定します。

topおよびtailを指定した場合、dataのtopの位置からtailの位置までの間にあるデータを送信します。topを省略した場合はdataの先頭から送信し、tailを省略した場合は、dataの最後までを送信します。
topやtailに負数を指定した場合、dataの最後から指定した数を引いた位置が起点となり、その位置がdata内に収まらない場合には、省略時の値が使用されます。また、topよりもtailの位置が前に来る場合には、dataは送信されません。

tcp:sendは、クライアントオブジェクトで使用することができます。

成功した場合には、dataの送信した最後の位置を返します。失敗した場合には、nil、エラーメッセージ、エラーが発生するまでに送信したdataの最後の位置を返します。

こちらの使用例を参照してください。

tcp:setoption(option, value)

TCPのオブジェクトtcpのメソッドであり、オブジェクトに内包するソケットのオプションを設定します。

• option … 文字列型
• value … 論理型

optionおよびvalueは、それぞれ次の値を取ります。

tcp:setoptionは、サーバーオブジェクト、クライアントオブジェクトで使用することができます。

成功した場合には 1 を返し、失敗した場合には nil を返します。

こちらの使用例を参照してください。

tcp:setstats(received, sent, age)

TCPのオブジェクトtcpのメソッドであり、オブジェクトの統計情報を指定した値でリセットします。

• received … 数値型(FIXNUM)
• sent … 数値型(FIXNUM)
• age … 数値型(FIXNUM)

received、sentおよびageに指定した値で、それぞれ受信バイト数、送信バイト数、およびオブジェクトの生存時間(秒)をリセットします。

received、sent、ageを省略した場合には、現在の受信バイト数、送信バイト数、およびオブジェクトの生存時間がそのまま使用されます。

tcp:setstatsは、マスターオブジェクト、サーバーオブジェクト、クライアントオブジェクトで使用することができます。

成功した場合には 1 を返し、失敗した場合には nil を返します。

こちらの使用例を参照してください。

tcp:settimeout(value, mode)

TCPのオブジェクトtcpのメソッドであり、オブジェクトのタイムアウト時間を設定します。

• value … 数値型(FIXNUM)
• mode … 文字列型

valueには、タイムアウトまでの秒数を指定します。nil または負数を指定した場合、処理が完了するまで無期限にブロックします。

modeには次の値を指定します。modeを省略した場合、'b' を指定した場合の動作となります。

• b … ブロックタイムアウト。1つの入出力操作が行われるまでにブロックする時間を指定する。
• t … ライブラリ関数から戻るまでの間にブロックする時間を指定する。

タイムアウト時間を設定し指定した時間が経過した場合、ブロックしていた関数は処理を中止してエラーを返します。

tcp:settimeoutは、マスターオブジェクト、サーバーオブジェクト、クライアントオブジェクトで使用することができます。

成功した場合、1を返します。失敗した場合には、nil、エラーメッセージの2つを返します。

こちらの使用例を参照してください。

tcp:shutdown(, mode)

TCPのオブジェクトtcpのメソッドであり、送信または受信、およびその両方を遮断します。

• mode … 文字列型

modeには次の値を指定します。省略した場合は、both を指定した場合の動作となります。

• both … 送受信共に遮断する
• send … 送信のみを遮断する
• receive … 受信のみを遮断する

tcp:shutdownは、クライアントオブジェクトで使用することができます。

戻り値は 1 です。

こちらの使用例を参照してください。

udp:close()

UDPのオブジェクトudpのメソッドであり、ソケットを閉じます。

オブジェクトで使用するソケットを閉じ、オブジェクトに割り当てられていたアドレス、ポート番号は他のアプリケーションで使用できるようになります。

udp:closeは、connectedオブジェクト、unconnectedオブジェクトで使用することができます。

戻り値は 1 です。

こちらの使用例を参照してください。

udp:getpeername()

UDPのオブジェクトudpのメソッドであり、接続したリモートホストのIPアドレスおよびポート番号を取得します。

udp:getpeernameは、connectedオブジェクトで使用することができます。

成功した場合、IPv4アドレスとポート番号を返します。失敗した場合には、nil、エラーメッセージの2つを返します。

こちらの使用例を参照してください。

udp:getsockname()

UDPのオブジェクトudpのメソッドであり、オブジェクトに割り当てられたIPアドレスおよびポート番号を取得します。

UDPでは、setsocknameまたはsendtoのどちらかを最初に呼び出すまで、どのアドレスも割り当てられません。

udp:getsocknameは、connectedオブジェクト、unconnectedオブジェクトで使用することができます。

成功した場合、IPv4アドレスとポート番号を返します。失敗した場合には、nil、エラーメッセージの2つを返します。

こちらの使用例を参照してください。

udp:receive(size)

UDPのオブジェクトudpのメソッドであり、オブジェクトからデータを読み込みます。

• size … 数値型(FIXNUM)

sizeには受信するデータグラムの最大サイズを指定します。sizeに指定したデータサイズと、デフォルトの最大サイズ(2048バイト)のうち、小さい方の値を使用します。sizeを省略した場合、受信するデータグラムの最大サイズは2048バイトとなります。

udp:receiveは、connectedオブジェクト、unconnectedオブジェクトで使用することができます。connectedオブジェクトは接続した相手からのデータだけ受信し、unconnectedオブジェクトは不特定のホストからのデータを受信します。

成功した場合には、受信したデータ(文字列型)を返します。失敗した場合には、nil、エラーメッセージの2つを返します。

こちらの使用例を参照してください。

udp:receivefrom(size)

UDPのオブジェクトudpのメソッドであり、オブジェクトからデータを読み込みます。

• size … 数値型(FIXNUM)

sizeには受信するデータグラムの最大サイズを指定します。sizeに指定したデータサイズと、デフォルトの最大サイズ(2048バイト)のうち、小さい方の値を使用します。sizeを省略した場合、受信するデータグラムの最大サイズは2048バイトとなります。

udp:receivefromは、unconnectedオブジェクトで使用することができます。udp:receiveが受信したデータだけを返すのに対して、udp:receivefromは受信したデータの他に、相手先の情報(IPアドレス、ポート番号)も返します。

成功した場合には、受信したデータ(文字列型)、送信元のIPアドレス、ポート番号の3つを返します。失敗した場合には、nil、エラーメッセージの2つを返します。

こちらの使用例を参照してください。

udp:send(datagram)

UDPのオブジェクトudpのメソッドであり、udp:setpeernameで指定した相手へデータを送信します。

• datagram … 文字列型

datagramには送信するデータを指定します。

UDPの送信はブロックされません。そのため、udp:settimeoutの値に処理が左右されることはありません。

udp:sendは、connectedオブジェクトで使用することができます。

成功した場合、送信したバイト数を返します。失敗した場合には、nil、エラーメッセージの2つを返します。

こちらの使用例を参照してください。

udp:sendto(datagram, ip, port)

UDPのオブジェクトudpのメソッドであり、指定した相手へデータを送信します。

• datagram … 文字列型
• ip … 文字列型
• port … 数値型(FIXNUM)

datagramには送信するデータを指定します。

ipおよびportにはデータの送信先ホストのIPv4アドレス、ポート番号を指定します。

UDPの送信はブロックされません。そのため、udp:settimeoutの値に処理が左右されることはありません。

udp:sendtoは、unconnectedオブジェクトで使用することができます。

成功した場合、送信したバイト数を返します。失敗した場合には、nil、エラーメッセージの2つを返します。

こちらの使用例を参照してください。

udp:setpeername(address, port)

UDPのオブジェクトudpのメソッドであり、通信する相手を指定、およびその解除を行います。

• address … 文字列型
• port … 数値型(FIXNUM)

addressには、IPv4アドレスまたはホスト名、'*'(アスタリスク)を指定します。'*'を指定した場合、通信相手との対応付けが解除されます。

portには通信する相手のポート番号を指定します。addressに '*' を指定した場合、portの値は無視されます。

udp:setpeernameは、connectedオブジェクト、unconnectedオブジェクトで使用することができます。unconnectedオブジェクトで指定した相手との対応付けが行われると、connectedオブジェクトへ遷移します。また、connectedオブジェクトにおいて、通信相手との対応付けを解除する場合、addressに '*' を指定し、portは省略します。この関数によって通信相手との対応付けが解消されると、unconnectedオブジェクトへと遷移します。

成功した場合、1 を返します。失敗した場合には、nil、エラーメッセージの2つを返します。

こちらの使用例を参照してください。

udp:setsockname(address, port)

UDPのオブジェクトudpのメソッドであり、オブジェクトにローカルアドレスおよびポート番号を割り当てます。

• address … 文字列型
• port … 数値型(FIXNUM)

addressには、オブジェクトに割り当てるIPv4アドレス、ホスト名、または'*'(アスタリスク)のいずれかを指定します。'*'を指定した場合、全てのローカルインタフェースに対して関連付けを行います。

portにはオブジェクトに割り当てるポート番号を指定します。portに0を指定した場合、システムが一時的なポートを割り当てます。vRXの場合は49152〜65535、vRX以外の機種の場合は21024〜25000の範囲から割り当てます。

udp:setsocknameは、unconnetedオブジェクトでデータを送信する前に1度だけ使用することができます。また、この関数を省略した場合、UDPでデータを送信するときに、システムが全てのローカルインタフェースに関連付け、一時的なポートの割り当てを行います。

成功した場合、1 を返します。失敗した場合には、nil、エラーメッセージの2つを返します。

こちらの使用例を参照してください。

udp:settimeout(value)

UDPのオブジェクトudpのメソッドであり、オブジェクトのタイムアウト時間を設定します。

• value … 数値型(FIXNUM)

valueには、タイムアウトまでの秒数を指定します。nil または負数を指定した場合、処理が完了するまで無期限にブロックします。

タイムアウト時間を設定し指定した時間経過した場合、ブロックしていた関数は処理を中止してエラーを返します。なお、UDPでは、tcp:sendおよびtcp:sendtoはブロックされないため、送信時には本関数による影響は受けません。

udp:settimeoutは、connectedオブジェクト、unconnectedオブジェクトで使用することができます。

成功した場合、1を返します。失敗した場合には、nil、エラーメッセージの2つを返します。

こちらの使用例を参照してください。

rt.mime.b64(data1, data2)

指定されたデータをBase64形式でエンコードして返します。

• data1 … 文字列型
• data2 … 文字列型

data1とdata2にはエンコードするデータ(文字列またはバイナリデータ)を指定します。
data2を指定した場合、data1とdata2を連結してBase64エンコードを行います。パディングは行わず、エンコードできなかった残りのバイトデータは2つ目の戻り値として返されます。 data2を省略した場合、data1をBase64エンコードします。このとき、data1全体がエンコードされるように必要に応じてパディングを付与します。

Base64エンコードした文字列を返します。data2を指定した場合、エンコードできなかった残りのデータを2つ目の戻り値として返します。
この後にに続くチャンクがある場合、2つ目の戻り値を第一引数のdata1に指定して本関数を呼び出します。

estr = rt.mime.b64("test")
print(estr)
-- estr = dGVzdA==
    

rt.mime.dot(NUM, data)

メッセージに含まれる<CRLF.CRLF>(※)を変換します。
※CRLF：改行を表すコード(アスキーコードでは、CR：0x0D、LF：0x0A)

SMTPでは、<CRLF.CRLF>を送信してメッセージの完了を相手に通知しています。送信メッセージの途中にこのパターンが含まれる場合、メッセージの途中までしか相手は受信しません。本関数では、メッセージ中に改行 CRLFの次にピリオド(.) が続く場合には、直後にもう1つピリオド(.) を追加します。

• num … 数値型(FIXNUM)
• data … 文字列型

dataには送信メッセージを指定します。

送信メッセージが複数のブロックに分割されている場合、numには直前のブロックの最後にある文字列のパターンに応じて、次のように数値を指定します。

SMTPのメッセージボディはCRLFから始まるように定義されています。そのため正しいメッセージに変換するためには、本関数を最初にコールする際にnumに 2 を指定しなけれななりません。

変換したメッセージ、dataの末尾にある改行コードの数の2つを返します。2つ目の戻り値である改行コードの数は、末尾がCRの場合は 1、末尾がCRLFの場合は 2となります。末尾がLFの場合でも直前がCRではない場合、2つ目の戻り値は 0 となります。
dataがnilまたは省略された場合には、nil、2 の2つを返します。
この後にに続くチャンクがある場合、2つ目の戻り値を第一引数のnumに指定して本関数を呼び出します。

-- Luaスクリプトでは、CR="\r", LF="\n" と記述します。
dotstr, num = rt.mime.dot(2, ".\r\nSend message.\r\n.\r\n.test\r\n")
print(dotstr)

--[[ 変換後の文字列。CRLFの次に"."が続く場合、"."が追加されている。
..
Send message.
..
..test
]]
    

rt.mime.eol(code, data, marker)

改行コードの変換を行います。

• code … 数値型(FIXNUM)
• data … 文字列型
• marker … 文字列型

dataには改行コードを変換する文字列を指定します。

送信メッセージが複数のブロックに分割されている場合、codeには直前のブロックの最後にある文字のアスキーコードを指定します。

markerには改行コードを指定します。dataに含まれる改行コードをmarkerで指定した改行コードに置き換えます。markerを省略した場合には、改行コードを<CRLF>に置き換えます。
※ 改行コードとは、次のいずれかを指します。CR, LF, CRLF, LFCR

改行コードを変換した文字列と、2つ目の戻り値には、dataの末尾が改行コードの一部だった場合にはそのアスキーコードを返し、それ以外の場合には 0 を返します。 dataがnilまたは省略された場合には、1つ目の戻り値でnilを返し、2つ目の戻り値は 0 となります。
この後に続くブロックがある場合、2つ目の戻り値を第一引数のcodeに指定して本関数を呼び出します。

-- Luaスクリプトでは、CR="\r", LF="\n" と記述します。
str, num = rt.mime.eol(0, "test\rexample\rtest\r", "\r\n")
print(str)
-- 改行コードを可視化して表示する
print(string.gsub(str, "\r\n", "\\r\\n"))

--[[ 変換結果（コンソールに出力された文字列）
test
example
test

test\r\nexample\r\ntest\r\n     3
]]
    

rt.mime.qp(data1, data2, marker)

指定されたデータをQuoted-Printable形式でエンコードして返します。

• data1 … 文字列型
• data2 … 文字列型
• marker … 文字列型

data1とdata2にはエンコードするデータを指定します。
data2を指定した場合、data1とdata2を連結してQuoted-Printableエンコードを行います。パディングは行わず、エンコードできなかった残りの文字は2つ目の戻り値として返されます。 data2を省略した場合、data1をQuoted-Printableエンコードします。このとき、data1全体がエンコードされるように必要に応じてパディングを付与します。

markerには改行コードを指定します。指定されたデータに含まれる改行コード<CRLF>をmarkerで指定した改行コードに置き換えます。markerを省略した場合には、改行コードを<CRLF>に置き換えます。

Quoted-Printableエンコードした文字列を返します。data2を指定した場合、エンコードできなかった残りのデータを2つ目の戻り値として返します。
この後に続くデータブロックがある場合、2つ目の戻り値を第一引数のdata1に指定し、続くデータブロックをdata2に指定して本関数を呼び出します。

estr, rem = rt.mime.qp("テスト")
print(estr)
-- estr = =83e=83X=83g
    

rt.mime.qpwrp(left_len, data, length)

Quoted-Printableエンコードされた文字列の1行の長さがlengthで指定した長さ以下になるように改行します。

• left_len … 数値型(FIXNUM)
• data … 文字列型
• length … 数値型(FIXNUM)

dataにはQuoted-Printableエンコードされた文字列を指定します。

lengthには1行の長さを指定します。lengthを省略した場合、デフォルト値は 76 です。"=XX"のようなQuoted-Printableエンコードされた文字列の途中でlengthで指定した長さに達した場合、Quoted-Printableエンコードされた文字の前で改行します。また、文字列に改行コード(CRLF)が含まれる場合には、1行がlengthの長さ未満であっても、改行コードの位置で改行されます。

送信メッセージが複数のブロックに分割されている場合、left_lenには直前のブロックを本関数で処理した際に出た最終行の余りの長さを指定します。余りの長さは直前のブロックを本関数にて処理した際の2つ目の戻り値として返されます。
処理する文字列が先頭のデータである場合、left_lenには 0 を指定します。

指定した長さで改行された文字列、最終行の余りの長さ(lengthから最終行の長さを引いた値)の2つを返します。dataに続く次のブロックがある場合、2つ目の戻り値を第一引数のleft_lenに指定して本関数を呼び出します。

--Quoted-Printableエンコードされた文字列の配列
-- 「あいうえおかきくけこ」
-- 「さしすせそたちつてと」
tbl = {
 "=82=A0=82=A2=82=A4=82=A6=82=A8=82=A9=82=AB=82=AD=82=AF=82=B1",
 "=82=B3=82=B5=82=B7=82=B9=82=BB=82=BD=82=BF=82=C2=82=C4=82=C6"
}

estr = {}
len = 0
for i, v in ipairs(tbl) do
  estr[i], len = rt.mime.qpwrp(len, v, 16)
end
print(estr[1] .. estr[2])

--[[ 変換結果（コンソールに出力された文字列）
=
=82=A0=82=A2=82=
=A4=82=A6=82=A8=
=82=A9=82=AB=82=
=AD=82=AF=82=B1=
=82=B3=82=B5=82=
=B7=82=B9=82=BB=
=82=BD=82=BF=82=
=C2=82=C4=82=C6
]]
    

rt.mime.unb64(data1, data2)

指定されたデータをBase64形式でデコードして返します。

• data1 … 文字列型
• data2 … 文字列型

data1とdata2にはBase64エンコードされた文字列を指定します。
data2を指定した場合、data1とdata2を連結してBase64形式でデコードを行います。デコードできなかった残りの文字列は2つ目の戻り値として返されます。 data2を省略した場合、data1をBase64形式でデコードします。

Base64形式でデコードした文字列を返します。data2を指定した場合、デコードできなかった残りの文字列を2つ目の戻り値として返します。
この後に続くブロックがある場合、2つ目の戻り値を第一引数のdata1に指定して本関数を呼び出します。

-- base64エンコードされた文字列をデコードする
estr = "gqKC64LNgsmC2YLWgsY="

str = rt.mime.unb64(estr)
print(str)

--[[ デコードした結果。(コンソールに出力された文字列)
いろはにほへと
]]
    

rt.mime.unqp(data1, data2)

指定されたデータをQuoted-Printable形式でデコードして返します。

• data1 … 文字列型
• data2 … 文字列型

data1とdata2にはQuoted-Printableエンコードされた文字列を指定します。
data2を指定した場合、data1とdata2を連結してQuoted-Printable形式でデコードを行います。デコードできなかった残りの文字列は2つ目の戻り値として返されます。 data2を省略した場合、data1をQuoted-Printable形式でデコードします。

Quoted-Printable形式でデコードした文字列を返します。data2を指定した場合、デコードできなかった残りの文字列を2つ目の戻り値として返します。
この後に続くブロックがある場合、2つ目の戻り値を第一引数のdata1に指定して本関数を呼び出します。

-- Quoted-Printableエンコードされた文字列をデコードする
data = "=83e=83X=83g"

str = rt.mime.unqp(data)
print(str)

--[[ コンソールへの出力結果
テスト
]]
    

rt.mime.wrp(num, data, length)

文字列をlengthで指定した長さ以下になるように改行します。

• left_len … 数値型(FIXNUM)
• data … 文字列型
• length … 数値型(FIXNUM)

dataには指定した長さで改行する文字列を指定します。

lengthには1行の長さを指定します。lengthを省略した場合、デフォルト値は 76 です。lengthで指定した長さで文字列を改行します。また、文字列に改行コード(CRLF)が含まれる場合には、1行がlengthの長さ未満であっても、改行コードの位置で改行されます。

送信メッセージが複数のブロックに分割されている場合、left_lenには直前のブロックを本関数で処理した際に出た最終行の余りの長さを指定します。余りの長さは直前のブロックを本関数にて処理した際の2つ目の戻り値として返されます。
処理する文字列が先頭のデータである場合、left_lenには 0 を指定します。

指定した長さで改行された文字列、最終行の余りの長さ(lengthから最終行の長さを引いた値)の2つを返します。dataに続くブロックがある場合、2つ目の戻り値を第一引数のleft_lenに指定して本関数を呼び出します。

-- 文字列の配列
tbl = {
 "abcdefghijklmnopqrstuvwxyz",
 "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
 "0123456789"
}

estr = {}
len = 0
for i, v in ipairs(tbl) do
  estr[i], len = rt.mime.wrp(len, v, 10)
end

print(estr[1] .. estr[2] .. estr[3])


--[[ 改行された結果。(コンソールに出力された文字列)

abcdefghij
klmnopqrst
uvwxyzABCD
EFGHIJKLMN
OPQRSTUVWX
YZ01234567
89
]]
    

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 … テーブル型

指定された時刻を表す数値で、「1980年1月1日 9時0分0秒」からの経過秒数を返します。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の戻り値となります。