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

名称

history - GNU ヒストリライブラリ

COPYRIGHT

The GNU History Library is Copyright (C) 1989-2002 by the Free Software Foundation, Inc.

解説

多くのプログラムは、1 行づつユーザからの入力を読み込みます。 GNU ヒストリライブラリは、それらの行の経過を追い、各行を任意のデータに関連づけて、新しい行を組み立てる際に前の行からの情報を利用することができます。

ヒストリ展開

ヒストリライブラリは bash のヒストリ拡張と同じヒストリ拡張機能をサポートします。このセクションは、どのような構文機能が利用可能であるかを記述しています。

ヒストリ拡張はヒストリリストから入力ストリームにワード (単語) を取り入れ、コマンドの繰り返しや、前のコマンドに引数を挿入して現在の入力行にする、または前のコマンドのエラーをすぐにを修正することを容易にします。

通常、ヒストリ拡張は完全な行が読み込まれた直後に実行されます。それは、2 つの部分で行われます。最初は置換の間にヒストリリストからのどの行を使用したらよいかを決定することです。 2 番目は現在の行に含まれる行の部分を選択することです。ヒストリから選択された行は イベントで、作用される行の部分は ワードです。様々な 修飾子が、選択されたワードを操作するるために利用可能です。入力を読み込むとき、行は、引用符によって囲まれるとき、そうでなければ切り離される、 (下記の history_tokenize() の説明を参照) いくつかのワードは、1 つのワードと見なされるように、 bash と同じやり方でワードに分解されます。ヒストリ拡張は、ヒストリ拡張文字、デフォルトでは、 !、が現れることで導入されます。バックスラッシュ ( \) と単一引用符だけがヒストリ拡張文字をクオート (無効に) することができます。

イベント指示子

イベント指示子はヒストリリストにおけるコマンド行エントリの参照です。

