[Home]Plua/PluaDoc

Amatubu_Wiki | Plua | RecentChanges | Preferences

Plua ドキュメンテーション

1. 導入

Plua は Lua 4.0.1 (に加えて小さな IDE) を Palm Computing のプラットフォームに移植したものです。Lua は TeCGraf - the Computer Graphics Technology Group of PUC-Rio, Brazil でデザインされたプログラミング言語です。

Lua についての詳しい情報は [Lua] にあります。(注意: 私は TeCGraf や PUC-Rio とは無関係です)

このソフトウェアは完全に無保証です。ですから、自己責任で使用してください。 Plua はリバースエンジニアリングやどんな方法でも変更することはできません。Plua をソフトウェア集に含める場合は、オンラインであるかどうかに関わらず、まず作者に許可を求めてください。Plua を売ったり再配布したりするために Plua を変更することは許されていません。

Plua is Copyright (c) 2001-2005 Marcio M. Andrade.

2. 操作

Plua は 2 つの異なるモードで使用することができます。最初のひとつは素早い 読み込み-評価-表示 のループを提供します。このモードではプログラムを入力してすぐに評価させることができます。画面の下半分にプログラムを入力すると結果が上半分に表示されます。入力中のプログラムを評価するには、Run ボタンをタップします。入力中のプログラムを消すには、Clear ボタンをタップします。

例えば、テキストフィールドにこのプログラムを入力した場合:

 print("Result = ", 2*3)

Plua は結果エリアに以下の内容を表示するでしょう:

 Result =   6

ふたつめのモードも Lua のプログラムを実行することができますが、2 つの違いがあります:

ファイル選択画面にアクセスするためには File ボタンをタップします。右上で 4 つのファイルタイプ(Memo、Doc、Stream、Card)から選択することができます。選択されたタイプの現存するプログラムのリストが表示されます。

Lua コードの Memo を作成する場合、"-- " (引用符は不要で、後ろにスペースが必要です)で始まり、プログラム名(通常はひとつの単語)が ".lua" で終了していなくてはなりません。そうでないと、Plua で表示されないでしょう。Doc、Stream、VFS ファイルも同様に ".lua" で終了していなければなりません。

リストからひとつプログラムを選び、Run ボタンをタップして実行します。Plua は全画面モードに切り替わり、プログラムを実行します。プログラムが終了したとき、Plua はプログラム選択画面に戻ります。終了する前にプログラムを止めたい場合には、アプリケーションアイコンをタップします。Plua は VFS ファイルを拡張カードの /PALM/Programs/Plua/src から探します。

Compile ボタンはプログラムを PRC ファイルにコンパイルするために使用されます。生成された PRC は他のプログラムと同じようにアプリケーションランチャーから実行することができます。しかしながら、Plua もしくは PluaRT(Plua ランタイム)がインストールされている必要があることに注意してください。Plua アプリケーションを実行したいだけならば両方をインストールする必要はありません。Plua もランタイムもインストールされていない状態でコンパイルしたプログラムが実行された場合、エラーメッセージが表示されてプログラムは停止します。生成された PRC はあらかじめ準備された固定のアイコンになります。プログラムを実行するためにコンパイルが必須ではないことに注意してください。Plua 内でプログラムを実行したいだけならば、Run ボタンを使うことができます。Compile ボタンはあなたのプログラムからスタンドアロンの RPC を生成したい場合だけに使うべきです。

Main ボタンをクリックするとメイン画面に戻ります。メモ(Memo)については、さらに 2 つのボタンがあります: New と Edit で、それぞれメモを作成、編集するためのものです。Doc については、同じように Edit ボタンがあります。このボタンをタップすると、Plua はサードパーティアプリケーションの SrcEdit を起動し、doc ファイルを編集することができます。このアプリケーションがインストールされていない場合は何も起こりません。

