- はじめに -
以下の記事でxonshのEnvironment Variablesの大体の日本語訳を書いた。
しかし、上記の記事は2017年次の物かつ、要約的な記事のため、より詳細に見て開発に以降できるよう本体へのコードや掴みどころをメモした記事を書いておく。
本家ドキュメントは下記なので参照のこと。
- - はじめに -
- - Windowsに関連するもの -
- - xonsh本体の動作に関するもの -
- $XONSHRC
- $VIRTUAL_ENV
- $XONSH_HISTORY_SIZE
- $XONSH_HISTORY_BACKEND
- $SUPPRESS_BRANCH_TIMEOUT_MESSAGE
- $VC_BRANCH_TIMEOUT
- $VC_HG_SHOW_BRANCH
- $UPDATE_OS_ENVIRON
- $VI_MODE
- $XDG_DATA_HOME
- $XONSH_DATA_DIR
- $XONSH_CACHE_EVERYTHING
- $XONSH_CACHE_SCRIPTS
- $XONSH_TRACEBACK_LOGFILE
- $XONSH_STORE_*
- $XONSH_DATETIME_FORMAT
- $XONSH_DEBUG
- $XONSH_ENCODING
- $XONSH_ENCODING_ERRORS
- $XONSH_PROC_FREQUENCY
- - コマンド補完に関するもの -
- $UPDATE_COMPLETIONS_ON_KEYPRESS
- $AUTO_SUGGEST
- $AUTO_SUGGEST_IN_COMPLETIONS
- $COMPLETIONS_DISPLAY
- $COMPLETIONS_MENU_ROWS
- $COMPLETION_IN_THREAD
- $COMPLETION_QUERY_LIMIT
- $COMPLETIONS_CONFIRM
- $BASH_COMPLETIONS
- $CASE_SENSITIVE_COMPLETIONS
- $COMPLETIONS_BRACKETS
- $FUZZY_PATH_COMPLETION
- $GLOB_SORTED
- $SUBSEQUENCE_PATH_COMPLETION
- $SUGGEST_COMMANDS
- $SUGGEST_MAX_NUM
- $SUGGEST_THRESHOLD
- $XONSH_AUTOPAIR
- $XONSH_HISTORY_MATCH_ANYWHERE
- - ファイル、ディレクトリ操作に関するもの -
- - 表示に関するもの -
- $PROMPT
- $PROMPT_FIELDS
- $RIGHT_PROMPT
- $BOTTOM_TOOLBAR
- $XONSH_GITSTATUS_*
- $UPDATE_PROMPT_ON_KEYPRESS
- $PROMPT_REFRESH_INTERVAL
- $COLOR_INPUT
- $COLOR_RESULTS
- $PRETTY_PRINT_RESULTS
- $DYNAMIC_CWD_WIDTH
- $DYNAMIC_CWD_ELISION_CHAR
- $INDENT
- $LS_COLORS
- $XONSH_COLOR_STYLE
- $PTK_STYLE_OVERRIDES
- $PROMPT_TOOLKIT_COLOR_DEPTH
- $MULTILINE_PROMPT
- $TITLE
- $XONSH_SHOW_TRACEBACK
- $XONSH_STDERR_*
- - コマンドやxonshスクリプトの動作、変数の扱いに関するもの -
- - キーバインドや操作に関するもの -
- - フラグや変数として利用するもの -
- - おわりに -
- Windowsに関連するもの -
$ANSICON
- doc: https://xon.sh/envvars.html#ansicon
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/base_shell.py#L516
- type: bool
Windowsのcmd.exe(コマンドプロンプト)において、ANSI escape sequencesを表示するためのアプリケーションであるansicon*1を利用するかどうかの設定。ansiconを利用する場合にTrueにしておくと、$TITLEをプロンプトのタイトルに設定するようになる。実装でいうと以下のような感じ。
import ctypes ctypes.windll.kernel32.SetConsoleTitleW(env.get("TITLE"))
$FORCE_POSIX_PATHS
- doc: https://xon.sh/envvars.html#force-posix-paths
- code:
- type: bool
TrueであればWindows上のpathの補完等でもスラッシュ(/)を利用する。
$INTENSIFY_COLORS_ON_WIN
- doc: https://xon.sh/envvars.html#intensify-colors-on-win
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/pyghooks.py#L533
- type: bool
Windowsのcmd.exeを利用する時に、colorを見やすくするかどうかのフラグ。青色がシアンに置き換わったりする。
そもそも近年でcolor style自体がかなり柔軟になったので、不要かも。細かく指定しない場合には使える。
$WIN_UNICODE_CONSOLE
- doc: https://xon.sh/envvars.html#win-unicode-console
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/tools.py#L1559
- type: bool
Trueであれば、WindowsでのUnicodeサポートを有効にする。win_unicode_consoleなる外部ライブラリをimportしているだけ。以下必須。
pip install win_unicode_console
$PATHEXT
- doc: https://xon.sh/envvars.html#pathext
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/xoreutils/_which.py
- type: list
環境変数のPATHを見に行った時に、実行可能ファイルとして判定する拡張子のリスト。
".EXE"のように大文字で指定する。xonsh上でWINDOWS判定されていれば、[".COM", ".EXE", ".BAT", ".CMD"]がデフォルトで入るので、それ以外に必要であれば追加する。
- xonsh本体の動作に関するもの -
$XONSHRC
- doc: https://xon.sh/envvars.html#xonshrc
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/main.py#L294
- type: list
rcファイルへのpathのリスト。['~/xonshrc', '~/.config/xonsh/rc.xsh']のように複数あれば前方から複数読み込まれるし、ファイルがなければ読み込まれず終わる。
$VIRTUAL_ENV
- doc: https://xon.sh/envvars.html#virtual-env
- code:
- type: str
アクティブなPythonへのPath。pythonやpipコマンドが指すところでもあり、xonsh用のpythonバージョン管理ツールであるvoxも参照するpathになる。
デフォルトでは変数が設定されていない状態なので注意。
$XONSH_HISTORY_SIZE
- doc: https://xon.sh/envvars.html#xonsh-history-size
- code:
- type: set or str
historyのサイズの指定。「(8128, "commands")」「"8128 commands"」のようなsetか文字列で、保存するコマンド数(commands)、保持する履歴ファイル数(files)、許可される秒数(s)、バイト数(b)の単位のどれかと値を指定する。
$XONSH_HISTORY_BACKEND
- doc: https://xon.sh/envvars.html#xonsh-history-backend
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/history/main.py
- type: str (json or sql)
historyの保存形式。デフォルトはjsonだが、sqlを設定すればsqliteをバックエンドに選べる。設定は以下を見ると良い。
https://xon.sh/tutorial_history_backend.html
$SUPPRESS_BRANCH_TIMEOUT_MESSAGE
- doc: https://xon.sh/envvars.html#suppress-branch-timeout-message
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/prompt/vc.py#L120
- type: bool
Trueであれば、VC_BRANCH_TIMEOUTに設定された時間を過ぎてもPROMPTの文字列、branch名、色の生成が終わって無かった場合に強制的にタイムアウトとしメッセージを表示する。PROMPTに{curr_branch}でブランチ名を表示させようとするが、git repoが巨大で…という時に起こる。
$VC_BRANCH_TIMEOUT
- doc: https://xon.sh/envvars.html#vc-branch-timeout
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/prompt/vc.py
- type: float
gitのブランチ名などをPROMPTに表示する時にタイムアウトする秒数。デカいrepo触ったりする時に設定しておくと良い。
$VC_HG_SHOW_BRANCH
- doc: https://xon.sh/envvars.html#vc-hg-show-branch
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/prompt/vc.py
- type: bool
Trueであれば、Mercurialのブランチを表示する。gitでなくMercurial使っている場合はこちら。
$UPDATE_OS_ENVIRON
- doc: https://xon.sh/envvars.html#update-os-environ
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/environ.py#L1565
- type: bool
Trueであれば、xonshのEnvが追加、削除された場合にその変更をos側の環境変数にも加える。デフォルトはfalse。
中身は「os.environ.update」を少し工夫して呼んでいるだけなので、個別にos側に追加したい時は不要。WindowsとかOSの環境変数が影響の大きい環境では使える場合があるかも。
$VI_MODE
- doc: https://xon.sh/envvars.html#vi-mode
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/shell.py#L112
- type: bool
Trueであれば、シェルの操作がvi風になる。iでinsert、escでnormalモードになるなど。
実装自体はprompt toolkitの機能で、現行のモードを判定するfilterとして実装されている以下の部分から追っていくと良い。
https://github.com/prompt-toolkit/python-prompt-toolkit/blob/master/prompt_toolkit/filters/cli.py
$XDG_DATA_HOME
- doc: https://xon.sh/envvars.html#xdg-data-home
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/pygments_cache.py#L253
- type: str
英語では「Open desktop standard data home dir」となっているが、普通にセッションログやスクリプトの実行ログが入る場所へのpathというだけ。以下のXONSH_DATA_DIRに近いが、こちらのPathはxonsh用ではなく、一般的な環境全体用。
すこし踏み入ればpygmentsを使った実装になっていることが分かるが、難しい事はほとんどしておらず整備もあまりされていない印象。pygmentsすごい。
$XONSH_DATA_DIR
- doc: https://xon.sh/envvars.html#xonsh-data-dir
- code:
- type: str
セッションログやスクリプトの実行ログが入る場所へのpath。
デフォルトでは「$XDG_DATA_HOME + "/xonsh"」 が設定されている。
$XONSH_CACHE_EVERYTHING
- doc: https://xon.sh/envvars.html#xonsh-cache-everything
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/codecache.py
- type: bool
Trueであれば、全てのコード(コマンド含め)をキャッシュに保存する。
ここで言っているキャッシュというのは、historyではなく、そのセッションにおけるキャッシュで、できるだけコンパイルして保存しておいて次回のコマンド実行を早めるというもの。
$XONSH_CACHE_SCRIPTS
- doc: https://xon.sh/envvars.html#xonsh-cache-scripts
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/codecache.py
- type: bool
Trueであれば、スクリプト実行をキャッシュに保存する。
機構自体は上記のXONSH_CACHE_EVERYTHINGと同じだが、こちらはexecを通るようなスクリプトを実行した場合のキャッシュ。
$XONSH_TRACEBACK_LOGFILE
- doc: https://xon.sh/envvars.html#xonsh-traceback-logfile
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/tools.py#L901
- type: str
XONSH_SHOW_TRACEBACKがTrueの場合に、ログファイルとして残す先。ファイル名か不要の場合はNoneにしておく。
$XONSH_STORE_*
- doc:https://xon.sh/envvars.html#xonsh-store-stdin, https://xon.sh/envvars.html#xonsh-store-stdout
- code:
- type: bool
Trueであればhistoryに標準入出力を保存する。
$XONSH_STORE_STDIN
xonshの!()や![]オペレータを使って実行されたものをhistoryに保存する。
$XONSH_STORE_STDOUT
stderrやstdoutをhistoryに保存する。
$XONSH_DATETIME_FORMAT
- doc: https://xon.sh/envvars.html#xonsh-datetime-format
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/tools.py#L2333
- type: str
ログやhistoryなど多くの場所で使われるdatetimeのフォーマット。デフォルトでは「"%Y-%m-%d %H:%M"」。
利用先は多いが、実装はtools.pyの中に収まっているだけでシンプル。
$XONSH_DEBUG
- doc: https://xon.sh/envvars.html#xonsh-debug
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/main.py#L281
- type: int (1~3)
デバッグモードの指定。1であればimport情報、2であれば入力変換、コマンド置換の情報、3以上であればPLY解析メッセージと情報が増えていく。
よくissueを立てると「$XONSH_DEBUG=3 で一回ログ出して見て」とよく言われたりする。
実装自体は、参照されている部分が多いので変更は大変そうだが、追加はlogging足すだけなので参考に。
$XONSH_ENCODING
- doc: https://xon.sh/envvars.html#xonsh-encoding
- code:
- type: str
xonshのサブプロセスで利用されるエンコーディング。デフォルトでは「sys.getdefaultencoding()」が入る。
I/O制御で使われているTeeクラス、入力を作るreadline辺りが主に利用している。
$XONSH_ENCODING_ERRORS
- doc: https://xon.sh/envvars.html#xonsh-encoding-errors
- type: str
Pythonのエンコーディングエラーが出た時の処理。多くの場所で共通して使われている。
入る値は以下を参考に。
https://docs.python.org/3/library/codecs.html#error-handlers
$XONSH_PROC_FREQUENCY
- doc: https://xon.sh/envvars.html#xonsh-proc-frequency
- code:
- type: float
連続したパイプラインを実行する時、キューを読み込むためにxonshプロセススレッドがスリープする秒数。
スリープタイムというよりは、コマンドを連続で実行した時、スレッド同士のキューが詰まった場合にタイムアウトする時間のイメージ。
- コマンド補完に関するもの -
$UPDATE_COMPLETIONS_ON_KEYPRESS
- doc: https://xon.sh/envvars.html#update-completions-on-keypress
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/shell.py#L95
- type: bool
Trueであれば、キー入力時に毎回補完候補を出すようになる。例えば補完であればTABを押さなくてもキー入力毎に候補を表示できるようになる。
PROMPTの表示を評価するUPDATE_PROMPT_ON_KEYPRESSも別にあるので混同に注意。
実装自体はprompt toolkitの機能で、xonshはこの変数をフラグとしてptkの引数となるcomplete_while_typingに投げているだけである。その仕組み自体を把握するにはptkを追う必要がある。詳細は以下。
https://python-prompt-toolkit.readthedocs.io/en/latest/pages/asking_for_input.html?highlight=complete_while_typing#complete-while-typing
$AUTO_SUGGEST
- doc: https://xon.sh/envvars.html#auto-suggest
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/shell.py#L190
- type: bool
Trueの時にfish shellのようなグレーアウトの補完候補を出す*2。
この機能はxonshのコアライブラリであるpython prompt toolkit内の実装なので、そちらを参考にすると良い。
https://github.com/prompt-toolkit/python-prompt-toolkit/blob/master/docs/pages/asking_for_input.rst#auto-suggestion
表示されている補完候補を確定するときは「右矢印」「ctrl+e」がデフォルトで設定されている。変更する場合は以下が参考になる。
xonsh[ptk]で、Suggestionを確定するキーバインドを設定する - Qiita
下記のAUTO_SUGGEST_IN_COMPLETIONSとも関連しており、両者がTrueになっている場合、AUTO_SUGGESTで表示される候補をTab補完から除く等の機能があるので設定はよしなに。
$AUTO_SUGGEST_IN_COMPLETIONS
- doc: https://xon.sh/envvars.html#auto-suggest-in-completions
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/completer.py#L49
- type: bool
Trueの時、Tabキーで補完候補を表示する。$UPDATE_COMPLETIONS_ON_KEYPRESSがTrueの時は、Tab以外のキーでもキー入力時に補完候補が動的に表示される。
AUTO_SUGGEST同様、xonshというよりはpython prompt toolkitの機能であり、そちらを呼び出すかどうかのフラグにあたる。
https://github.com/prompt-toolkit/python-prompt-toolkit/blob/master/docs/pages/asking_for_input.rst#autocompletion
$COMPLETIONS_DISPLAY
- doc: https://xon.sh/envvars.html#completions-display
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/shell.py#L51
- type: str ("none" or "single" or "multi" or "readline") or bool or None
Pythonのコードの補完を表示するか、もしくは表示形式をどうするか。
none or false
表示しない。stringの"none"や"false"でも良いし、PythonのNoneでも、boolのFalseでも良い。
single
1列で補完候補を表示する。stringで"single"。
multi or true
複数列で表示する。デフォルト値。stringで"multi"、"true"とするか、boolのTrueを指定する。
$COMPLETIONS_MENU_ROWS
- doc: https://xon.sh/envvars.html#completions-menu-rows
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/completer.py#L91
- type: str ("single" or "multi") or int
補完を出す行数の指定。stringの"multi"だと5行で横幅最大まで補完を省略して表示する。int値を指定しても良い。
$COMPLETION_IN_THREAD
- doc: https://xon.sh/envvars.html#completion-in-thread
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/shell.py#L127
- type: bool
補完をasync/awaitで表示する。
実装自体はprompt toolkitのAppの引数にフラグを入れているだけで、非同期補完の詳細を見るにはptkのasync_promptの実装を見ると良い。
https://python-prompt-toolkit.readthedocs.io/en/master/pages/asking_for_input.html#asynchronous-completion
https://github.com/prompt-toolkit/python-prompt-toolkit/blob/master/prompt_toolkit/shortcuts/prompt.py#L909
$COMPLETION_QUERY_LIMIT
- doc: https://xon.sh/envvars.html#completion-query-limit
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/readline_shell.py#L222
- type: int
補完メニューの表示件数。最大件数では無く、これを超えたら補完が表示される閾値のイメージ。
xonshやprompt toolkitの機能というよりは、GNU Readlineのrl_completion_query_itemsをglobal変数として入れておくという実装なので、詳しくは以下を読む。
GNU Readline Library - Programming with GNU Readline
$COMPLETIONS_CONFIRM
- doc: https://xon.sh/envvars.html#completions-confirm
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/key_bindings.py#L136
- type: bool
タブ補完メニューが表示されている時、FalseだとEnterでコマンドを直接実行、TrueだとEnterでコマンドを確定のみして確認状態にする。
実装はprompt toolkitのkeybindにfilterを設定しているので、理解したければptkのkeybindingsを理解してからが良い。
$BASH_COMPLETIONS
- doc: https://xon.sh/envvars.html#bash-completions
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/completers/bash_completion.py
- type: list or tuple
bashのcompletionを利用するために、bash_completionスクリプトへのPATHを設定するための変数。sshの補完やgitの補完が含まれるため、基本的には必須だと思う。
listかtupleで最初に有効だったものが利用される。
brew install bash-completion2
こちらは、"/usr/local/share/bash-completion/bash_completion" にファイルが配置される。デフォルトでBASH_COMPLETIONSにこのpathが入っているはずなので、基本的にはインストールだけで設定できるはず。
デフォルトだといくつか設定されており、それらを走査する実装になっているため、もし一意に絞れるようであれば絞るかソートで前に持ってきておくと良い。
$CASE_SENSITIVE_COMPLETIONS
- doc: https://xon.sh/envvars.html#case-sensitive-completions
- code:
- jedi: https://github.com/xonsh/xonsh/blob/master/xontrib/jedi.xsh
- readline: https://github.com/xonsh/xonsh/blob/master/xonsh/readline_shell.py#L176
- global: https://github.com/xonsh/xonsh/blob/master/xonsh/built_ins.py#L150
- path: https://github.com/xonsh/xonsh/blob/master/xonsh/completers/path.py#L121
- filter: https://github.com/xonsh/xonsh/blob/master/xonsh/completers/tools.py#L14
- type: bool
Trueであれば、補完で大文字と小文字を区別する。Pythonの変数やディレクトリ、環境変数などの補完全てに共通した設定。
$COMPLETIONS_BRACKETS
- doc: https://xon.sh/envvars.html#completions-brackets
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/completers/python.py#L244
- type: bool
Trueの時、シェル入力時にPythonの括弧の補間を有効にする。実装自体はシンプルなので読めば大体分かると思う。
$FUZZY_PATH_COMPLETION
- doc: https://xon.sh/envvars.html#fuzzy-path-completion
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/completers/path.py#L302
- type: bool
Trueであれば、pathをTab補完する時にfuzzyに補完する。あいまい補完。
> $FUZZY_PATH_COMPLETION = True > ls desko ./Desktop
具体的な実装としてはlevenshteinを使っており、以下を見れば良い。
https://github.com/xonsh/xonsh/blob/master/xonsh/tools.py#L854
$GLOB_SORTED
- doc: https://xon.sh/envvars.html#glob-sorted
- code:
- type: bool
Trueであれば補完の結果をソートしてから表示する。
$SUBSEQUENCE_PATH_COMPLETION
- doc: https://xon.sh/envvars.html#shell-type
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/completers/path.py#L286
- type: bool
Trueであれば、pathの補完において ~/w/t のような入力でも拡大解釈されて ~/work/tmp も候補に上がるようになる。
ディレクトリが長い時に雑に打って移動する時に使える。
$SUGGEST_COMMANDS
- doc: https://xon.sh/envvars.html#suggest-commands
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/tools.py#L854
- type: bool
Trueであれば、無効なコマンドを入力した時に「もしかして?」を表示する。
$SUGGEST_MAX_NUM
- doc: https://xon.sh/envvars.html#suggest-max-num
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/tools.py#L854
- type: int
SUGGEST_COMMANDSがTrueの時に表示するコマンド数。負の値を入れておくと制限なしになる。
$SUGGEST_THRESHOLD
- doc: https://xon.sh/envvars.html#suggest-threshold
- code:
- type: int
SUGGEST_COMMANDSやFUZZY_PATH_COMPLETIONでレーベンシュタイン距離を計算して、その閾値として扱う値。デフォルトは3。
$XONSH_AUTOPAIR
- doc: https://xon.sh/envvars.html#xonsh-autopair
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/key_bindings.py
- type: bool
Trueであれば、括弧、括弧、引用符を自動挿入する。
keybindingsのfilterとして実装されているので、prompt toolkitにおけるfilterが何かを追ってから読むと大体実装もわかる。
$XONSH_HISTORY_MATCH_ANYWHERE
- doc: https://xon.sh/envvars.html#xonsh-history-match-anywhere
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/shell.py#L117
- type: bool
Trueであれば、上矢印で履歴を参照する時、現在の入力を検索語として接頭語以外でも補完する。
実装自体はprompt toolkitのbufferにおけるhistory matchなので、以下を参照すると良い。
https://github.com/prompt-toolkit/python-prompt-toolkit/blob/master/prompt_toolkit/buffer.py#L911
- ファイル、ディレクトリ操作に関するもの -
$AUTO_CD
- doc: https://xon.sh/envvars.html#auto-cd
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/built_ins.py#L701
- type: bool
Trueにしておくとcdコマンドを打たなくてもディレクトリ名だけで移動できる。
$CDPATH
- doc: https://xon.sh/envvars.html#cdpath
- code:
- type: set
bash, zsh等のCDPATHと同じ。cdコマンドが利用する相対パス。CDPATHによく使うディレクトリを入れておけば、cd hogeでショートカットのように移動できるので便利。一方で補間含めて全ての相対パスがこちらを参照するようになるので、使う場合は意図しないディレクトリに移動しないよう注意が必要。
$AUTO_PUSHD
- doc: https://xon.sh/envvars.html#auto-pushd
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/dirstack.py#L263
- type: bool
DOSで言う所のディレクトリスタックに対して、cd時に自動でpushdする。pushd、popd、dirsコマンド*3を良く使うのであれば良い。
$DIRSTACK_SIZE
- doc: https://xon.sh/envvars.html#dirstack-size
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/dirstack.py#L364
- type: int
DOSで言う所のディレクトリスタックの最大保存数。実装自体は至極簡単なので読めば分かるはず。
$PUSHD_MINUS
- doc: https://xon.sh/envvars.html#pushd-minus
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/dirstack.py#L313
- type: bool
ディレクトリスタックの操作pushd、popdに関するフラグ。Falseが通常のシェルコマンドのpushdで、Trueの場合はpushdとpopdが逆になる。
$PUSHD_SILENT
- doc: https://xon.sh/envvars.html#pushd-silent
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/dirstack.py#L368
- type: bool
Trueならディレクトリスタックにpushdした時に表示する。デフォルトのFalseなら表示しない。
$DOTGLOB
- doc: https://xon.sh/envvars.html#dotglob
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/tools.py#L2234
- type: bool
Trueなら「*」や「**」を使ってglobした時にドットで始まるドットファイルを含むようにする。
実装はシンプルにreplaceで変換しているだけなので、読めば分かるはず。
- 表示に関するもの -
$PROMPT
- doc: https://xon.sh/envvars.html#prompt
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/shell.py#L208
- type: str
xonshというよりはpython prompt toolkitの機能であり、ptk内のAppに対する引数に与える文字列に当たる。
https://github.com/prompt-toolkit/python-prompt-toolkit/blob/master/docs/pages/asking_for_input.rst#adding-a-bottom-toolbar
背景色や文字色も変更できるので、以下のドキュメントを参考にすると良い。
Asking for input (prompts) — prompt_toolkit 3.0.0 documentation
More about styling — prompt_toolkit 3.0.0 documentation
$PROMPTの表示。詳しく設定したい場合は、以下のチュートリアルを見ながら設定を進めると良い。
https://xon.sh/tutorial.html#customizing-the-prompt
$PROMPT_FIELDS
- doc: https://xon.sh/envvars.html#prompt-fields
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/prompt/base.py
- type: dict
$PROMPTに対してオリジナルのフォーマットを関数等で指定できる。詳しく設定したい場合は、以下のチュートリアルを見ながら設定を進めると良い。
https://xon.sh/tutorial.html#customizing-the-prompt
$RIGHT_PROMPT
- doc: https://xon.sh/envvars.html#right-prompt
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/shell.py#L222
- type: str
xonshというよりはpython prompt toolkitの機能であり、ptk内のAppに対する引数に与える文字列に当たる。
https://github.com/prompt-toolkit/python-prompt-toolkit/blob/master/docs/pages/asking_for_input.rst#adding-a-bottom-toolbar
背景色や文字色も変更できるので、以下のドキュメントを参考にすると良い。
Asking for input (prompts) — prompt_toolkit 3.0.0 documentation
More about styling — prompt_toolkit 3.0.0 documentation
右側のPROMPTに表示する文字列。詳しく設定したい場合は、以下のチュートリアルを見ながら設定を進めると良い。
https://xon.sh/tutorial.html#customizing-the-prompt
$BOTTOM_TOOLBAR
- doc: https://xon.sh/envvars.html#bottom-toolbar
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/shell.py#L239
- type: str
bottom toolbarを表示する文字列。空ならbottom toolbar無しになる。
xonshというよりはpython prompt toolkitの機能であり、ptk内のAppに対する引数に与える文字列に当たる。
https://github.com/prompt-toolkit/python-prompt-toolkit/blob/master/docs/pages/asking_for_input.rst#adding-a-bottom-toolbar
背景色や文字色も変更できるので、以下のドキュメントを参考にすると良い。
Asking for input (prompts) — prompt_toolkit 3.0.0 documentation
More about styling — prompt_toolkit 3.0.0 documentation
詳しく設定したい場合は、以下のチュートリアルを見ながら設定を進めると良い。
https://xon.sh/tutorial.html#customizing-the-prompt
$XONSH_GITSTATUS_*
- doc: https://xon.sh/envvars.html#xonsh-gitstatus
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/prompt/gitstatus.py
- type: str
xonshのgit statusのシンボル。gitコマンドがない場合はそれぞれsetされないので注意。
$XONSH_GITSTATUS_HASH
ハッシュ値。「git describe --always」と「git rev-parse --short HEAD」の値が違っていたら、XONSH_GITSTATUS_HASH+後者の値をHASHとして表示する実装。以下参照。
https://github.com/xonsh/xonsh/blob/master/xonsh/prompt/gitstatus.py#L89
デフォルト値は":"。
$XONSH_GITSTATUS_BRANCH
ブランチ名。デフォルト値は"{CYAN}"。
$XONSH_GITSTATUS_OPERATION
rebase中だとかmerge中だとかの状態シンボル。
[https://github.com/xonsh/xonsh/blob/master/xonsh/prompt/gitstatus.py#L104[
デフォルト値は"{CYAN}"。
$XONSH_GITSTATUS_STAGED
stageに乗っている時のシンボル。デフォルト値は"{RED}●"。
$XONSH_GITSTATUS_CONFLICTS:
コンフリクトが置きている時のシンボル。デフォルト値は"{RED}×"。
$XONSH_GITSTATUS_CHANGED
変更がある状態のシンボル。デフォルト値は"{BLUE}+"。
$XONSH_GITSTATUS_UNTRACKED
gitをトラックしていない時のシンボル。デフォルト値は"…"。
$XONSH_GITSTATUS_STASHED
stashした状態のシンボル。デフォルト値は"⚑"。
$XONSH_GITSTATUS_CLEAN
git上記の状態以外でclearな時のシンボル。デフォルト値は"{BOLD_GREEN}✓"。
$XONSH_GITSTATUS_AHEAD
masterブランチとのズレがaheadな状態を示すシンボル。デフォルト値は"↑·"。
$XONSH_GITSTATUS_BEHIND
masterブランチとのズレがbehindな状態を示すシンボル。デフォルト値は"↓·"。
$UPDATE_PROMPT_ON_KEYPRESS
- doc: https://xon.sh/envvars.html#update-prompt-on-keypress
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/shell.py#L103
- type: bool
Trueであれば、キー入力ごとにPROMPT表示を評価する。PROMPTに時計を実装したり、gitの状態を表示する時に有用。
実装もprompt toolkitにprompt周りの設定を関数で渡すか、stringで渡すかの違いでしかないのでシンプル。
実際評価しているのはptkなので、以下辺りから追っていくと良い。
https://github.com/prompt-toolkit/python-prompt-toolkit/blob/master/prompt_toolkit/shortcuts/prompt.py
$PROMPT_REFRESH_INTERVAL
- doc: https://xon.sh/envvars.html#prompt-refresh-interval
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/shell.py#L89
- type: float or None
PROMPTを更新する秒数を入れる。実装自体はprompt toolkitにあり、以下のサンプルのようにbottom_toolbarやrpromptでリアルタイムに更新される時計を作ったりできる。
https://github.com/prompt-toolkit/python-prompt-toolkit/blob/2.0/examples/prompts/clock-input.py
私が追加した変数なのだが、もちろん画面全体が指定秒でリフレッシュされて更新される訳なので、シェルの動作が重くなってしまう。(rpromptだけとか出来るようになっていくと良いな…)
$COLOR_INPUT
- doc: https://xon.sh/envvars.html#color-input
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/shell.py#L146
- type: bool
入力しているコマンドにsyntax highlightingをつける。実装自体は、prompt toolkit及びpygmentsによる実装なので以下を参考にすると良い。
https://github.com/prompt-toolkit/python-prompt-toolkit/blob/master/prompt_toolkit/lexers/pygments.py#L145
$COLOR_RESULTS
- doc: https://xon.sh/envvars.html#color-results
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/main.py#L258
- type: bool
出力結果にsyntax highlightingをつける。実装自体は、上記のCOLOR_INPUTと同じくprompt toolkit及びpygmentsによる実装なので以下を参考にすると良い。
https://github.com/prompt-toolkit/python-prompt-toolkit/blob/master/prompt_toolkit/lexers/pygments.py#L145
$PRETTY_PRINT_RESULTS
- doc:https://xon.sh/envvars.html#pretty-print-results
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/main.py#L246
- type: bool
Tanaka Akira氏が作っているrubyのprettyprint.rbを使って、出力を表示するかどうかのフラグ。
以下のドキュメントの通り、単体でもapiとして使えるようにはなっている。
https://xon.sh/api/pretty.html
$DYNAMIC_CWD_WIDTH
- doc: https://xon.sh/envvars.html#dynamic-cwd-width
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/prompt/cwd.py#L48
- type: tuple
$PROMPTに表示するディレクトリを省略する時の文字数閾値。
(float, str)のtupleで、0番目に閾値を入れる。float('inf')を入れる事もできる。
1番目にはstringの"%"かそれ以外が入る。"%"を入れた場合はShellの画面サイズに対する0番目の値のパーセンテージになる。"%"以外を入れたらシンプルに0番目がintになって文字数で閾値になる。
$DYNAMIC_CWD_ELISION_CHAR
- doc: https://xon.sh/envvars.html#dynamic-cwd-elision-char
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/prompt/cwd.py#L48
- type: str
$PROMPTに表示するディレクトリ名が長い場合に省略形として出す文字列。省略する時の文字数の閾値はDYNAMIC_CWD_WIDTHに依存。
$INDENT
- doc: https://xon.sh/envvars.html#indent
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/key_bindings.py#L25
- type: str
複数行入力のインデント文字列
$LS_COLORS
- doc: https://xon.sh/envvars.html#ls-colors
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/environ.py#L185
- type: str
bash, zsh同様、lsコマンドの出力の色指定。基本的には他のシェルのものが参考になるし、実装を見て色名でのstring指定もできる。
$XONSH_COLOR_STYLE
- doc: https://xon.sh/envvars.html#xonsh-color-style
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/pyghooks.py#L469
- type: str
xonshのcolorを統一的に変更できるthemeのような機能。適応できるstyleは「xonfig styles」で確認できる。
最近はPTK_STYLE_OVERRIDESやPROMPT_TOOLKIT_COLOR_DEPTHで柔軟に変更できるようになったが、このtheme機能も簡単に良い感じにできるので良さはある。
$PTK_STYLE_OVERRIDES
- doc: https://xon.sh/envvars.html#ptk-style-overrides
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/shell.py#L155
- type: dict
補完の表示色や、背景色、プロンプトの色などあらゆる色を設定するところ。
- "completion-menu": "bg:ansigray ansiblack"
- "completion-menu.completion": ""
- "completion-menu.completion.current": "bg:ansibrightblack ansiwhite"
- "scrollbar.background": "bg:ansibrightblack"
- "scrollbar.arrow": "bg:ansiblack ansiwhite bold"
- "scrollbar.button": "bg:ansiblack"
- "auto-suggestion": "ansibrightblack"
- "aborting": "ansibrightblack"
デフォルト値参考:https://github.com/laloch/xonsh/blob/master/xonsh/style_tools.py#L347
$PROMPT_TOOLKIT_COLOR_DEPTH
- doc: https://xon.sh/envvars.html#prompt-toolkit-color-depth
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/tools.py#L1471
- type: str
色の深度を決定できる変数。ドキュメントには書いていないが、コード上では以下の値が指定できる。
- "DEPTH_1_BIT"
- "MONOCHROME"
- "DEPTH_4_BIT"
- "ANSI_COLORS_ONLY"
- "DEPTH_8_BIT"
- "DEFAULT"
- "DEPTH_24_BIT"
- "TRUE_COLOR"
$MULTILINE_PROMPT
- doc: https://xon.sh/envvars.html#multiline-prompt
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/shell.py#L253
- type: str
コマンドを改行した際に表示される幅寄せ用の文字。
$TITLE
- doc: https://xon.sh/envvars.html#title
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/base_shell.py#L500
- type: str
ターミナルのタイトルを設定する。実装自体は以下のように非常にシンプルで、これで設定できないターミナルエミュレータを使っている場合は無意味。
if ON_WINDOWS and "ANSICON" not in env: kernel32.SetConsoleTitleW(t) else: with open(1, "wb", closefd=False) as f: f.write("\x1b]0;{0}\x07".format(t).encode()) f.flush()
iTerm2でタブ名が変わる例
$XONSH_SHOW_TRACEBACK
- doc: https://xon.sh/envvars.html#xonsh-show-traceback
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/tools.py#L901
- type: bool
Trueであれば、xonshコマンドがエラーの時にtracebackを全て表示する。長くなるのでデフォルトはFalse。
$XONSH_STDERR_*
- doc: https://xon.sh/envvars.html#xonsh-stderr-postfix, https://xon.sh/envvars.html#xonsh-stderr-prefix
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/base_shell.py#L264
- type: str
stderrの出力に接頭語、接尾語を付ける。stderrの色を設定したい時などに使える。
stdio周りはxonsh独自にTeeクラスが実装されていて、そこを通るのでそちらも参考に。
$XONSH_STDERR_POSTFIX
stderrの出力に付く接頭語。
$XONSH_STDERR_PREFIX
stderrの出力に付く接尾語。
- コマンドやxonshスクリプトの動作、変数の扱いに関するもの -
$EXPAND_ENV_VARS
- doc: https://xon.sh/envvars.html#expand-env-vars
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/tools.py#L99
- type: bool
Trueであれば「$var」「${var}」「%var%」をサブプロセスモードで自動で展開する。
実装自体はbuiltins.__xonsh__.envの中にあれば変換するし、なければそのまま文字列で利用するとなっている。
> $EXPAND_ENV_VARS=True > echo "my home is $HOME" my home is /Users/shunsuke.kawai > $EXPAND_ENV_VARS=False > echo "my home is $HOME" my home is $HOME
あまりFalseにする必要はないと思うが、format string等で不具合が出た時にはこちらの設定を確認すると良い。
$FOREIGN_ALIASES_OVERRIDE
- doc: https://xon.sh/envvars.html#foreign-aliases-override
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/foreign_shells.py#L688
- type: bool
zsh上でxonshコマンドでxonshを起動する等、外部シェルから呼び出されている場合にxonshrc等で設定するaliasを外部シェルのaliasに対してOverrideするかどうか。
扱いが難しく xonshが起動した時点でaliasesの読み込みは行われてしまうので、xonshrcやxonsh上のコマンドとして設定しても動作しない。
呼び出し元のbashやzshで環境変数としてFOREIGN_ALIASES_OVERRIDEを設定しておく必要があるので注意。
$FOREIGN_ALIASES_SUPPRESS_SKIP_MESSAGE
- doc: https://xon.sh/envvars.html#foreign-aliases-suppress-skip-message
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/aliases.py#L467
- type: bool
外部シェルのaliasが既に存在する時、xonsh上でOverrideしようとすると警告を出すaliasコマンドが一部存在する。その時のメッセージを表示しないようにするためのフラグ。
基本的にはTrueにしておいて問題ないと思う。
$HISTCONTROL
- doc: https://xon.sh/envvars.html#histcontrol
- code: xonsh/json.py at master · xonsh/xonsh · GitHub
- type: set ("ignoredups" or "ignoreerr")
履歴に保存するコマンドを選択する。
setの中にstringで"ignoreerr"を入れておくと、終了ステータスが0以外の正常終了しなかったコマンドを履歴に追加しない設定となる。
setの中にstringで"ignoreerr"を入れておくと、同じコマンドを連続で入力した時に保存しない設定となる。
$LANG
- doc: https://xon.sh/envvars.html#lang
- code: https://github.com/xonsh/xonsh/blob/master/scripts/xon.sh
- type: str
historyファイル等で利用する文字コード。あくまでxonsh内での文字コードなので、デフォルトのutf-8以外にする必要に迫られる場合は殆どないはず。
$SHELL_TYPE
- doc: https://xon.sh/envvars.html#shell-type
- code:
- type: str ("readline" or "prompt_toolkit" or "random" or "best")
シェルのコアライブラリを選択する。以下の4つのstringが指定できる。
- "readline"
- "prompt_toolkit"
- "random": ランダムにptkかreadlineを起動する
- "best": 環境に応じてptkかreadlineを起動する
基本的にというか"prompt_toolkit"でないとxonshの恩恵の殆どが受けられないので一択だと思う…readlineだとほぼbash…randomとかどういう時に使うんだろう…
$RAISE_SUBPROC_ERROR
- doc: https://xon.sh/envvars.html#raise-subproc-error
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/proc.py#L2252
- type: bool
Trueであれば、サブプロセス経由のコマンドが異常終了した場合にsubprocess.CalledProcessErrorを発生させる。デフォルトはFalse。
何も表示せず、ステータスコードを返さず終了するようなモジュールを使う時に役立つかも…?
$XONSH_APPEND_NEWLINE
- doc: https://xon.sh/envvars.html#xonsh-append-newline
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/base_shell.py#L372
- type: bool
Trueであれば、コマンドの結果の末尾に改行を追加する。
普通のシェルの動作として使う場合はTrueで、「xonsh -c hoge.py」のようにしてxonshを動かす場合に余計な改行が入ってしまうのでFalseにするためのもの。
デフォルト値にはXONSH_INTERACTIVEの値が入っており、基本的にインタラクティブシェルだったらTrueになるようになっている。
- キーバインドや操作に関するもの -
$IGNOREEOF
- doc: https://xon.sh/envvars.html#ignoreeof
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/key_bindings.py#L146
- type: bool
Trueであれば、「ctrl + d」でシェルを終了しない。
コマンド入力を待機し続けるループをbreakするかしないかという実装。
https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/shell.py#L186
$MOUSE_SUPPORT
- doc: https://xon.sh/envvars.html#mouse-support
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/ptk2/shell.py#L87
- type: bool
Trueであれば、シェル上でマウス操作を許可する。
実装自体はprompt toolkitの機能で、ptkの方を見に行くと良い。以下のexampleを実行すれば分かるように、マウスクリックでカーソルを移動させたりできる。
https://github.com/prompt-toolkit/python-prompt-toolkit/blob/master/examples/prompts/mouse-support.py
エディタやセレクターっぽい機能を実装する時にも使えるかも。
- フラグや変数として利用するもの -
$LOADED_RC_FILES
- doc: https://xon.sh/envvars.html#loaded-rc-files
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/environ.py#L1663
- type: list (bool)
xonshrcが読み込まれたかどうかのフラグをlistにしたもの。n番目が何のrcファイルなんだ…
$OLDPWD
- doc: https://xon.sh/envvars.html#oldpwd
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/environ.py#L1680
- type: str
一つ前に居たディレクトリの文字列が入る。起動時はcdするまでEnvがセットすらされてないので注意が必要。
$PATH
- doc: https://xon.sh/envvars.html#path
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/tools.py
- type: list
各シェルで言う所のいわゆるPATH。binとかスクリプトは個々に入っているディレクトリを見に行って実行する。
listなのでappendとかで追加する。bulitins.__xonsh__.env["PATH"]からもよく参照される。
$TERM
- doc: https://xon.sh/envvars.html#term
- type: str
基本的にはユーザが設定する事はなく、ターミナルエミュレータが与える変数。以下のようにWindowsのエミュレータの判定とかに使われる。
https://github.com/xonsh/xonsh/blob/master/xonsh/base_shell.py#L500
例えば以下のissueのように、Windows+AnacondaをWSL上から触っていてターミナルエミュレータが認識できない場合等に強制的に指定する場合に使う。
Unknown Terminal type using conda env (Windows 10 --> WSL) · Issue #2525 · xonsh/xonsh · GitHub
指定する時はドキュメントの通り、早い段階(xonsh起動時の引数、xonshrcの上部)で設定しないと他設定が読み込まれる。
$XONSH_INTERACTIVE
- doc: https://xon.sh/envvars.html#xonsh-interactive
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/main.py#L356
- type: bool
xonshがインタラクティブシェルとして起動しているか、「xonsh -c hoge.py」のようなスクリプト実行形式で起動しているかのフラグ。
$XONSH_LOGIN
- doc: https://xon.sh/envvars.html#xonsh-login
- code: https://github.com/xonsh/xonsh/blob/master/xonsh/main.py#L353
- type: bool
xonshがログインシェルとして起動しているかのフラグ。
$XONSH_SOURCE
- おわりに -
大体これで1.0.0までカバーできるはず。
今回「XDG_CONFIG_HOME」「XONSH_CONFIG_DIR」「XONSH_HISTORY_FILE」など非推奨やもう機能していないものを抜いているので注意。PRを出して改修するのが良さそう。