.nh
.TH DIRENV-STDLIB 1 "2019" direnv "User Manuals"
.SH "نام (NAME)"
direnv-stdlib \- توابع برای \fB\&.envrc\fR

.SH "خلاصه دستور (SYNOPSIS)"
\fBdirenv stdlib\fR

.SH "توضیحات (DESCRIPTION)"
یک اسکریپت bash موسوم به \fIstdlib\fP را خروجی می‌دهد. دستورهای زیر در آن اسکریپت گنجانده شده‌اند و در زمینهٔ یک \fB\&.envrc\fR بارگذاری می‌شوند. علاوه بر این، در صورت وجود، فایل موجود در \fB~/.config/direnv/direnvrc\fR را نیز بارگذاری می‌کند.

.SH STDLIB
.SS \fBhas <command>\fR
اگر \fIcommand\fP در دسترس باشد مقدار 0 و در غیر این صورت مقدار 1 را برمی‌گرداند. این می‌تواند یک باینری در PATH یا یک تابع پوسته باشد.

.PP
مثال:

.EX
if has curl; then
  echo "Yes we do"
fi
.EE

.SS \fBexpand_path <rel_path> [<relative_to>]\fR
مسیر مطلق \fIrel_path\fP را نسبت به \fIrelative_to\fP یا دایرکتوری فعلی خروجی می‌دهد.

.PP
مثال:

.EX
cd /usr/local/games
expand_path ../foo
# output: /usr/local/foo
.EE

.SS \fBdotenv [<dotenv_path>]\fR
یک فایل ".env" را در محیط فعلی بارگذاری می‌کند.

.SS \fBdotenv_if_exists [<dotenv_path>]\fR
یک فایل ".env" را در محیط فعلی بارگذاری می‌کند، اما فقط در صورتی که وجود داشته باشد.

.SS \fBuser_rel_path <abs_path>\fR
در صورت امکان، مسیر مطلق \fIabs_path\fP را به یک مسیر نسبی برای کاربر تبدیل می‌کند.

.PP
مثال:

.EX
echo $HOME
# output: /home/user
user_rel_path /home/user/my/project
# output: ~/my/project
user_rel_path /usr/local/lib
# output: /usr/local/lib
.EE

.SS \fBfind_up <filename>\fR
مسیر \fIfilename\fP را هنگام جستجو از دایرکتوری فعلی رو به بالا تا / خروجی می‌دهد. اگر فایل پیدا نشود، مقدار 1 را برمی‌گرداند.

.PP
مثال:

.EX
cd /usr/local/my
mkdir -p project/foo
touch bar
cd project/foo
find_up bar
# output: /usr/local/my/bar
.EE

.SS \fBsource_env <file_or_dir_path>\fR
یک \fB\&.envrc\fR دیگر را با مشخص کردن مسیر یا نام فایل آن بارگذاری می‌کند.

.PP
نکته: فایل \fB\&.envrc\fR دیگر توسط چارچوب امنیتی بررسی نمی‌شود.

.SS \fBsource_env_if_exists <filename>\fR
یک ".envrc" دیگر را بارگذاری می‌کند، اما فقط در صورتی که وجود داشته باشد.

.PP
نکته: برخلاف \fBsource_env\fR، این دستور تنها زمانی کار می‌کند که مسیر یک فایل مشخص شده باشد،
      نه یک دایرکتوری.

.PP
مثال:

.EX
source_env_if_exists .envrc.private
.EE.SS \fBenv_vars_required <varname> [<varname> ...]\fR
برای هر متغیری که در محیط وجود نداشته باشد یا مقدار آن خالی باشد، خطا ثبت می‌کند.
.br
معمولاً این دستور در ترکیب با source_env و source_env_if_exists استفاده می‌شود.

.PP
مثال:

.EX
# expect .envrc.private to provide tokens
source_env .envrc.private
# check presence of tokens
env_vars_required GITHUB_TOKEN OTHER_TOKEN
.EE

.SS \fBsource_up [<filename>]\fR
در صورت پیدا شدن یک \fB\&.envrc\fR دیگر به وسیلهٔ دستور find_up، آن را بارگذاری می‌کند. اگر هیچ فایلی پیدا نشود، مقدار ۱ را بازمی‌گرداند.

.PP
نکته: \fB\&.envrc\fR دیگر توسط چارچوب امنیتی بررسی نمی‌شود.