初期設定(Preference)はメニューの Preferences からアクセスすることができます。"Read-only-mode" がチェックされている場合、データベースへの書き込みアクセスや削除は中止され、エラーメッセージが表示されるでしょう。"Clear output" がチェックされている場合、Clear ボタンは出力エリアも消去します。

Plua のオンラインヘルプシステムは PalmOS の標準の "Find" ボタンからアクセスできます。メイン画面やメモの編集中に Find ボタンをクリックすると、Plua はすべての関数名を表示するダイアログを開きます。関数名を選択して Goto をタップすれば Plua は関数のリファレンスを表示します。Index ボタンをクリックすると、すべての関数名がもう一度表示されます。Done をタップするとヘルプダイアログを閉じます。メイン画面やメモの編集中に、Find ボタンをタップする前にまず単語を選択しておくこともできます。この場合には、ヘルプダイアログは直接関数のリファレンスを開きます。ヘルプシステムを使用するためには、まず pluahelp.prc をインストールしなければなりません。

3. テクニカルノート

完全な Lua パッケージを移植するために大変な努力をしています。ソースコードのいくつかの部分はほとんどそのままですが、それ以外の部分は PalmOS のアーキテクチャにあうように大きく変更されています。

3.1. 互換性

Plua は PalmOS 3.1 以降を必要とします。インデックスカラーのサポート(2 ビット、4 ビット、8 ビット)には少なくとも PalmOS 3.5 が必要です。それ以外のバージョンでは、ハードウェアがグレースケールをサポートしている場合でも画面はモノクロ(カラーは 0=white と 1=black)と見なされます。

3.2. 標準の Lua ディストリビューションと比較したときの制限事項

3.3. 標準の Lua ディストリビューションからの拡張機能

標準の Lua ライブラリの関数に加えて、Plua は PalmOS 独自の機能にアクセスするための追加関数を提供しています。以下のリストでは、オプションのパラメータを角括弧 [] であらわしています。

データベース入出力関数:

ディレクトリ関数:

リソース関数:

シリアル入出力関数:

低レベルのグラフィック関数:

UI 関係の関数:

イベント関数:

サウンド関数:

ビット単位の操作関数:

バイナリデータ関数:

その他の関数:

組み込み定数:

4. 簡単なチュートリアル

このセクションはあなたがすでに Lua 言語をよく知っていることを仮定し、Palm プラットフォームに関連した点に焦点をあわせます。言語 Lua を知らない場合でも、心配することはありません。そのホームページにたくさんのドキュメントがあります。ドキュメントを読まずにすぐにプログラミングを始めたいのであれば、以下はいくつかのティップスです:

4.1. ディスプレイ

Plua はあなたのデバイスの画面をビットマップディスプレイとして扱うため、個々のピクセルを指定することができます。"標準出力" もディスプレイに割り当てられていますので、print() や write() を使えば文字がディスプレイに表示されます。Plua は現在のカーソル位置を数字のペア (x,y) に保存します。この位置はディスプレイに何かを書くたびに更新されます。

以下の命令は

 pline(0,0,19,19)

(0,0) の位置から (19,19) までの直線を描き、カーソル位置を (19,19) に更新するでしょう。次の命令は

 write("abc")

(19,19) の位置を開始位置とする "abc" という文字列を表示し、カーソルは (19,19+d) に移動されるでしょう。d は現在のフォントで描かれた文字列 "abc" の横幅をピクセル単位で表したものです。

カーソル位置の他に、Plua は前景色と背景色とフォントを保存します。下記の例は "Plua" という文字列を黒字に赤で太字フォントで描きます:

 pcolor(prgb(255,0,0), prgb(0,0,0))
 pfont(1) print("Plua")

Plua は 1 ビットのモノクロディスプレイ、2 ビットか 4 ビットのグレースケールディスプレイ、8 ビットのカラーディスプレイで動作します。前景色と背景色は、カラーが使用できないときには最も近いグレースケールトーンに割り当てられます。pmode() 関数を呼ぶことにより、デバイスのディスプレイ特性を調べることができます:

 width, height, depth, hasColor = pmode()
 print(width, height, depth, hasColor)

