** This document is provided as only in Japanese, sorry **

qpの使い方
==========

2006年12月19日
清水俊彦

はじめに
========

私がqpを作り始めたのは2004年の秋口からです。
自分の蔵書管理を行うためのWebアプリケーションで使うための簡単な
SQL実行コマンド（当時はqueryって名前にしていました）を作ったのが
きっかけです。
その後、様々な機能追加を続けたところ、いろんな場面で使えるコマン
ドに成長してしまいました。

そのqueryをブラッシュアップし、機能の整理と今後の拡張を考慮した
のがqpです。

qpのゴールは、SQLとHTMLさえ知っていれば、webアプリケーションが作
れる環境を提供することです。

qpの世界にようこそ。


qpとは？
========

qpはmysql専用のツールで、sql文の実行結果を指定の書式に整えて出力し
てくれます。
特にCGIでの親和性が高くなるように設計しています。

次のような特徴があります。
・sql文をそのまま記述できます。
・sql文に与えるパラメタは簡単な記述方法で記述できます。
・出力書式は自由に指定できます。
・forthライクなコマンドを使って簡単な実行制御が行えます
  ※まだ未実装です。。。orz

てな説明だけではとてもわかりにくいので、スクリプト例を示します。

----------ここから
format sample
  t No
  fr %#
  t タイトル
  fl <b>%2</b>
  t 金額
  fr %?3=0:ただ:%!3=0:%3円:
end

sql default sample table 
  select no , title , price 
    from goods 
    where price <= %maxPrice
end
---------ここまで

これをsample.qp という名前で保存しておき、次のように実行します。

./qp -D database_name -u user -q "maxPrice=100" sample.qp

これを実行すると次のようなhtmlを標準出力に出力します。

---------ここから
  <tr> <th> No</th><th> 品名</th><th> 金額</th> </tr>
  <tr>
    <td> 1</td>
    <td> <b>humbreger</b></td>
    <td align="right"> 80円</td>
  </tr>
  <tr>
    <td> 2</td>
    <td> <b>coffee</b></td>
    <td align="right"> 100円</td>
  </tr>
  <tr>
    <td> 3</td>
    <td> <b>smile</b></td>
    <td align="right"> ただ</td>
  </tr>
---------ここまで

このように簡単なスクリプトを書くことで、SQLでの抽出結果を様々
にフォーマット化して出力が行えるツールです。


インストール
============

qpのインストールには以下の環境が必要です。

1) LinuxかWindows
   LinuxかWindowsの動くマシンが必要です。
　 作者はLinuxマシンで稼動していますが、開発はWindows上でも行っ
   ています。Linuxはおおむね何でも動くと思います。作者は
   fedora core4を使っています。

2) mysql
  当然ながらmysqlが必要です。
　qpはmysql4.1で動作するように開発してします。
  現在は5.0系での動作確認は未実施です。

3)fpc (pascalコンパイラ)
   qpはfpcで記述されていますので、コンパイルにfpcが必要です。
　 fpcは http://www.freepascal.org にて無償で入手できます。
   少なくとも2.0.4以上が必要です。
   

上記が揃ったら以下の手順でインストールを行ってください。

1) qpのアーカイブを適当なディレクトリに展開してください。
   展開後は次のようなディレクトリができます。
   　Readme     : 今読んでいるこの文書
   　Readme.scpt: スクリプトファイルの書き方のドキュメント
     src/q      : qpコマンドのソース
	 src/u      : 他のユーティリティなどのソース(汎用でないのが多いです)
     bin        : unix用の実行形式（リポジトリから取得してください)
     exe        : windows用の実行形式（リポジトリから取得してください)

2) Makefileの以下の点を修正してください
　   INST_DIR : 実行形式をインストールするディレクトリ。

3) makeを実行してください。この時、インストール先のディレ
   クトリへの書き込みができるユーザで実行してください。
     $ cd src/q
     $ make clean
     $ make

以上でインストールは終了です。

コンパイルエラー/リンクエラーが出ることはないと思いますが、
出た場合は、mysql関連のライブラリが/usr/libにあることを確認
してください。(特にlibmysqlclient.so)



コマンドラインオプション
========================

qpのコマンドラインは次の形式で指定します。

　qp [オプション] {SQL|ファイル名}

利用できるオプションは次の通りです。

  -u name : mysqlに接続する時のユーザ名。デフォルトは現在のuid
  -p pass : mysqlに接続する時のパスワード。デフォルトはなし。
  -H host : mysqlに接続する時のホスト名。デフォルトはlocalhost
  -D name : 接続するデータベース名。デフォルトはtest
  -U str  : QUERY_STRING形式の文字列。パラメタ受渡し用
  -0 msg  : 該当データがない場合のメッセージ文字列
  -h      : table形式の場合、<th>～</th>を出力しない。

また、パラメタとして、ファイル名の指定が必須です。
指定の名称のファイルが存在しない場合のみ、その文字列をSQLと
みなして実行します。


スクリプトファイルの書き方
===========================

Readme.scriptをご覧ください。


                                                                      以上


