EN JA
EDITLINE(3)
EDITLINE(3) FreeBSD Library Functions Manual EDITLINE(3)

名称

editline, el_init, el_end, el_reset, el_gets, el_getc, el_push, el_parse, el_set, el_get, el_source, el_resize, el_line, el_insertstr, el_deletestr, history_init, history_end, history, tok_init, tok_end, tok_reset, tok_line, tok_str行エディタ、ヒストリとトークン化の関数

ライブラリ

Command Line Editor Library (libedit, -ledit)

書式

#include < histedit.h>

EditLine *
el_init( const char *prog, FILE *fin, FILE *fout, FILE *ferr);

void
el_end( EditLine *e);

void
el_reset( EditLine *e);

const char *
el_gets( EditLine *e, int *count);

int
el_getc( EditLine *e, char *ch);

void
el_push( EditLine *e, char *str);

int
el_parse( EditLine *e, int argc, const char *argv[]);

int
el_set( EditLine *e, int op, ...);

int
el_get( EditLine *e, int op, ...);

int
el_source( EditLine *e, const char *file);

void
el_resize( EditLine *e);

const LineInfo *
el_line( EditLine *e);

int
el_insertstr( EditLine *e, const char *str);

void
el_deletestr( EditLine *e, int count);

History *
history_init();

void
history_end( History *h);

int
history( History *h, HistEvent *ev, int op, ...);

Tokenizer *
tok_init( const char *IFS);

void
tok_end( Tokenizer *t);

void
tok_reset( Tokenizer *t);

int
tok_line( Tokenizer *t, const LineInfo *li, int *argc, const char **argv[], int *cursorc, int *cursoro);

int
tok_str( Tokenizer *t, const char *str, int *argc, const char **argv[]);

解説

editline 関数は、 sh(1) で見られるものに似ている汎用の行 (ライン) 編集、ヒストリとトークン化の関数を提供します。

これらの関数は、 libedit ライブラリ (それは、 libtermcap ライブラリを必要とする) で利用可能です。プログラムは、 -ledit -ltermcap でリンクされるべきです。

行編集関数

行編集関数は、 el_init() によって作られ、 el_end() によって解放される共通のデータ構造体 EditLine を使用します。

次の関数が利用可能です。

el_init()
行エディタを初期化して、他のすべての行編集関数によって使用されるデータ構造体を返します。 prog は、どの設定を使用するべきであるか決めるために editrc(5) ファイルを読むとき使用される呼び出しプログラムの名前です。 fin, foutferr は、(それぞれ) 使用する入力、出力とエラーのストリームです。この文書では、“the tty”への参照は、実際には、この入力/出力ストリームの組み合わせです。
el_end()
クリーンアップして、 el_init() で作成されたと仮定されて、 e で終了します。
el_reset()
tty とパーサをリセットします。これは、tty の状態を混乱したかもしれないエラーの後に呼ばれるべきです。
el_gets()
tty から 1 行を読み込みます。 count は、読み込まれた文字の数を含むために修正されます。成功する場合、読み込まれた行を返します。あるいは文字が読み込まれなかった場合、あるいはエラーが生じた場合、 NULL を返します。エラーが生じたなら、 count は、-1 に設定され、 errno は、それを引き起こしたエラーコードを含んでいます。返り値は、 el_gets() への呼び出しにわたって有効なままでありません、そしてデータが保持されることになっているなら、コピーされなければなりません。
el_getc()
tty から 1 文字を読み込みます。 ch は、読み込まれた文字を含むために修正されます。成功する場合、読み込まれた文字の数を返します。そうでなければ、-1 を返します。
el_push()
入力ストリームに str を押し戻します。これは、マクロ展開機構によって使用されます。詳細については、 editrc(5)bind -s の記述を参照してください。
el_parse()
組み込み editline コマンドを実行するために、サイズは、 argc 要素である argv 配列を解析します。コマンドに“prog:”接頭辞が付いている場合、“prog”が el_init() に供給された prog 引数と一致する場合、 el_parse() は、コマンドを単に実行します。コマンドが未知の場合、返り値は、-1 です、エラーがなかったかまたは“prog”が一致しない場合、返り値は、0 となります。あるいはコマンドがエラーを返した場合 1 となります。詳細については、 editrc(5) を参照してください。
el_set()
editline パラメータを設定します。 op は、どのパラメータを設定するか決定し、各演算は、それ自身のパラメータリストを持っています。

op のための次の値は、要求された引数リストとともにサポートされます。