width と height はピクセル単位でのディスプレイ解像度です。depth は 1、2、4、8 のいずれかで、ディスプレイがカラーをサポートしている場合 hasColor は 1 になり、サポートしていなければ 0 になります。カラーデバイスにおいては、prgb() 関数を使って指定された赤、緑、青の成分からなる色のインデックスを調べることができます。下記の例は標準のカラーパレットを使った 8 ビットのカラーデバイスで実行すれば 125 が表示されるでしょう。

 red = prgb(255,0,0)
 print(red)

Plua は Logo のような "タートル" ポインタをサポートしています。pwalk() と pturn() を使って線を描きながらディスプレイを歩き回ることができます。下記の例はディスプレイを消去し、ディスプレイの中心にカーソルを移動して小さな螺旋を描きます。

 pclear() w,h = pmode() pmoveto(w/2,h/2)
 for d = 1,20,1 do
   pwalk(d) pturn(-40)
 end

下記の例はビットマップを表示する方法を示しています。11000 はいくつかの Palm ROM に格納されている "Taxi" ビットマップのリソース ID です。

 pclear()
 bmp = popenres("Tbmp", 11000)
 pdrawbmp(bmp)
 pcloseres(bmp)

ディスプレイに関する最後の注意事項です: 画面の右端まで書いても折り返しはされず、画面の一番下の行に書いても画面はスクロールしません。

4.2. ユーザインタフェース

標準の PalmOS の UI コンポーネントは簡単に作成し、やり取りすることができます。これをおこなうための通常の方法はいくつかのコンポーネントを作成し、その後 UI イベントを待つイベントループに入ることです。以下の例がまさにこれを行っています:

 textField = pfield(1,20,20)
 lengthButton = pbutton("Length") pnl()
 while 1 do
   ev,id = pevent()
   if ev == ctlSelect and id == lengthButton then
     print(strlen(pgettext(textField)))
   end
 end

pfield() と pbutton() 関数はそれぞれ 1 行のテキストフィールドとボタンを作成します。pnl() 関数はカーソルをボタンの下に移動させます。無限ループの中で pevent() が呼ばれ、これで UI イベントが発生するまでアプリケーションは停止します。我々の例では、"Length" ボタンが押されたときにイベント(ctlSelect)が発生します。pevent() はイベント ID とコンポーネント ID (この場合はボタンの ID)を返します。プログラムは pgettext() を用いてテキストフィールドの内容を取得し、その長さを表示します。

注意: このプログラムは無限ループに入りますので、これを止めるにはアプリケーションアイコンをタップするしかありません。

以下の例は pinput()、palert()、pconfirm() を使用しています。

 s = pinput("Write something")
 if s ~= nil then
   palert("You wrote "..s)
 end

 if pconfirm("Are you tired ?") then
   print("Me too")
 else
   print("Me neither")
 end

アプリケーションにメニューを設定するためには、以下のように pmenu() を使用します。

 pmenu({"O:Open", "Preferences", "-", "Q:Quit"})

メニューには 4 つのアイテムが現れるでしょう: 固定の "About Plua" アイテム、固定の区切り、"O" のショートカットがついた "Open" アイテム、ショートカットなしの "Preferences" アイテム、区切り、"Q" のショートカットがついた "Quit" アイテムです。制限事項: 現在のところ pmenu() は PalmOS 3.5 以降でのみ動作します(それ以前のバージョンは動的にメニューを設定することができません)。また、フルスクリーンモードでのみ動作し、同じメニューバーにひとつ以上のメニューを定義することはできません。pmenu() はいつでも呼び出すことができ、現在のメニューを新しいもので置き換えます。

メニューアイテムが選択された(About アイテムを除く)とき、pevent() から menuSelect イベントが返ります。上の例では、"Preferences" が選択されたとき、pevent() は menuSelect と 2 を返すでしょう。これは、ユーザーが定義した 2 つめのアイテムが選択されたことを意味します。