!
空白, 改行, = または ( が続くときを除いて、ヒストリ置換が始まります。
! n
コマンド行 n を参照します。
!- n
現在のコマンド行マイナス n を参照します。
!!
前のコマンドを参照します。これは、`!-1' と同義語です。
! string
string で始まる最近のコマンドを参照します。
!? string[?]
string を含む最近のコマンドを参照します。後続する ?string の直後が改行であるなら、省略できます。
^ string1^ string2^
迅速な置換。 string1string2 に置き換えて最後のコマンドを繰り返します。 ``!!:s/ string1/ string2/'' と同等です (下記の 修飾子を参照)。
!#
今までにタイプされているコマンド行の全体。

ワード指示子

ワード指示子はイベントから必要なワードを選択するために使用されます。 : はワード指示子からイベント指定を切り離します。ワード指示子が ^, $, *, - または % で始まるなら省略できます。最初のワードが 0 (ゼロ) を意味している状態で、ワードは行の始まりから番号付けされます。ワードは単一の空白によって切り離された現在行に挿入されます。

0 (zero)
0 番目のワード。シェルでは、これはコマンド名 (ワード)です。
n
n 番目のワード。
^
最初の引数。すなわち、ワード 1。
$
最後の引数。
%
最近の `? string?' 検索で一致したワード。
x -y
一連のワード。 `- y' は、`0- y' の短縮形です。
*
0 番目を除くすべてのワード。これは、` 1-$' の同義語です。イベントにたった 1 つのワードがある場合、 * の使用はエラーではありません。その場合、空の文字列を返します。
x*
x-$ の短縮形です。
x-
x-$ は、 x* の簡略化に似ていますが、最後のワードを省略します。

ワード指示子がイベント指定なしで供給されるなら、イベントとして前のコマンドが使用されます。

修飾子

省略可能なワード指示子の後に、それぞれ `:' に先行した次の修飾子の 1 つ以上のシーケンスが現れるかもしれません。

h
先頭だけ残して、後続するファイル名の構成要素を取り除きます。
t
後部を残して、すべての先導するファイル名の構成要素を取り除きます。
r
basename を残して、形式 .xxx の後続する接尾辞を取り除きます。
e
後続する接尾辞以外のすべてを取り除きます。
p
新しいコマンドを印刷 (表示) しますが、それを実行しません。
q
それ以上の置換を回避して、置換ワードをクオート (無効に) します。
x
q のように代置換されたワードをクオートしますが、 空白 と改行でワードに割り込みます。
s/ old/ new/
イベント行で、最初に見つかる oldnew に置き換えます。 / の代わりにどんなデリミタも使用することができます。最後のデリミタはイベント行の最後の文字であるなら省略可能です。デリミタは、1 つのバックスラッシュがある oldnew でクオートできます。 new の中に &が現れるなら、 old で置き換えられます。 1 つのバックスラッシュは、 &をクオートします。 old が空であるなら、最後に置換された old に設定されるか、以前にヒストリ置換が行われていなければ、 !? string[?] 検索の最後の string です。
&
前の置換を繰り返します。
g
変更が全体のイベント行で適用されます。これは、` :s' (例えば、 ` :gs/ old / new /') または ` :&' 関連して使用されます。 ` :s' と共に使用されるなら、どんなデリミタも / の代わりに使用することができ、最後のデリミタはイベント行の最後の文字であるなら省略可能です。 a は、 g と同義語として使用されるかもしれません。
G
次の ` s' 修飾子をイベント行における各単語に一度適用します。

ヒストリ関数でプログラミング

このセクションは他のプログラムでヒストリライブラリを使用する方法を説明しています。

ヒストリの紹介

ヒストリライブラリを使用しているプログラマは、ヒストリリストで、任意のデータを行に関連づけ、リストから行を取り除く、任意のテキスト文字列を含む行としてリストを検索し、および直接リスト中でどんな行も参照する、行を覚えているために利用可能な関数があります。さらに、異なったプログラムにわたって一貫したユーザインタフェースを提供するヒストリ 拡張関数が利用可能です。

ヒストリライブラリを使って書かれたプログラムを使用するユーザは、前の行のテキストを操作して、新しいコマンドでそのテキストを使用するための 1 組のよく知られているコマンドと共に一貫したユーザインタフェースの利点があります。基本的なヒストリ操作コマンドは、 bash で提供されるヒストリ置換と同じです。

プログラマが望むなら、コマンド行編集の利点が追加され、デフォルトで何らかのヒストリ操作を含む、 readline ライブラリを使用することができます。

他のコードで提供される任意の機能性のあるヒストリライブラリを使用する任意の関数を宣言する前に、アプリケーションの作者はヒストリライブラリの機能を使用する任意のファイルにファイル <readline/history.h> をインクルードするべきです。それは、ライブラリのパブリック関数と変数のすべてのための extern 宣言を供給して、パブリックデータ構造体のすべてを宣言しています。

 

ヒストリ記憶域

ヒストリリストはヒストリエントリの配列です。ヒストリエントリは次のように宣言されます:

typedef void * histdata_t;

 


typedef struct _hist_entry {
char *line;
char *timestamp;
histdata_t data;
} HIST_ENTRY;

したがって、ヒストリリスト自体は次のように宣言されるかもしれません。

HIST_ENTRY ** the_history_list;

 

ヒストリライブラリの状態はただ 1 つの構造体にカプセル化されます:


/*
* 構造体はヒストリの活動している現在の状態を渡すために使用します。
*/
typedef struct _hist_state {
HIST_ENTRY **entries; /* エントリ自体へのポインタ. */
int offset; /* この配列中の位置ポインタ. */
int length; /* この配列中の要素の数. */
int size; /* この配列に割り付けられたスロットの数. */
int flags;
} HISTORY_STATE;

flags メンバが HS_STIFLED を含むなら、ヒストリは抑制されています。

ヒストリ関数

このセクションは、GNU ヒストリライブラリによってエクスポートされた様々な関数のための呼び出しシークエンスを説明しています。

ヒストリと状態管理の初期化

このセクションは利用者のプログラムでヒストリ機能を使用したいと思うとき、ヒストリライブラリの状態を初期化して、管理するために使用される関数について説明しています。
 
void using_history ( void)
 
ヒストリ関数が使用されるかもしれないセッションを開始します。これはインタラクティブな変数を初期化します。
 
HISTORY_STATE * history_get_history_state ( void)
 
入力ヒストリの現在の状態について説明する構造体を返します。
 
void history_set_history_state ( HISTORY_STATE *state)
 
state 従ってヒストリリストの状態を設定します。
 

ヒストリリスト管理

これらの関数は、ヒストリリストで個々のエントリを管理するか、またはリスト自体を管理するパラメータを設定します。
 
void add_history ( const char *string)
 
ヒストリリストの終わりに string を置きます。関連データフィールド (もしあるならば) は、 NULL に設定されます。
 
void add_history_time ( const char *string)
 
string への最新のヒストリエントリに関連しているタイムスタンプを変更します。
 
HIST_ENTRY * remove_history ( int which)
 
ヒストリからオフセット which のヒストリエントリを取り除きます。利用者が行、データ、含んでいる構造体を解放することができるように、取り除いた要素を返します。
 
histdata_t free_history_entry ( HIST_ENTRY *histent)
 
ヒストリエントリ histent とそれに関連しているあらゆるヒストリライブラリのプライベートデータを解放します。呼び出し側がそれを処置することができるように、アプリケーション特有のデータを返します。
 
HIST_ENTRY * replace_history_entry ( int which, const char *line, histdata_t data)
 
linedata があるオフセット which のヒストリエントリを取り除きます。呼び出し側が任意のアプリケーション特有のデータを処置することができるように、これは古いエントリを返します。無効の which の場合では、 NULL ポインタが返されます。
 
void clear_history ( void)
 
すべてのエントリを削除することによって、ヒストリリストをクリアします。
 
void stifle_history ( int max)
 
最後の max エントリだけを覚えていて、ヒストリリストを抑制します。
 
int unstifle_history ( void)
 
ヒストリの抑制を止めます。これは、( stifle_history() で設定された) 以前に設定している最大数の歴史エントリを返します。歴史は抑制されました。この値はヒストリが抑制されているなら、正で、そうでなければ、負です。
 
int history_is_stifled ( void)
 
ヒストリが抑制されているなら、0 以外を返し、そうでなければ、0 を返します。
 

ヒストリリストに関する情報

これらの関数は全体のヒストリリストか個々のリストエントリに関する情報を返します。
 
HIST_ENTRY ** history_list ( void)
 
現在の入力ヒストリである HIST_ENTRY *NULL で終了した配列を返します。このリストの要素 0 は開始時間です。ヒストリがなければ、 NULL を返します。
 
int where_history ( void)
 
現在のヒストリ要素のオフセットを返します。
 
HIST_ENTRY * current_history ( void)
 
where_history() によって決定されるように現在の位置にヒストリエントリを返します。エントリがそこになければ、 NULL ポインタを返します。
 
HIST_ENTRY * history_get ( int offset)
 
history_base から始めて、位置 offset のヒストリエントリを返します。エントリがそこにないか、または offset がヒストリの長さより大きいなら、 NULL ポインタを返します。
 
time_t history_get_time ( HIST_ENTRY *)
 
引数として渡されたヒストリエントリに関連しているタイムスタンプを返します。
 
int history_total_bytes ( void)
 
プライマリ (第一) のヒストリエントリが使用しているバイト数を返します。この関数はヒストリのすべての行の長さの合計を返します。
 

ヒストリリストの周りで移動

これらの関数は、設定するか、または変更するためにヒストリリストに現在のインデックスを許します。
 
int history_set_pos ( int pos)
 
現在のヒストリオフセットをリスト中の絶対インデックスである pos に設定します。成功すれば 1 を返し、 pos が 0 より小さいかヒストリエントリの数より大きいなら 0 を返します。
 
HIST_ENTRY * previous_history ( void)
 
以前のヒストリエントリに現在のヒストリオフセットをバックアップし、そのエントリへのポインタを返します。以前のエントリがなければ、 NULL ポインタを返します。
 
HIST_ENTRY * next_history ( void)
 
現在のヒストリオフセットを次のヒストリエントリへ前方に移動し、そのエントリへのポインタを返します。次のエントリがなければ、 NULL ポインタを返します。
 

ヒストリリストの検索

これらの関数で、指定された文字列を含むエントリでヒストリリストを検索できます。検索は現在のヒストリ位置から前方と後方の両方で実行できます。検索は、文字列がヒストリエントリの始めに一致しなければならないことを意味する、 anchored (^) されるかもしれません。
 
int history_search ( const char *string, int direction)
 
現在のヒストリオフセットから始まる string のためにヒストリを検索します。 direction が 0 未満であるなら、検索は前方のエントリを、そうでなければ、後方のエントリに行われます。 string が見つけられるなら、現在のヒストリインデックスはそのヒストリエントリに設定され、返された値は、 string が見つけられたエントリの行でのオフセットです。そうでなければ、何も変更せず、-1 を返します。
 
int history_search_prefix ( const char *string, int direction)
 
現在のヒストリオフセットから始まる string のためにヒストリを検索します。検索は、一致する行は、 string で始まらなければならない、 anchored (^) されます。 direction が 0 未満であるなら、検索は前方のエントリを、そうでなければ、後方のエントリに行われます。 string が見つけられるなら、現在のヒストリインデックスはそのエントリに設定され、返り値は、0 です。そうでなければ、何も変更せず、-1 を返します。
 
int history_search_pos ( const char *string, int direction, int pos)
 
リストの中の絶対インデックスである pos で始まる、ヒストリリスト中で string を検索します。 direction が負であるなら、検索は、 pos から後方に進み、そうでなければ、前方に進みます。 string が見つけられたヒストリ要素の絶対インデックスを返し、そうでなければ、-1 を返します。
 

ヒストリファイルの管理

ヒストリライブラリは、ファイルからヒストリを読み込んで、ファイルにヒストリを書き込むことができます。このセクションは、ヒストリファイルを管理するための関数を文書化しています。
 
int read_history ( const char *filename)
 
一度に 1 行の filename の内容をヒストリリストに追加します。 filenameNULL であるなら、 ~/.history から読み込みます。成功すれば、0 を返し、そうでなければ、 errno を返します。
 
int read_history_range ( const char *filename, int from, int to)
 
filename から一連の行を読み込み、それらをヒストリリストに追加します。行 from から読み込み始めて、 to で終わります。 from が 0 であるなら、始まりから開始します。 tofrom 以下であるなら、ファイルの終りまで読み込みます。 filenameNULL であるなら、 ~/.history から読み込みます。成功すれば、0 を返し、そうでなければ、 errno を返します。
 
int write_history ( const char *filename)
 
必要なら、 filename を上書きして、 filename へ現在のヒストリを書き込みます。 filenameNULL であるなら、ヒストリリストを ~/.history に書き込みます。成功すれば、0 を返し、読み込みまたは書き込みエラーなら、 errno を返します。
 
 
int append_history ( int nelements, const char *filename)
 
ヒストリリストの最後の nelementsfilename に追加します。 filenameNULL であるなら、 ~/.history に追加します。成功すれば、0 を返し、読み込みまたは書き込みエラーなら、 errno を返します。
 
int history_truncate_file ( const char *filename, int nlines)
 
最後の nlines 行だけを残して、ヒストリファイル filename を切り捨てます。 filenameNULL であるなら、 ~/.history が切り捨てられます。成功すれば、0 を返し、エラーの場合は、 errno を返します。
 

ヒストリ展開

これらの関数はヒストリ拡張を実装します。
 
int history_expand ( char *string, char **output)
 
string を拡張し、文字列のポインタである output に結果を置きます。返り値次の通りです:
0
拡張が行われなかったなら、 (テキストにおける唯一の変更がヒストリ拡張文字に先行するエスケープ文字の除去であるなら)。
1
拡張が行われたなら。
-1
拡張でエラーがあったなら。
2
返された行は表示されるべきですが、 :p 修飾子と同様に、実行しません。
拡張でエラーが発生したなら、 output は説明的なエラーメッセージを含んでいます。
 
char * get_history_event ( const char *string, int *cindex, int qchar)
 
string + *cindex で始まるヒストリイベントのテキストを返します。 *cindex は、イベント記述子の後を指すように変更されます。関数エントリでは、 cindex はヒストリイベント指定が始まる string へのインデックスを指します。 qchar は、``標準の'' 終了文字に加えてイベント指定を終わらせることができる文字です。
 
char ** history_tokenize ( const char *string)
 
シェルと同じかもしれない、 string から解析されたトークンの配列を返します。トークンは、 history_word_delimiters 変数の文字で分割され、シェルのクオートのコンベンションに従います。
 
char * history_arg_extract ( int first, int last, const char *string)
 
string に存在する first から last 引数で構成される文字列セグメントを抽出します。引数は、 history_tokenize() を使用して分割されます。
 

ヒストリ変数

このセクションは、GNU ヒストリライブラリによってエクスポートされた外部的に可視の変数について記述しています。
 
int history_base
 
ヒストリリストにおける、最初のエントリの論理的なオフセット。
 
int history_length
 
ヒストリリストにおける、現在格納されているエントリの数。
 
int history_max_entries
 
ヒストリエントリの最大数。 stifle_history() を使用してこれを変更しなければなりません。
 
int history_write_timestamps
 
0 でなければ、セッションの間にそれらを保存することができるので、タイムスタンプは、ヒトトリファイルに書き込まれます。デフォルト値は、タイムスタンプが保存されないことを意味する、0 です。
 
char history_expansion_char
 
ヒストリイベントを導入する文字。デフォルトは、 ! です。これを 0 に設定すると、ヒストリ拡張は抑制されます。
 
char history_subst_char
 
行の始めで見つけられるならワード置換を呼び出す文字。デフォルトは、 ^ です。
 
char history_comment_char
 
トークン化の間、この文字がワードの最初の文字と思われるなら、それと改行までのすべてのその後の文字は、行の残りのためのヒストリ拡張を抑圧して、無視されます。これはデフォルトで無効にされます。
 
char * history_word_delimiters
 
history_tokenize() のためのトークンを分離する文字。デフォルト値は、 " \t\n()<>;&|" です。
 
char * history_no_expand_chars
 
history_expansion_char に続いてすぐに見つけられるなら、ヒストリ拡張を抑制する文字のリスト。デフォルトは、空白、タブ、改行、 \r= です。
 
char * history_search_delimiter_chars
 
部分文字列検索の場合における空白、タブ、 :? に加えてヒストリ検索文字列を区切ることができる追加文字のリスト。デフォルトは空です。
 
int history_quotes_inhibit_expansion
 
0 でなければ、単一引用符で引用されたワードはヒストリ拡張文字のためにスキャンされません。デフォルト値は、0 です。
 
rl_linebuf_func_t * history_inhibit_expansion_function
 
これは、2 つの引数を取る関数のアドレスに設定されるべきです: char * ( string) と int はその文字列 ( i) にインデックス付けます。 string[i] で始まるヒストリ拡張が実行されるべきでないなら、 0 以外の値を返すべきです。拡張を行うべきであるなら 0 を返すべきです。それは、追加目的のためにヒストリ拡張文字を使用する bash のようなアプリケーションでの使用を対象としています。デフォルトで、この変数は、 NULL に設定されます。

関連ファイル

~/.history
ヒストリが保存された読み込みと書き込みのためのデフォルトのファイル名

関連項目

The Gnu Readline Library, Brian Fox and Chet Ramey
The Gnu History Library, Brian Fox and Chet Ramey
bash(1)
readline(3)

作者

Brian Fox, Free Software Foundation
 
bfox@gnu.org

Chet Ramey, Case Western Reserve University

 

chet@ins.CWRU.Edu

バグ報告

history ライブラリでバグを見つけたなら、それを報告するべきです。しかし、最初に、利用者はそれが本当にバグであり、利用者が使っている history ライブラリの最新版に現れるかを確かめるべきです。

いったん、バグが実際に存在すると決定すれば、バグレポートを bug-readline@ gnu.org にメールしてください。また、修正があるなら、それをメールすることは歓迎されています! 提案と `賢明な' バグレポートは、 bug-readline@ gnu.org にメールするか、または Usenet のニュースグループ gnu.bash.bug にポスト (投稿) してください。

このマニュアルページに関するコメントとバグレポートは chet@ins.CWRU.Edu に直接送るべきです。

2003 July 31 GNU History 5.0