.SS \fBsource_up_if_exists [<filename>]\fR
در صورت پیدا شدن یک \fB\&.envrc\fR دیگر به وسیلهٔ دستور find_up، آن را بارگذاری می‌کند. اگر موردی یافت نشود، هیچ اتفاقی نمی‌افتد.

.PP
نکته: \fB\&.envrc\fR دیگر توسط چارچوب امنیتی بررسی نمی‌شود.

.SS \fBsource_url <url> <integrity-hash>\fR
اسکریپت دیگری را از \fBurl\fR داده‌شده بارگذاری می‌کند. پیش از بارگذاری، یکپارچگی آن را با استفاده از \fBintegrity-hash\fR ارائه‌شده بررسی خواهد کرد.

.PP
برای یافتن مقدار \fBintegrity-hash\fR، دستور \fBdirenv fetchurl <url>\fR را اجرا کرده و هش را از پیام خروجی استخراج کنید.

.PP
همچنین برای جزئیات بیشتر \fBdirenv-fetchurl(1)\fR را ببینید.

.SS \fBfetchurl <url> [<integrity-hash>]\fR
نشانی \fBurl\fR داده‌شده را روی دیسک بارگیری کرده و مکان مسیر آن را در stdout خروجی می‌دهد.

.PP
اگر آرگومان \fBintegrity-hash\fR ارائه شده باشد، صحت و یکپارچگی اسکریپت را نیز بررسی خواهد کرد.

.PP
همچنین برای جزئیات بیشتر \fBdirenv-fetchurl(1)\fR را ببینید.

.SS \fBdirenv_apply_dump <file>\fR
خروجی \fBdirenv dump\fR را که در یک فایل ذخیره شده است بارگذاری می‌کند.