4.3. データベース入出力

PalmOS は本当のファイルシステムを持っていませんが、Plua は Lua バーチャルマシンに基礎となる OS が I/O をサポートしているように見せかけます。"標準出力(stdout)" 識別子はディスプレイにマッピングされ、"標準エラー出力(stderr)" 識別子はダイアログボックスにマッピングされ、stderr に書き込まれたものを表示します。

標準的なファイルは PalmOS の File Stream API を用いて実装されています。このため、Lua プログラムは通常通りファイルを開き、作成し、読み書きすることができます。データベースタイプやクリエータを知ることなく。以下の例がそのことを示しています:

 f = openfile("MyOutput", "w")
 write(f, "This is being written to a PalmOS stream database")
 closefile(f)

データベース MyOutput が書き込み用に開かれ(もし存在しなければ作成されます)、文字列が書き込まれ、閉じられます。

PalmOS のデータベースを直接操作するための関数も存在します。もしそうしたいならば。それらは上記の "標準の Lua ディストリビューションからの拡張機能" セクションにリストされています。以下の例はすべての MemoPad レコードについて、それぞれのレコードの 1 行目を表示します:

 f,n = opendb("MemoDB", "r")
 for i = 0,n-1,1 do
   openrec(f, i)
   s = read(f, "*l")
   print(s)
 end
 closedb(f)

read() 関数は Lua ライブラリの標準 I/O に属します。I/O 関数はストリームファイルにも標準のデータベースにも同じように働きます。標準のデータベースの場合、それぞれのレコードはサブファイルのように働き、すなわち、EOF 状態になったとき、最初から最後まで読み込まれたということです。データベースからの読み込みを続けるためには、次のレコードを開くために openrec() を呼び出さなければなりません。

opendb() に有効なモードは以下の通りです:

最初の 2 つのモードには "b" を追加することができます("rb" や "r+b" というように)。これはバイナリモードを意味します。レコードがバイナリモードで読み込まれるとき、最後の文字が ASCII 0(ヌル文字)の場合この最後の文字は無視されます。この機能は、MemoPad のようなアプリケーションはいつもレコードの最後にヌル文字を書き込むため、なくてはならないものです。あるケースではヌル文字を無視しなければなりませんが、ほかのケースでは(バイナリデータのような場合)重要です。

The standard dofile() function works with Doc files, MemoPad records and compiled applications. If there is a Doc file named "name.lua", for example, it can be included by using dofile("name.lua"). For MemoPad records, the record name must be prefixed with the string "memo:". If there is a record named "-- name.lua", for example, it can be included by using dofile("memo:name.lua"). For applications, the compiled lua code can be included by using dofile("appname"), where "appname" is the PRC name.

A note about error handling in file I/O: in case of success, the functions marked as returning true in fact return an userdata value (which is true, since any non-nil value is considered true in Lua). The value of this userdata is not important, it is used just to make it different from false (nil). In case of failure, all I/O functions (except for read) return two additional values besides nil. The second value is a string with the error message and the third value is the numeric error code. The error messages/codes are inspired on the Unix C Library (libc) errors. Currently the following errors may be reported:

For example, suppose opendb() is used to open a database, like in the following code:

 f,n,e = opendb("Test", "r")

If there is a database named Test, f will be assigned a handle to the opened database, n will be assigned the number of records in the database and e will be assigned nil. However, if there is no databse named Test, f will assigned nil, n will be assigned the string "No such file or directory" and e will be assigned 2 (for ENOENT). This example illustrates how a function may return different number of values (and possibly of different types) depending on its execution.

4.4. シリアル入出力

The function openser() opens an IO port known to the New Serial Manager. Currently only the serial (RS-232) and infrared (IrComm) ports are supported. The following example shows how to open the serial port and wait for data in a efficient way.

 f = openser("serial0", 57600, "8N1")
 while 1 do
   ev = pevent()
   if ev == ioPending then
     s = read(f, 8)
     print(s)
   elseif ev == penDown then
     break
   end
 end
 closeser(f)