EL_PROMPT, char *(*f)(EditLine *)
プロンプト印刷関数を f として定義します。それは、プロンプトを含んでいる文字列を返すことです。
EL_PROMPT_ESC, char *(*f)(EditLine *), char c
EL_PROMPT, と同じですが、 c 引数は、スタート/ストップのリテラルプロンプト文字を表します。

スタート/ストップのリテラル文字がプロンプトで見つかるなら、文字自身は、印刷されませんが、その後の文字は、現在の行の状態に影響せずに、端末に直接印刷されます。その後の 2 番目のスタート/ストップのリテラル文字は、この振る舞いを終了します。これは、一般的にプロンプトの端末の色/スタイルを変更するリテラルのエスケープシーケンスを組み込むために使用されます。 0 は、その設定を取り消します。

EL_REFRESH
次の端末の行で現在の行を再表示します。
EL_RPROMPT, char *(*f)(EditLine *)
右側のプロンプト印刷関数を f として定義します。それは、プロンプトを含んでいる文字列を返すことです。
EL_RPROMPT_ESC, char *(*f)(EditLine *), char c
正しいプロンプトの印刷関数を定義しますが、リテラルのエスケープ文字付きです。
EL_TERMINAL, const char *type
tty の端末タイプを type であると定義します。あるいは typeNULL である場合、 TERM であると定義します。
EL_EDITOR, const char *mode
編集モードを mode に設定します。それは、“emacs”あるいは“vi”のうちの 1 つでなければなりません。
EL_SIGNAL, int flag
flag が 0 でない場合、 editline は、コマンド入力を読み込む時、次のシグナルのためのそれ自身のシグナルハンドラをインストールします。 SIGCONT, SIGHUP, SIGINT, SIGQUIT, SIGSTOP, SIGTERM, SIGTSTPSIGWINCH。そうでなければ、現在のシグナルハンドラが使用されます。
EL_BIND, const char *, ..., NULL
bind 組み込みコマンドを実行します。詳細については、 editrc(5) を参照してください。
EL_ECHOTC, const char *, ..., NULL
echotc 組み込みコマンドを実行します。詳細については、 editrc(5) を参照してください。
EL_SETTC, const char *, ..., NULL
settc 組み込みコマンドを実行します。詳細については、 editrc(5) を参照してください。
EL_SETTY, const char *, ..., NULL
setty 組み込みコマンドを実行します。詳細については、 editrc(5) を参照してください。
EL_TELLTC, const char *, ..., NULL
telltc 組み込みコマンドを実行します。詳細については、 editrc(5) を参照してください。
EL_ADDFN, const char *name, const char *help, unsigned char (*func)(EditLine *e, int ch)
ユーザ定義関数 func() を追加します。それは、 name に結び付けられるキーが入力される時、呼び出される name として参照されます。 help は、 name の説明です。呼び出し時に、 ch は、呼び出しの原因となるキーです。 func() の返り値は、次のうちの 1 つであるべきです。
CC_NORM
通常の文字を追加します。
CC_NEWLINE
行末が入力されました。
CC_EOF
EOF が入力されました。
CC_ARGHACK
引数としてさらなるコマンド入力を予期します。視覚的に何も起こりません。
CC_REFRESH
表示をリフレッシュします。
CC_REFRESH_BEEP
表示をリフレッシュし、ビープ音を鳴らします。
CC_CURSOR
カーソルを移動し、 CC_REFRESH を更新して実行します。
CC_REDISPLAY
入力行全体を再表示します。キー結合が余分な情報を出力する場合に、これは、便利です。
CC_ERROR
エラーが発生しました。ビープ音、そして tty をフラッシュします。
CC_FATAL
致命的なエラー。tty を既知の状態へリセットします。
EL_HIST, History *(*func)(History *, int op, ...), const char *ptr
通常 history() である、使用するヒストリ関数を定義します。 ptr は、 history_init() によって返される値であるべきです。
EL_EDITMODE, int flag
flag が 0 でなければ、編集は、有効にされます (デフォルト)。これは、目安だけであり、 editline の操作に影響しないことに注意してください。このとき、編集が有効にされるかどうか決定するために、 ( el_get() を使用して) これをチェックするのは、呼び出し側の責任です。
EL_GETCFN, int (*f)(EditLine *, char *c)
読み込んだ文字数を返し、それらを c に格納する、文字読み込み関数を f と定義します。この関数は、 el_gets() と el_getc() によって内部的に呼び出されます。組み込み関数は、特別な関数名 EL_BUILTIN_GETCFN で設定するか復旧することができます。
EL_CLIENTDATA, void *data
この EditLine 構造体に関連している data を登録します。それは、対応する el_get() 呼び出しで検索することができます。
EL_SETFP, int fd, FILE *fp
fp から、現在の editline ファイルポインタを“入力” fd = 0, “出力” fd = 1 または“エラー” fd = 2 に設定します。
el_get()
editline パラメータを取得します。 op は、 result にどのパラメータを取り出したらよいかを決定します。成功するなら、0 を返し、そうでなければ、-1 を返します。

