.\" man 7 groff_mdoc  Best resource ever
.Dd September 1, 2013
.Dt JSHON \&1 "Jshon Manual"
.Os " "
.Sh "نام (NAME)"
.Nm jshon
.Nd تجزیه‌کننده JSON برای شل
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm jshon
-[P|S|Q|V|C|I|0] [-F path] -[t|l|k|u|p|a|j] -[s|n] value -[e|i|d] index
.Sh "توضیحات (DESCRIPTION)"
.Nm
داده‌های JSON را تجزیه کرده، می‌خواند و ایجاد می‌کند. این ابزار به گونه‌ای طراحی شده است که تا جای ممکن در محیط شل قابل استفاده باشد و جایگزین تجزیه‌کننده‌های شکننده و موقتی ساخته‌شده با grep/sed/awk و همچنین تک‌خطی‌های سنگین نوشته‌شده با perl/python شود.
.Pp
.Nm
متن json را از stdin بارگیری می‌کند، اقدامات را انجام می‌دهد و سپس نتیجهٔ آخرین اقدام را در stdout نمایش می‌دهد. برخی از گزینه‌ها خروجی json تولید می‌کنند، در حالی که برخی دیگر خلاصه‌های متنی ساده ارائه می‌دهند. از آنجا که Bash ساختارهای دادهٔ تودرتوی بسیار ضعیفی دارد،
.Nm
مانند یک کتابخانهٔ معمولی، JSON را به عنوان یک شیء بومی بازنمی‌گرداند. در عوض،
.Nm
تاریخچه‌ای از ویرایش‌ها را در یک پشته (stack) نگه می‌دارد و شما بالاترین عنصر JSON را دستکاری می‌کنید.
.
.Sh "عملیات‌ها (ACTIONS)"
هر اقدام به شکل یک گزینهٔ کوتاه است. برخی از آن‌ها به آرگومان نیاز دارند. در حالی که نمونه‌های متعددی از 
.Nm
می‌توانند با لوله (pipe) به یکدیگر متصل شوند، اقدامات باید به صورت متوالی زنجیره‌ای شوند تا تعداد فراخوانی‌ها کاهش یابد. تمام مثال‌ها از این نمونه json استفاده می‌کنند:
.Pp
\&  {"a":1,"b":[true,false,null,"str"],"c":{"d":4,"e":5}}
.br
\&  jshon [actions] < sample.json
.Pp
بیشتر استفاده‌های رایجِ فقط‌خواندنی تنها به چندین اقدام
.Nm \-e 
و یک اقدام
.Nm \-a
در میان آن‌ها نیاز خواهند داشت.
.Pp
.Bl -tag -width ".." -compact
.It Cm -t
(نوع / type) یکی از مقادیر string، object، array، number، bool یا null را بازمی‌گرداند.
.Pp
\&  jshon -t -> object
.Pp
.It Cm -l
(طول / length) یک عدد صحیح بازمی‌گرداند. فقط روی string، object و array کار می‌کند.
.Pp
\&  jshon -l -> 3
.Pp
.It Cm -k
(کلیدها / keys) فهرستی از کلیدها را که با خط جدید از هم جدا شده‌اند بازمی‌گرداند. فقط روی object کار می‌کند.
.Pp
\&  jshon -k -> a b c
.Pp
.It Cm -e index
(استخراج / extract) مقدار json در "index" مورد نظر را بازمی‌گرداند. فقط روی object و array کار می‌کند. اندیس یک آرایه یک عدد صحیح است.
.Pp
\&  jshon -e c -> {"d":4,"e":5}
.Pp
.It Cm -a
(سرتاسری / across) اقدامات باقی‌مانده را روی تمام عناصرِ عنصر انتخاب‌شده نگاشت می‌کند. فقط روی objectها و arrayها کار می‌کند. فراخوانی‌های متعدد
.Nm \-a
می‌توانند به صورت تودرتو باشند، هرچند نیاز به این کار در عمل نادر است.
.Pp
\&  jshon -e b -a -t -> bool bool null string
.Pp
.It Cm -s value
(رشته / string) یک رشتهٔ کدگذاری‌شده به صورت json بازمی‌گرداند. بعداً می‌تواند در یک ساختار موجود درج (-i) شود.
.Pp
\&  jshon -s "back\[rs]slash" -> "back\[rs]\[rs]slash"
.Pp
.It Cm -n value
(غیررشته/عدد / nonstring/number) یک عنصر json بازمی‌گرداند. بعداً می‌تواند در یک ساختار موجود درج (-i) شود. مقادیر معتبر عبارتند از 'true'، 'false'، 'null'، 'array'، 'object'، اعداد صحیح و ممیز شناور. اختصارات t، f، n، [] و {} نیز به ترتیب کار می‌کنند.
.Pp
\&  jshon -n object -> {}
.Pp
.It Cm -u
(رشته‌زدایی / unstring) یک رشتهٔ رمزگشایی‌شده بازمی‌گرداند. فقط روی انواع ساده کار می‌کند: string، int، real، boolean، null.
.Pp
\&  jshon -e b -e 3 -u -> str
.Pp
.It Cm -j
(لفظی json / json literal) خروجی json کدگذاری‌شده بازمی‌گرداند. روی تمام انواع کار می‌کند، هرچند برای string، array و object بیشترین کاربرد را دارد.
.Pp
.It Cm -p
(برداشتن از پشته / pop) آخرین دستکاری را از پشته برمی‌دارد و تاریخچه را به عقب بازمی‌گرداند. برای استخراج چندین مقدار از یک شیء مفید است.
.Pp
\& jshon -e c -e d -u -p -e e -u -> 4 5
.Pp
.It Cm -d index
(حذف / delete) یک مورد را در یک آرایه یا شیء حذف می‌کند. اندیس‌های منفی آرایه از انتها دور می‌زنند.
.Pp
\&  jshon -d b -> {"a":1,"c":{"d":4,"e":5}}
.Pp
.It Cm -i index
(درج / insert) پیچیده است. معکوس extract است. اقدام extract یک زیرعنصر json را روی پشته قرار می‌دهد. اقدام insert یک زیرعنصر را از پشته برمی‌دارد و آن بخش از json را در آرایه/شیء بزرگ‌تر زیرین درج می‌کند. از extract برای ورود به عمق درخت json، از delete/string/nonstring برای اعمال تغییرات و از insert برای بازگرداندن تغییرات به داخل درخت استفاده کنید.
.Pp
\&  jshon -e a -i a -> the orginal json
.br
\&  jshon -s one -i a -> {"a":"one", ...}
.Pp
با آرایه‌ها به روش خاصی رفتار می‌شود. ارسال اعداد صحیح، یک مقدار را بدون رونویسی (overwrite) درج می‌کند. اعداد صحیح منفی و همچنین رشتهٔ 'append' قابل قبول هستند. برای بازنویسی یک مقدار در یک آرایه: اندیس را حذف (delete) کنید، مقدار جدید را با
.Nm \-n/s
ایجاد کنید و سپس در آن اندیس درج نمایید.
.Pp
\&  jshon -e b -d 0 -s q -i 0 -> {"b":"q",false,null,"str"}
.
.Pp
.Sh "گزینه‌های غیردستکاری (NON-MANIPULATION)"
چندین گزینهٔ متا وجود دارند که مستقیماً json را ویرایش نمی‌کنند. این گزینه‌ها را در هر بار فراخوانی حداکثر یک بار استفاده کنید.
.Pp
.Bl -tag -width ".." -compact
.It Cm -F <path>
(فایل / file) به جای stdin، از یک فایل می‌خواند. این تنها گزینهٔ غیردستکاری است که آرگومان می‌گیرد.
.Pp
.It Cm -P
(jsonp) پیش از ادامهٔ عادی کار، کال‌بک jsonp را حذف می‌کند.
.Pp
.It Cm -S
(مرتب‌سازی / sort) به جای ترتیب اصلی، دادهٔ json را مرتب‌شده بر اساس کلید بازمی‌گرداند.
.Pp
.It Cm -Q
(بی‌صدا / quiet) گزارش خطا در stderr را غیرفعال می‌کند، تا مجبور نباشید در سراسر اسکریپت خود از "2> /dev/null" استفاده کنید.
.Pp
.It Cm -V
(با مقدار / by-value) ارسال با مقدار (pass-by-value) را روی پشتهٔ تاریخچهٔ ویرایش فعال می‌کند. در موارد حاد با هزاران مقدار به شدت تودرتو، این کار ممکن است منجر به این شود که
.Nm
چندین برابر کندتر اجرا شده و چندین برابر حافظهٔ بیشتری مصرف کند. با این حال by-value ایمن‌تر از by-reference است و معمولاً رفتار غیرمنتظرهٔ کمتری ایجاد می‌کند. به طور پیش‌فرض by-reference فعال است زیرا در طول عملیات فقط‌خواندنی هیچ خطری ندارد و عموماً ویرایش json را راحت‌تر می‌سازد.
.Pp
\& jshon    -e c -n 7 -i d -p   -> c["d"] == 7
.br
\& jshon -V -e c -n 7 -i d -p   -> c["d"] == 5
.br
\& jshon -V -e c -n 7 -i d -i c -> c["d"] == 7
.Pp
با
.Nm \-V
، تغییرات باید به صورت دستی دوباره در طول پشته درج شوند، به جای اینکه صرفاً مقادیر میانی از پشته برداشته (pop) شوند.
.Pp
.It Cm -C
(ادامه / continue) در صورت بروز خطاهای بالقوه قابل جبران ادامه می‌دهد. برای مثال، استخراج مقادیری که وجود ندارند، به جای لغو اجرا، مقدار 'null' را به پشتهٔ ویرایش اضافه می‌کند. این رفتار ممکن است در آینده تغییر کند.
.Pp
.It Cm -I
(درجا / in-place) ویرایش درجا در فایل. نیازمند یک فایل برای تغییر است و بنابراین فقط با -F کار می‌کند. این گزینه برای اعمال تغییرات جزئی در یک فایل json در نظر گرفته شده است. هنگام استفاده، خروجی عادی غیرفعال شده و پایین‌ترین عنصر پشتهٔ ویرایش در فایل نوشته می‌شود.
.Pp
.It Cm -0
(جداکننده‌های تهی / null delimiters) جداکنندهٔ -u را از خط جدید به یک نویسهٔ null تغییر می‌دهد. این گزینه تنها بر -u اثر می‌گذارد زیرا فقط در این حالت ممکن است یک خط جدید به طور مجاز در خروجی ظاهر شود.
.Pp
.It Cm --version
یک برچسب زمانی به صورت YYYYMMDD را بازمی‌گرداند و خارج می‌شود.
.
.Pp
.Sh "ابزارهای دیگر (OTHER TOOLS)"
.Nm
همیشه در هر خط یک فیلد خروجی می‌دهد. بسیاری از ابزارهای یونیکس انتظار چندین فیلد با جداکنندهٔ تب (tab) در هر خط را دارند. برای رفع این مشکل، خروجی را از طریق لوله به 'paste' بفرستید. با این حال، paste نمی‌تواند خطوط خالی را مدیریت کند، بنابراین آن‌ها را با یک جای‌نگه‌دار پر کنید. در اینجا یک مثال آورده شده است:
.Pp
\&  jshon ... | sed 's/^$/-/' | paste -s -d '\\t\\t\\n'
.Pp
این دستور خطوط خالی را با '-' جایگزین کرده و هر سه خط را در یک خط ادغام می‌کند.
.Pp
ستون‌ها را می‌توان با یک حلقهٔ while نیز استخراج کرد و هم‌زمان به راحتی در متغیرها بارگذاری نمود:
.Pp
\&  while {
.br
\&      read -r var1
.br
\&      read -r var2
.br
\&      read -r var3
.br
\&  }; do [thing with vars]
.br
\&  done < <(jshon ...)
.Pp
اگر از 'read' به همراه -0 استفاده می‌کنید، توجه داشته باشید که read (دستور داخلی bash) از IFS پیروی نمی‌کند. در عوض از این دستور استفاده کنید:
.Pp
\& read -r -d $'\\0' var1
.Pp
روز به روز ابزارهای بیشتری خروجی json تولید می‌کنند. اغلب این ابزارها از یک ترکیب خط‌محورِ json/متن‌ساده استفاده می‌کنند که در آن هر خط یک ساختار مستقل json است. متأسفانه این بدان معناست که خروجی به عنوان یک کل، یک json معتبر نیست. می‌توانید یا با حلقه داده‌ها را خط به خط پیمایش کنید (و
.Nm
را برای هر خط یک بار فراخوانی کنید) یا اینکه آن را به یک آرایهٔ معتبر json تبدیل نمایید. به عنوان مثال:
.Pp
\&  while read line; do jshon <<< "$line"; done < <(journalctl -o json)
.Pp
\&  journalctl -o json | sed -e '1i[' -e '$!s/$/,/' -e '$a]' | jshon
.Pp
.
.Pp
.Sh "کدگلف (GOLF)"
اگر به دستورات تک‌خطی بسیار کوتاه علاقه‌مندید، در صورتی که ابهامی ایجاد نشود می‌توان آرگومان‌ها را فشرده کرد. مثالِ
.Nm \-p(op)
را می‌توان به صورت زیر فشرده (golf) کرد:
.Pp
\& jshon -e c -e d -u -p -e e -u == jshon -ec -ed -upee -u
.Pp
انجام این کار را توصیه نمی‌کنم (فهمیدن دستور را بسیار دشوارتر می‌کند)، اما برخی افراد با وجود پیامدهایش، کدها را فشرده می‌کنند.
.
.Pp
.Sh "نویسندگان (AUTHORS)"
.An -nosplit
.Pp
.Nm
توسط
.An Kyle Keen Aq keenerd@gmail.com 
همراه با وصله‌هایی از
.An Dave Reisner Aq d@falconindy.com ,
.An AndrewF 
(BSD، OSX، jsonp، مرتب‌سازی)،
و 
.An Jean-Marc A
(solaris)
نوشته شده است.
.
.Pp
.Sh "گزارش باگ‌ها (BUGS)"
بسیار زیاد! اعداد اعشاری ممیز شناور ممکن است دقت خود را از دست بدهند. استفاده از آن می‌توانست راحت‌تر باشد. مستندات مختصر است.