When data is available at the serial port, the ioPending event is sent. Note that it is not possible to know how much data is available. The read() function reads at most 8 bytes and returns. If less than 8 bytes are available, read() returns them without blocking. If more than 8 bytes are available, they remaining bytes are hold in the Serial Manager buffer. In the next loop interaction, another ioPending event will be sent, and so on. In this example, the loop is stopped when the user taps anywhere in the screen with the pen.

The functions openser() and closeser() may also return the error messages/codes defined for file I/O.

4.5. 統一された入出力

ひとつ前のセクションでは正規のデータベース、ストリームデータベース、シリアル入出力を扱う方法を説明しました。それぞれの PalmOS の API について新しい関数を作る代わりに、Plua は標準的な Lua の関数(openfile、read、write、closefile)を使って統一された入出力操作をサポートしています。統一された入出力は VFS、TCP/IP、そして新しいシリアルマネージャによってアクセス可能なすべてのデバイスをサポートしています。下記のテーブルはサポートされているすべてのオプションをあらわしています。

タイプ 構文
ストリームデータベース openfile("name", "mode") openfile("MyDatabase", "r+")
Doc データベース openfile("name", "mode") openfile("MyDoc", "r")
Memo データベース openfile("memo:name", "mode") openfile("memo:Data", "w")
シリアルマネージャ openfile("srm:device:baud:word") openfile("srm:serial0:9600:8N1", "w")
VFS ファイル openfile("vfsn:path", "mode") openfile("vfs0:/Palm/Programs/Readme.txt", "r")
TCP ソケット openfile("tcp:host:port") openfile("tcp:www.lua.org:80")
UDP ソケット openfile("udp:host:port") openfile("udp:host.com:7")

4.6. バイナリデータ

Most PalmOS applications save persistent data in one or more PDB's. This information is written in binary form, that is, a sequence of bytes usually representing the encoding of a C structure. In Lua, however, information is stored in numbers, strings and tables, and their internal binary representation is not relevant. In order to read and write binary data, Plua provides the functions pack() and unpack(). The following example shows the usage of these functions along with database access functions.

Storing a a table into a PDB record:

 table = {25, "Plua", 3.1416, 9999}
 data = pack("BSDW", table)
 f = opendb("MyBinaryData", "wb")
 index = createrec(f, strlen(data))
 openrec(f, index)
 write(f, data)
 closedb(f)

According to the format string "BSDW", the number 25 (the first element) is packed as a byte, the string "Plua" is packed as a null-terminated string, the number 3.1416 is packed as a double and the number 9999 is packed as a 16 bit word. The returned data is a binary string of 1+5+8+2 = 16 bytes. This data is stored as record in the MyBinaryData PDB.

Reading the same record into a table:

 f = opendb("MyBinaryData", "rb")
 openrec(f, index)
 data = read(f, "*a")
 table = unpack("BSDW", data)
 closedb(f)

After this, the returned table will have the same elements as the original one.

4.7. ライブラリ

コンパイルされた Plua アプリケーションをライブラリとして使うことができます。便利な Lua の関数のセットがあり、他の開発者に提供したいとしましょう。すぐわかる方法はソースコードを配布することですが、他の選択肢もあります: メモ帳(MemoPad)や Doc ファイルに関数を書き、通常のアプリケーションと同じようにコンパイルします。例えば、生成された PRC が "MyLib" という名前ならば、他のアプリケーションは dofile("MyLib") とするだけで関数を読み込むことができます。あなたの "ライブラリ" を配布するには、コンパイルしたときに作られた "MyLib.prc" という PRC を配布します。

C ライブラリをビルドして Plua と連携させるための説明は、 libkit の例を参照してください。

[原文]


Amatubu_Wiki | Plua | RecentChanges | Preferences
This page is read-only | View other revisions
Last edited October 9, 2006 15:15 by Amatubu (diff)
Search:

Copyright (c) 1996-2019 naoki iimura e-mail