.SS \fBdirenv_load [<command-generating-dump-output>]\fR
محیط تولیدشده حاصل از اجرای \fIargv\fP به عنوان یک دستور را اعمال می‌کند. این قابلیت برای اتخاذ محیط یک فرایند فرزند مفید است \- ترتیبی دهید که آن فرایند \(lqdirenv dump\(rq را اجرا کند و سپس نتایج را با direnv_load در بر بگیرید.

.PP
مثال:

.EX
direnv_load opam exec direnv dump
.EE

.SS \fBPATH_add <path>\fR
مسیر بسط‌یافتهٔ \fIpath\fP را به ابتدای متغیر محیطی PATH اضافه می‌کند. این دستور از اشتباه رایجی که در آن PATH تنها با \fIpath\fP جدید جایگزین می‌شود جلوگیری می‌کند.

.PP
مثال:

.EX
pwd
# output: /home/user/my/project
PATH_add bin
echo $PATH
# output: /home/user/my/project/bin:/usr/bin:/bin
.EE

.SS \fBMANPATH_add <path>\fR
مسیر بسط‌یافتهٔ \fIpath\fP را به ابتدای متغیر محیطی MANPATH اضافه می‌کند. این دستور منطق اکتشافی (heuristic) ویژهٔ man را مدیریت می‌کند..SS \fBpath_add <varname> <path>\fR
مانند \fBPATH_add\fR عمل می‌کند، با این تفاوت که برای یک \fIvarname\fP دلخواه است\&.

.SS \fBPATH_rm <pattern> [<pattern> ...]\fR
دایرکتوری‌هایی را که با هر یک از الگوهای شل داده‌شده مطابقت دارند از متغیر محیطی PATH حذف می‌کند. ترتیب دایرکتوری‌های باقی‌مانده در PATH حاصل حفظ می‌شود.

.PP
نحو الگوی Bash:
  https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html

.PP
مثال:

.EX
echo $PATH
# output: /dontremove/me:/remove/me:/usr/local/bin/:...
PATH_rm '/remove/*'
echo $PATH
# output: /dontremove/me:/usr/local/bin/:...
.EE

.SS \fBload_prefix <prefix_path>\fR
برخی متغیرهای رایج مسیر را برای پیشوندِ \fIprefix_path\fP داده‌شده گسترش می‌دهد. این دستور زمانی مفید است که برنامه‌ای را با استفاده از \fB\&./configure --prefix=$prefix_path && make install\fR در \fIprefix_path\fP نصب کرده باشید و بخواهید در پروژه از آن استفاده کنید.

.PP
متغیرهای مقداردهی‌شده:

.EX
CPATH
LD_LIBRARY_PATH
LIBRARY_PATH
MANPATH
PATH
PKG_CONFIG_PATH
.EE

.PP
مثال:

.EX
\&./configure --prefix=$HOME/rubies/ruby-1.9.3
make && make install
# Then in the .envrc
load_prefix ~/rubies/ruby-1.9.3
.EE

.SS \fBsemver_search <directory> <folder_prefix> <partial_version>\fR
یک دایرکتوری را برای یافتن بالاترین شماره نسخه در قالب SemVer (X.Y.Z) جستجو می‌کند.

.PP
مثال‌ها:

.EX
$ tree .
\&.
|-- dir
    |-- program-1.4.0
    |-- program-1.4.1
    |-- program-1.5.0
$ semver_search "dir" "program-" "1.4.0"
1.4.0
$ semver_search "dir" "program-" "1.4"
1.4.1
$ semver_search "dir" "program-" "1"
1.5.0
.EE

.SS \fBlayout <type>\fR
یک توزیع‌کننده معنایی (semantic dispatch) که برای توصیف ساختارهای رایج پروژه استفاده می‌شود.

.SS \fBlayout go\fR
مسیر "$(direnv_layout_dir)/go" را به متغیر محیطی GOPATH اضافه می‌کند.
و همچنین مسیر "$PWD/bin" را به متغیر محیطی PATH اضافه می‌کند.

.SS \fBlayout julia\fR
متغیر محیطی \fBJULIA_PROJECT\fR را روی دایرکتوری فعلی تنظیم می‌کند.

.SS \fBlayout node\fR
مسیر "$PWD/node_modules/.bin" را به متغیر محیطی PATH اضافه می‌کند..SS \fBlayout opam\fR
متغیرهای محیطی را از \fBopam env\fR تنظیم می‌کند\&.

.SS \fBlayout php\fR
مسیر "$PWD/vendor/bin" را به متغیر محیطی PATH اضافه می‌کند.

.SS \fBlayout perl\fR
متغیرهای محیطی مورد نیاز local::lib در perl را تنظیم می‌کند. برای جزئیات بیشتر http://search.cpan.org/dist/local-lib/lib/local/lib.pm را ببینید.

.SS \fBlayout pipenv\fR
مشابه \fBlayout python\fR، اما از Pipenv برای ساخت یک virtualenv از روی \fBPipfile\fR موجود در همان دایرکتوری استفاده می‌کند. این مسیر را می‌توان با متغیر محیطی \fBPIPENV_PIPFILE\fR بازنویسی کرد.

.PP
توجه داشته باشید که بر خلاف اجرای دستی Pipenv، این دستور متغیرهای محیطی را به‌طور خودکار از فایل \fB\&.env\fR بارگذاری نمی‌کند. برای شبیه‌سازی این رفتار می‌توانید \fBdotenv .env\fR را اضافه کنید.

.SS \fBlayout pyenv [<version> ...]\fR
مشابه \fBlayout python\fR، اما از pyenv برای ساخت یک virtualenv با نسخهٔ مشخص‌شدهٔ مفسر Python استفاده می‌کند.

.PP
می‌توان چندین نسخه را با فاصله از یکدیگر مشخص کرد؛ لطفاً برای اطلاعات بیشتر به مستندات pyenv مراجعه کنید.

.SS \fBlayout python [<python_exe>]\fR
یک محیط virtualenv زیر مسیر \fB$PWD/.direnv/python-$python_version\fR ایجاد و بارگذاری می‌کند\&. این کار نصب هرگونه egg را در زیرپوشهٔ پروژه اجباری می‌کند.

.PP
اگر می‌خواهید از نسخه‌های مختلف python استفاده کنید، مشخص کردن فایل اجرایی python امکان‌پذیر است (برای مثال: \fBlayout python python3\fR).

.PP
توجه داشته باشید که پیش‌تر virtualenv زیر مسیر \fB$PWD/.direnv/virtualenv\fR قرار داشت و در صورت وجود، توسط direnv مجدداً استفاده خواهد شد.

.SS \fBlayout python3\fR
میان‌بری برای \fBlayout python python3\fR

.SS \fBlayout ruby\fR
متغیر محیطی GEM_HOME را روی \fB$PWD/.direnv/ruby/RUBY_VERSION\fR تنظیم می‌کند\&. این کار نصب هرگونه gem را در زیرپوشهٔ پروژه اجباری می‌کند. اگر از bundler استفاده می‌کنید، برنامه‌های پوشش‌دهنده‌ای (wrapper) ایجاد می‌کند که می‌توان آن‌ها را مستقیماً و بدون پیشوند \fBbundle exec\fR فراخوانی کرد.

.SS \fBuse <program_name> [<version>]\fR
یک اعزام دستور معنایی با هدف بارگذاری وابستگی‌های خارجی در محیط.

.PP
مثال:

.EX
use_ruby() {
  echo "Ruby $1"
}
use ruby 1.9.3
# output: Ruby 1.9.3
.EE

.SS \fBuse julia <version>\fR
نسخهٔ مشخص‌شدهٔ Julia را بارگذاری می‌کند. باید با استفاده از $JULIA_VERSIONS مسیری را به دایرکتوری حاوی نسخه‌های نصب‌شدهٔ Julia مشخص کنید. می‌توانید به‌صورت اختیاری با استفاده از $JULIA_VERSION_PREFIX پیشوند پوشه‌های درون $JULIA_VERSIONS (پیش‌فرض \fBjulia-\fR) را بازنویسی کنید. اگر تطابق دقیقی برای \fB<version>\fR یافت نشود، جستجویی انجام خواهد شد و آخرین نسخه بارگذاری می‌شود.

.PP
مثال‌ها (.envrc):

.EX
use julia 1.5.1   # loads $JULIA_VERSIONS/julia-1.5.1
use julia 1.5     # loads $JULIA_VERSIONS/julia-1.5.1
use julia master  # loads $JULIA_VERSIONS/julia-master
.EE

.SS \fBuse rbenv\fR
ابزار rbenv را بارگذاری می‌کند که برنامه‌های پوشش‌دهندهٔ ruby را در PATH در دسترس قرار می‌دهد.

.SS \fBuse nix [...]\fR
متغیرهای محیطی را از \fBnix-shell\fR بارگذاری می‌کند\&.

.PP
اگر یک \fBdefault.nix\fR یا \fBshell.nix\fR داشته باشید، به‌طور پیش‌فرض از آن‌ها استفاده خواهد شد، اما همچنین می‌توانید بسته‌ها را مستقیماً مشخص کنید (برای مثال \fBuse nix -p ocaml\fR).

.PP
ببینید: http://nixos.org/nix/manual/#sec-nix-shell

.SS \fBuse flake [<installable>]\fR
محیط ساخت یک derivation را مشابه \fBnix develop\fR بارگذاری می‌کند\&.

.PP
به‌طور پیش‌فرض مشخصه devShell از فایل flake.nix پوشه جاری را بارگذاری می‌کند. یا می‌توانید یک «installable» مانند "nixpkgs#hello" ارسال کنید تا تمام وابستگی‌های ساخت بسته hello از آخرین nixpkgs بارگذاری شود.

.PP
توجه داشته باشید که ویژگی flakes در پشت یک پرچم آزمایشی پنهان شده است که باید خودتان آن را فعال کنید. Flakes هنوز پایدار در نظر گرفته نمی‌شود..SS \fBuse guix [...]\fR
بارگذاری متغیرهای محیطی از \fBguix shell\fR\&.

.PP
هر آرگومان داده‌شده به guix shell ارسال خواهد شد. برای مثال، \fBuse guix hello\fR محیطی شامل بسته hello را برپا می‌کند. برای ایجاد محیطی به همراه وابستگی‌های hello، پرچم \fB--development\fR استفاده می‌شود: \fBuse guix --development hello\fR\&. گزینه‌های دیگر شامل \fB--file\fR هستند که امکان بارگذاری یک محیط از روی فایل را فراهم می‌کند.

.PP
ببینید: https://guix.gnu.org/manual/en/guix.html#Invoking-guix-shell

.SS \fBrvm [...]\fR
در صورت نصب بودن rvm، باید دقیقاً مانند محیط شل عمل کند.

.SS \fBuse node [<version>]\fR:
نسخه مشخص‌شده NodeJS را در محیط بارگذاری می‌کند.

.PP
اگر نسخه ناقصی از NodeJS ارسال شود (مثلاً \fB4.2\fR)، یک تطبیق تقریبی (fuzzy match)
انجام شده و بالاترین نسخه منطبقِ نصب‌شده انتخاب می‌شود.

.PP
اگر هیچ نسخه‌ای ارسال نشود، در صورت وجود فایل‌های '.nvmrc' یا '.node-version'
در دایرکتوری جاری، آن‌ها را بررسی خواهد کرد.

.PP
متغیرهای محیطی:
.IP \(bu 2
$NODE_VERSIONS (الزامی)
به پوشه‌ای اشاره می‌کند که شامل تمام نسخه‌های نصب‌شده Node است. آن
پوشه باید وجود داشته باشد.
.IP \(bu 2
$NODE_VERSION_PREFIX (اختیاری) [پیش‌فرض="node-v"]
پیشوند پیش‌فرض نسخه را بازنویسی می‌کند.

.SS \fBuse vim [<vimrc_file>]\fR
اسکریپت vim مشخص‌شده (یا به‌طور پیش‌فرض .vimrc.local) را به ابتدای
متغیر محیطی \fBDIRENV_EXTRA_VIMRC\fR اضافه می‌کند.

.PP
این متغیر توسط افزونه direnv/direnv.vim شناخته می‌شود. در صورت یافت شدن،
پس از باز کردن فایل‌ها در دایرکتوری، آن را سورس (source) می‌کند.

.SS \fBwatch_file <path> [<path> ...]\fR
هر فایل را به فهرست نظارت (watch-list) direnv اضافه می‌کند. اگر فایل تغییر کند، direnv در اعلان (prompt) بعدی، محیط را بازخوانی خواهد کرد.

.PP
مثال (.envrc):

.EX
watch_file Gemfile
.EE

.SS \fBdirenv_version <version_at_least>\fR
بررسی می‌کند که نسخه direnv حداقل به اندازه \fBversion_at_least\fR جدید باشد. این
می‌تواند هنگام به‌اشتراک‌گذاری یک \fB\&.envrc\fR و برای اطمینان از به‌روز بودن کاربران مفید
باشد.

.SS \fBstrict_env [<command> ...]\fR
حالت سخت‌گیرانه اجرای شل را فعال می‌کند. این کار زمینه ارزیابی .envrc
را وادار می‌کند در موارد زیر بلافاصله خارج شود:
.IP \(bu 2
هر دستوری در یک خط لوله وضعیتی غیر از صفر برگرداند که به‌گونه‌ای دیگر
به‌عنوان بخشی از آزمون‌های \fBif\fR، \fBwhile\fR یا \fBuntil\fR، نقیض مقدار بازگشتی
(\fB!\fR) یا بخشی از یک زنجیره بولی (\fB&&\fR یا \fB||\fR) مدیریت نشده باشد.
.IP \(bu 2
به هر متغیری که به‌صراحت مقداردهی یا اعلان نشده است (خواه با
\fBdeclare\fR یا \fBlocal\fR) ارجاع داده شود.

.PP
اگر یک خط فرمان به دنبال آن بیاید، سخت‌گیری فقط برای طول مدت اجرای آن
دستور اعمال می‌شود.

.PP
مثال (کل اسکریپت):

.EX
strict_env
has curl
.EE

.PP
مثال (دستور):

.EX
strict_env has curl
.EE.SS \fBunstrict_env [<command> ...]\fR
سخت‌گیری اجرای پوسته را غیرفعال می‌کند. اگر به دنبال آن یک خط فرمان بیاید، این وضعیت برای مدت‌زمان اجرای همان دستور اعمال می‌شود.

.PP
مثال (کل اسکریپت):

.EX
unstrict_env
has curl
.EE

.PP
مثال (دستور):

.EX
unstrict_env has curl
.EE

.SS \fBon_git_branch [<branch_name>]\fR
اگر درون یک مخزن git با \fBbranch_name\fR داده‌شده باشید، مقدار 0 را برمی‌گرداند. اگر نام شاخه‌ای تعیین نشده باشد، در صورت قرار داشتن در \fIهر\fP شاخه‌ای مقدار 0 بازگردانده می‌شود. نیازمند نصب بودن دستور git است. در غیر این صورت مقدار 1 را برمی‌گرداند.

.PP
هنگامی که یک شاخه مشخص شده باشد، \fB\&.git/HEAD\fR رصد می‌شود تا ورود به شاخه یا خروج از آن موجب بارگذاری مجدد شود.

.PP
مثال (.envrc):

.EX
if on_git_branch child_changes; then
  export MERGE_BASE_BRANCH=parent_changes
fi

if on_git_branch; then
  echo "Thanks for contributing to a GitHub project!"
fi
.EE

.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
مجوز MIT \- کپی‌رایت (C) 2019 @zimbatm و مشارکت‌کنندگان

.SH "همچنین ببینید (SEE ALSO)"
direnv(1), direnv.toml(1)