op のための次の値は、実際のタイプの result と共にサポートされます:

EL_PROMPT, char *(*f)(EditLine *), char *c
f にプロンプトを表示する関数へのポインタを返します。 cNULL でないなら、その中のスタート/ストップのリテラルプロンプト文字を返します。
EL_RPROMPT, char *(*f)(EditLine *), char *c
f に右側のプロンプトを表示する関数へのポインタを返します。 cNULL でないなら、その中のスタート/ストップのリテラルプロンプト文字を返します。
EL_EDITOR, const char *
“emacs”か“vi”の 1 つであるエディタの名前を返します。
EL_GETTC, const char *name, void *value
name が有効な termcap(5) のケーパビリティであるなら、0 以外を返し、 value を、そのケーパビリティの現在の値に設定します。
EL_SIGNAL, int *
editline がプライベートシグナルハンドラをインストールしたなら、 0 以外を返します (上記の el_get() を参照)。
EL_EDITMODE, int *
編集が有効にされるなら、0 以外を返します。
EL_GETCFN, int (**f)(EditLine *, char *)
デフォルトの組み込む関数の場合では、 EL_BUILTIN_GETCFN と等しい、文字を読み込む関数へのポインタを返します。
EL_CLIENTDATA, void **data
対応する el_set() 呼び出しで以前に登録された data を検索します。
EL_UNBUFFERED, int
非バッファモードを設定するか、クリアします。このモードでは、 el_gets() は、処理直後の単一の文字を返します。
EL_PREP_TERM, int
端末の編集モードを設定するか、クリアします。
EL_GETFP, int fd, FILE **fp
“入力” fd = 0, “出力” fd = 1 または“エラー” fd = 2 である現在の editline ファイルポインタを fp に返します。
el_source()
file の内容を読むことにより editline を初期化します。 el_parse() は、 file 内の各行ごとに呼び出されます。 fileNULL であるなら、 $HOME/.editrc を試みます。 file の形式についての詳細については、 editrc(5) を参照してください。
el_resize()
端末のサイズが変わる場合、呼ばれなければなりません。 EL_SIGNALel_set() で設定されている場合、これは、自動的に行われます。そうでなければ、それは、適切な機会に el_resize() を呼び出すアプリケーションの責任です。
el_line()
次のように定義される LineInfo 構造体の現在の行のための編集情報を返します。

typedef struct lineinfo { 
    const char *buffer;    /* バッファのアドレス */ 
    const char *cursor;    /* カーソルのアドレス */ 
    const char *lastchar;  /* 最後の文字のアドレス */ 
} LineInfo;

buffer は、ヌル (NUL) 文字で終了していません。この関数は、 EL_ADDFN で追加されたユーザ定義関数の中から、その関数によって返された行に関連する LineInfo 構造体を取得するために el_gets() の後で、呼び出されるかもしれません。

el_insertstr()
カーソルがある行に str を挿入します。 str が空か適合しない場合-1 を返します。そうでなければ 0 を返します。
el_deletestr()
カーソルの前の count 文字を削除します。

ヒストリリスト関数

ヒストリ関数は、 history_init() によって作られ、 history_end() によって解放される共通のデータ構造体 History を使用します。

次の関数が利用可能です:

