.\"	$NetBSD: editline.3,v 1.4 1997/01/14 04:17:23 lukem Exp $
.\"
.\" Copyright (c) 1997 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This file was contributed to The NetBSD Foundation by Luke Mewburn.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.\" %FreeBSD: src/lib/libedit/editline.3,v 1.8.2.7 2001/12/17 10:08:30 ru Exp %
.\"
.\" $FreeBSD$
.Dd January 11, 1997
.Os
.Dt EDITLINE 3
.Sh 名称
.Nm editline ,
.Nm el_init ,
.Nm el_end ,
.Nm el_reset ,
.Nm el_gets ,
.Nm el_getc ,
.Nm el_push ,
.Nm el_parse ,
.Nm el_set ,
.Nm el_source ,
.Nm el_resize ,
.Nm el_line ,
.Nm el_insertstr ,
.Nm el_deletestr ,
.Nm el_data_set ,
.Nm el_data_get ,
.Nm history_init ,
.Nm history_end ,
.Nm history
.Nd ラインエディタと歴史関数
.Sh ライブラリ
.Lb libedit
.Sh 書式
.Fd #include <histedit.h>
.Ft EditLine *
.Fn el_init "const char *prog" "FILE *fin" "FILE *fout"
.Ft void
.Fn el_end "EditLine *e"
.Ft void
.Fn el_reset "EditLine *e"
.Ft const char *
.Fn el_gets "EditLine *e" "int *count"
.Ft int
.Fn el_getc "EditLine *e" "char *ch"
.Ft void
.Fn el_push "EditLine *e" "const char *str"
.Ft int
.Fn el_parse "EditLine *e" "int argc" "char *argv[]"
.Ft int
.Fn el_set "EditLine *e" "int op" "..."
.Ft int
.Fn el_source "EditLine *e" "const char *file"
.Ft void
.Fn el_resize "EditLine *e"
.Ft const LineInfo *
.Fn el_line "EditLine *e"
.Ft int
.Fn el_insertstr "EditLine *e" "char *str"
.Ft void
.Fn el_deletestr "EditLine *e" "int count"
.Ft void
.Fn el_data_set "EditLine *e" "void *data"
.Ft void *
.Fn el_data_get "EditLine *e"
.Ft History *
.Fn history_init
.Ft void
.Fn history_end "History *h"
.Ft const HistEvent *
.Fn history "History *h" "int op" "..."
.Sh 解説
.Nm editline
ライブラリには、汎用のライン編集と歴史関数が備わっています。これは
.Xr sh 1
にあるものと類似しています。
.Pp
これらの関数は
.Nm libedit
ライブラリで利用できます
(これには
.Nm libtermcap
ライブラリが必要です)。プログラムは
.Fl ledit ltermcap
とリンクする
必要があります。
.Sh ライン編集関数
ライン編集関数は、共通のデータ構造、
.Fa EditLine
を使用します。これは
.Fn el_init
によって作成され、
.Fn el_end
によって解放されます。
.Pp
以下の関数が利用できます。
.Bl -tag -width 4n
.It Fn el_init
ラインエディタを初期化し、他のすべてのライン編集関数が使用するデータ構造を
返します。
.Fa prog
は、起動する側のプログラムの名前であり、どの設定を使用するか
決定するために
.Xr editrc 5
ファイルを読み取るときに使用されます。
.Fa fin
と
.Fa fout
はそれぞれ使用する入力ストリームと出力ストリームです。この
ドキュメンテーションでは、
.Dq the tty
の参照が実際にはこの入力/出力ストリームの
組み合わせを参照します。
.It Fn el_end
クリーンアップし
.Fa e
で終了します。
.Fn el_init
で作成されたと想定されます。
.It Fn el_reset
tty とパーサをリセットします。これは
tty の状態を混乱させた可能性のある
エラーの後で呼び出す必要があります。
.It Fn el_gets
tty から 1 行を読み取ります。
.Fa count
は、読み取られたキャラクタ数を
入れるように修正されます。処理が成功した場合は読み取られたラインを返し、
キャラクタが読取られないか、またはエラーが発生した場合は
.Dv NULL
を返します。
.It Fn el_getc
tty から
1 キャラクタを読み取ります。
.Fa ch
は、読み取られたキャラクタを
入れるように修正されます。処理が成功した場合は読み取られたキャラクタの数を
返し、そうでない場合は -1 を返します。
.It Fn el_push
.Fa str
を入力ストリームに戻します。これはマクロ展開機構によって使用されます。
詳細については、
.Xr editrc 5
の
.Ic bind
.Fl s
の説明を参照してください。
.It Fn el_parse
.Fa argv
配列(サイズは
.Fa argc
エレメントです)
をパースし、組み込み
.Nm
コマンドを実行します。コマンドの接頭語が
.Dq prog:
の場合、
.Dq prog
が
.Fn el_init
に指定された
.Fa prog
引数と一致するなら、
.Fn el_parse
はコマンドを
実行するだけです。コマンドが未知の場合は戻り値は
-1 です。エラーがないかまたは
.Dq prog
が一致しなかった場合は
戻り値は
0 です。コマンドがエラーを
返したときは
1 です。詳細については、
.Xr editrc 5
を参照してください。
.Pp
.Em 注 :
.Va argv[0]
は
.Fn el_parse
によって修正されることがあります。
.Dq prog
と
コマンド
.Ar command
の間のコロンは、NUL
.Pq Dq \e0
で置き換えられます。
.It Fn el_set
.Fn el_set
.Nm
パラメータを設定します。
.Fa op
はどのパラメータを設定するかを決定し、
各操作には独自のパラメータリストがあります。
.Pp
.Fa op
の値については、必須引数リストとともに次のパラメータがサポート
されています。
.Bl -tag -width 4n
.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)"
プロンプト印刷関数を
.Fa f
として定義します。これはプロンプトの入ったストリング
を返すことです。
.It Dv EL_TERMINAL , Fa "const char *type"
tty の端末タイプが
.Fa type
であると定義します。
.Fa type
が
.Dv NULL
の場合は
.Ev TERM
にです。
.It Dv EL_EDITOR , Fa "const char *mode"
編集モードを
.Fa mode
に設定します。それは
.Dq emacs
または
.Dq vi
の 1 つである必要があります。
.It Dv EL_SIGNAL , Fa "int flag"
.Fa flag
がゼロでない場合、
.Nm
は、コマンド入力を読み取るときに、次の
シグナル用のシグナルハンドラをインストールします。
.Dv SIGCONT ,
.Dv SIGHUP ,
.Dv SIGINT ,
.Dv SIGQUIT ,
.Dv SIGSTOP ,
.Dv SIGTERM ,
.Dv SIGTSTP ,
および
.Dv SIGWINCH
。これら以外の場合、現在のシグナルハンドラが
使用されます。
.It Dv EL_BIND , Xo
.Fa "const char *" ,
.Fa "..." ,
.Dv NULL
.Xc
組み込み
.Ic bind
コマンドを実行します。詳細については、
.Xr editrc 5
を
参照してください。
.It Dv EL_ECHOTC , Xo
.Fa "const char *" ,
.Fa "..." ,
.Dv NULL
.Xc
組み込み
.Ic echotc
コマンドを実行します。詳細については、
.Xr editrc 5
を
参照してください。
.It Dv EL_SETTC , Xo
.Fa "const char *" ,
.Fa "..." ,
.Dv NULL
.Xc
組み込み
.Ic settc
コマンドを実行します。詳細については、
.Xr editrc 5
を参照してください。
.It Dv EL_SETTY , Xo
.Fa "const char *" ,
.Fa "..." ,
.Dv NULL
.Xc
組み込み
.Ic setty
コマンドを実行します。詳細については、
.Xr editrc 5
を
参照してください。
.It Dv EL_TELLTC , Xo
.Fa "const char *" ,
.Fa "..." ,
.Dv NULL
.Xc
組み込み
.Ic telltc
コマンドを実行します。詳細については、
.Xr editrc 5
を
参照してください。
.It Dv EL_ADDFN , Xo
.Fa "const char *name" ,
.Fa "const char *help" ,
.Fa "unsigned char (*func)(EditLine *e, int ch)
.Xc
ユーザ定義関数
.Fn func
を追加します。これは
.Fa name
として参照され、
.Fa name
に結合されたキーが入力されたときに呼び出されます。
.Fa help
は
.Fa name
の説明です。
起動時に、
.Fa ch
は呼び出しを起こすキーです。
.Fn func
の戻り値は次の 1 つです。
.Bl -tag -width "CC_REDISPLAY"
.It Dv CC_NORM
通常のキャラクタを追加します。
.It Dv CC_NEWLINE
行末が入力されました。
.It Dv CC_EOF
が入力されました。
.It Dv CC_ARGHACK
引数としてさらにコマンド入力を予期しています。表示されることは
何もしません。
.It Dv CC_REFRESH
表示をリフレッシュします。
.It Dv CC_CURSOR
カーソルが移動されたので、
.Dv CC_REFRESH
を更新および実行します。
.It Dv CC_REDISPLAY
入力行全体を再表示します。これが便利なのは、キー結合がその他の
情報を出力する場合です。
.It Dv CC_ERROR
エラーが発生しました。ビープ音、そして tty をフラッシュします。
.It Dv CC_FATAL
致命的エラー。tty を既知の状態にリセットします。
.El
.It Dv EL_HIST , Xo
.Fa "History *(*func)(History *, int op, ...)" ,
.Fa "const char *ptr"
.Xc
どの歴史関数を使用するかを定義します。それは通常は
.Fn history
です。
.Fa ptr
は、
.Fn history_init
が返す値である必要があります。
.El
.It Fn el_source
.Fa file
の内容を読むことで
.Nm
を初期化します。
.Fn el_parse
が、
.Fa file
内の行ごとに呼び出されます。
.Fa file
が
.Dv NULL
の場合、
.Pa $HOME/.editrc
を試します。
.Fa file
の形式の詳細については、
.Xr editrc 5
を
参照してください。
.It Fn el_resize
端末のサイズが変化する場合は呼び出す必要があります。
.Dv EL_SIGNAL
が
.Fn el_set
で設定されている場合、これは自動的に行われます。そうでない場合は、適切な
機会に
.Fn el_resize
を呼び出すのはアプリケーションの責任です。
.It Fn el_line
現在のラインについての編集情報を
.Fa LineInfo
で返します。これは次のように
定義されます。
.Bd -literal
typedef struct lineinfo {
    const char *buffer;    /* バッファのアドレス */
    const char *cursor;    /* カーソルのアドレス */
    const char *lastchar;  /* 最後のキャラクタのアドレス */
} LineInfo;
.Ed
.It Fn el_insertstr
カーソルがあるラインに
.Fa str
を挿入します。
.Fa str
が空であるかフィットしない
場合は -1 を返します。それ以外の場合は 0 を返します。
.It Fn el_deletestr
カーソルの前の
.Fa num
個のキャラクタを削除します。
.It Fn el_data_set
ユーザデータを
.Fa data
へ設定します。
.It Fn el_data_get
ユーザデータを取得します。
.El
.Sh 歴史リスト関数
歴史関数は共通のデータ構造
.Fa History
を使用します。
.Fa History
は、
.Fn history_init
によって作成され、
.Fn history_end
によって解放されます。
.Pp
次の関数が利用できます。
.Bl -tag -width 4n
.It Fn history_init
歴史リストを初期化し、他のすべての歴史関数が使用するデータ構造を返します。
.It Fn history_end
クリーンアップし、
.Fa h
で終了します。
.Fn history_init
で作成されたものと
想定されます。
.Pp
.It Fn history
歴史リストについて演算
.Fa op
を実行します。演算が要求する
オプション引数があります。
.Fa op
について次の値が、必須引数リストとともに
サポートされています。
.Bl -tag -width 4n
.It Dv H_EVENT , Fa "int size"
.Fa size
エレメントに歴史のサイズを設定します。
.It Dv H_END
クリーンアップし、
.Fa h
で終了します。
.Fn history_init
で作成されたものと
想定されます。
.It Dv H_CLEAR
歴史をクリアします。
.Pp
.It Dv H_FUNC , Xo
.Fa "void *ptr" ,
.Fa "history_gfun_t first" ,
.Fa "history_gfun_t next" ,
.Fa "history_gfun_t last" ,
.Fa "history_gfun_t prev" ,
.Fa "history_gfun_t curr" ,
.Fa "history_vfun_t clear" ,
.Fa "history_efun_t enter" ,
.Fa "history_efun_t add"
.Xc
さまざまな歴史演算を実行する関数を定義します。
.Fa ptr
は、関数が起動されるときに関数に指定される引数です。
.It Dv H_FIRST
歴史の最初のエレメントを返します。
.It Dv H_LAST
歴史の最後のエレメントを返します。
.It Dv H_PREV
歴史の直前のエレメントを返します。
.It Dv H_NEXT
歴史の次のエレメントを返します。
.It Dv H_CURR
歴史の現在のエレメントを返します。
.It Dv H_ADD , Fa "const char *str"
歴史の現在のエレメントの末尾に
.Fa str
を追加するか、またはエレメントがない
場合は
.Dv H_ENTER
で 1 つのエレメントを作成します。
.It Dv H_ENTER , Fa "const char *str"
.Fa str
を新しいエレメントとして
.Fn history
に追加します。必要であれば、最も古い
エントリを削除して、リストを作成されたサイズに保ちます。
.It Dv H_PREV_STR , Fa "const char *str"
.Fa str
で開始する、最も近い直前のイベントを返します。
.It Dv H_NEXT_STR , Fa "const char *str"
.Fa str
で開始する、最も近い次のイベントを返します。
.It Dv H_PREV_EVENT , Fa "int e"
.Fa e
という番号の直前のイベントを返します。
.It Dv H_NEXT_EVENT , Fa "int e"
.Fa e
という番号の次のイベントを返します。
.It Dv H_LOAD , Fa "const char *file"
.Fa file
に保存された歴史リストをロードします。
.It Dv H_SAVE , Fa "const char *file"
歴史リストを
.Fa file
に保存します。
.El
.El
.\"XXX.Sh EXAMPLES
.\"XXX: provide some examples
.Sh 関連項目
.Xr sh 1 ,
.Xr signal 3 ,
.Xr termcap 3 ,
.Xr editrc 5
.Sh 歴史
.Nm
ライブラリは最初に
.Bx 4.4
で現れました。
.Sh 作者
.An -nosplit
.Nm
ライブラリは
.An Christos Zoulas
が作成しました。このマニュアルは
.An Luke Mewburn
が作成しました。
.Sh バグ
このドキュメンテーションはおそらく不完全であると考えられます。
.Pp
.Fn el_parse
は、指定された
.Va argv[0]
を修正してはなりません。
.Pp
トークン化関数は
.Li <histedit.h>
内では公に定義されていません。