history_init()
ヒストリリストを初期化して、他のすべてのヒストリリスト関数によって使用されるデータ構造体を返します。
history_end()
クリンアップし、 h で終了します。 history_init() で作成されたと仮定されます。
history()
演算によって必要とされるオプション引数と共に、ヒストリリストで演算 op を実行します。 ev は、操作に従って変更されます。要求された引数リストとともに、 op のための次の値がサポートされます。
H_SETSIZE, int size
ヒストリのサイズを size に要素に設定します。
H_GETSIZE
ヒストリの現在のイベントの数を取得します。
H_END
クリンアップし、 h で終了します。 history_init() で作成されると仮定されます。
H_CLEAR
ヒストリをクリアします。
H_FUNC, void *ptr, history_gfun_t first, history_gfun_t next, history_gfun_t last, history_gfun_t prev, history_gfun_t curr, history_sfun_t set, history_vfun_t clear, history_efun_t enter, history_efun_t add
さまざまなヒストリ演算を実行する関数を定義します。 ptr は、それが呼び出されるときに関数に与えられる引数です。
H_FIRST
ヒストリの最初の要素を返します。
H_LAST
ヒストリの最後の要素を返します。
H_PREV
ヒストリの前の要素を返します。
H_NEXT
ヒストリの次の要素を返します。
H_CURR
ヒストリの現在の要素を返します。
H_SET
要求された要素を指すカーソルを設定します。
H_ADD, const char *str
ヒストリの現在の要素に str を追加するか、または現在の要素がなければ、引数 strH_ENTER 操作を実行します。
H_APPEND, const char *str
ヒストリの最後の新しい要素に str を追加します。
H_ENTER, const char *str
ヒストリに新しい要素として str を加え、そして必要ならば作成されたサイズにリストを保持するために最も古いエントリを削除します。 H_SETUNIQUE が 0 以外の引数で呼び出されたなら、内容が現在のヒストリ要素の 1 つに適合するなら、要素は、ヒストリに入れられません。要素が入れられるなら、 history() は、1 を返し、重複として無視されるなら、0 を返します。最後に、 history() は、エラーが起こったなら、-1 を返します。
H_PREV_STR, const char *str
str で始まる最も近い前のイベントを返します。
H_NEXT_STR, const char *str
str で始まる最も近い次のイベントを返します。
H_PREV_EVENT, int e
番号 e の前のイベントを返します。
H_NEXT_EVENT, int e
番号 e の次のイベントを返します。
H_LOAD, const char *file
file に格納されたヒストリリストをロードします。
H_SAVE, const char *file
ヒストリリストを file に保存します。
H_SETUNIQUE, int unique
隣接する同じイベント文字列は、ヒストリに入れられるべきでないというフラグを設定します。
H_GETUNIQUE
隣接している同じ要素がヒストリに入れられるべきなら、現在の設定を検索します。
H_DEL, int e
番号が付けられたイベント e を削除します。この関数は、 readline(3) 互換性のためだけに提供されています。呼び出し側は、返された HistEvent の文字列を解放する責任があります。

history() 関数は、操作 op が成功するなら、≥ 0 を返します。そうでなければ、-1 を返し、エラー関するより詳細を含むように ev を更新します。

トークン化関数

トークン化関数は、共通のデータ構造体、 Tokenizer を使用します。 Tokenizer は、 tok_init() によって作成され、 tok_end() によって解放されます。

つぎの関数が利用可能です:

tok_init()
tokenizer を初期化し、他のすべての tokenizer 関数によって使用されるデータ構造体を返します。 IFS は、 NULL であるなら、デフォルトである<空白>, <タブ>と<改行>の入力フィールドセパレータ (分離文字) を含みます。
tok_end()
tok_init() で作成されたと想定される t で、後始末をして、終了します。
tok_reset()
tokenizer 状態をリセットします。 tok_line() または tok_str() によってうまくトークン化された行の後で、トークン化された新しい行の前で使用します。
tok_line()
成功すれば li をトークン化し、単語を含む argv、単語の数を含む argc、 ( NULL でなければ) カーソルを含む単語のインデックスを含む cursorc と ( NULL でなければ) カーソルの argv[cursorc] 中のオフセットを含む cursoro を変更します。

成功すれば、0 を返し、内部エラーであれば-1 を返し、単一引用付が不一致なら 1 を返し、二重引用付が不一致なら 2 を返し、そしてバックスラッシュでクォートされた<改行>なら、3 を返します。正の終了コードは、別の行が読み込まれるべきであり、トークン化が再び試みられたことを示します。

tok_str()
tok_line() の、より簡単な形式です。 str は、トークン化するためのヌル (NUL) 文字で終了した文字列です。

歴史

editline ライブラリは、 4.4BSD ではじめて登場しました。 CC_REDISPLAY は、 NetBSD 1.3 で登場しました。 CC_REFRESH_BEEPEL_EDITMODE は、 NetBSD 1.4 で登場しました。 EL_RPROMPT は、 NetBSD 1.5 で登場しました。

作者

editline ライブラリは、 Christos Zoulas によって書かれました。 Luke Mewburn は、このマニュアルを書いて、 CC_REDISPLAY, CC_REFRESH_BEEP, EL_EDITMODEEL_RPROMPT を実装しました。

バグ

このとき、 editline がさらなる入力に使用されるかどうか決定するために ( el_source() か el_parse() の後で) el_get() の EL_EDITMODE 操作の結果をチェックするのは呼び出し側の責任です。すなわち、 EL_EDITMODE は、純粋に最新の editrc(5) edit (編集) コマンドの結果を示しています。
July 5, 2009 FreeBSD