JO(1) JO(1)

jo - تولید خروجی JSON از پوسته

jo [-p] [-a] [-B] [-D] [-e] [-n] [-v] [-V] [-d keydelim] [-f file] [–] [ [-s|-n|-b] word ...]

دستور jo بر اساس wordهایی که به عنوان آرگومان دریافت می‌کند یا از stdin می‌خواند، یک رشته JSON در stdout ایجاد می‌کند. اگر -f مشخص شده باشد، jo ابتدا محتویات file را به عنوان یک شیء یا آرایه JSON بارگذاری کرده، سپس آن را با wordهای بعدی پیش از چاپ رشته نهایی JSON در stdout اصلاح می‌کند. می‌توان file را به صورت - مشخص کرد تا از ورودی استاندارد jo خوانده شود؛ این حالت بر خواندن wordها از stdin اولویت دارد.

بدون گزینهٔ -a، این دستور یک شیء تولید می‌کند که در آن هر word یک جفت key=value (یا key@value) است، به‌طوری که key عنصر شیء JSON و value مقدار آن خواهد بود. دستور jo تلاش می‌کند تا نوع value را حدس بزند تا مقادیر عددی (با استفاده از strtod(3))، رشته‌ای یا null را در JSON بسازد.

یک value خالی یا ناموجود معمولاً به عنصری با مقدار null منجر می‌شود. اگر گزینهٔ -n مشخص شود، این عنصر ایجاد نخواهد شد.

دستور jo معمولاً با key به عنوان یک مقدار رشته‌ای لفظی (literal) رفتار می‌کند. اگر گزینهٔ -d مشخص شده باشد، key به عنوان یک مسیر شیء (object path) تفسیر خواهد شد، که مؤلفه‌های مجزای آن با اولین نویسهٔ keydelim از یکدیگر جدا می‌شوند.

دستور jo معمولاً با value به عنوان یک مقدار رشته‌ای لفظی رفتار می‌کند، مگر اینکه با یکی از نویسه‌های زیر آغاز شود:

مقدار (value) عملکرد (action)
@file محتوای file را عیناً جایگزین می‌کند
%file محتوای file را به شکل کدگذاری‌شده با base64 جایگزین می‌کند
:file محتوای file را به عنوان JSON تفسیر کرده و نتیجه را جایگزین می‌کند

برای جلوگیری از این تفسیر، نویسهٔ ویژه را با یک بک‌اسلش نادیده‌سازی (escape) کنید.

دستور jo با عبارت key@value به‌طور ویژه به عنوان عناصر بولی (boolean) در JSON رفتار می‌کند: اگر مقدار با T، t آغاز شود، یا مقدار عددی آن بزرگ‌تر از صفر باشد، خروجی true است، وگرنه false خواهد بود.

هنگامی که گزینهٔ -a مشخص شود، jo به جای شیء، یک آرایه ایجاد می‌کند.

هنگامی که از عملگر := در یک word استفاده می‌شود، نامِ سمت راستِ := فایلی حاوی JSON است که تجزیه شده و به کلید سمت چپ عملگر تخصیص داده می‌شود. فایل می‌تواند به صورت - تعیین شود تا از ورودی استاندارد jo خوانده شود..SH "تبدیل نوع (TYPE COERCION)"

حدس‌های نوعِ jo را می‌توان به ازای هر word با پیشوند کردن -s برای string (رشته)، -n برای number (عدد)، یا -b برای boolean (بولی) بازنویسی کرد. پیش از فهرست wordها باید پیشوند -- قرار گیرد تا به jo نشان داده شود که گزینهٔ سراسری دیگری وجود ندارد.

تبدیل نوع به صورت زیر عمل می‌کند:

word -s -n -b پیش‌فرض
a= “a”:"" “a”:0 “a”:false “a”:null
a=string “a”:“string” “a”:6 “a”:true “a”:“string”
a="quoted" “a”:“"quoted"” “a”:8 “a”:true “a”:“"quoted"”
a=12345 “a”:“12345” “a”:12345 “a”:true “a”:12345
a=true “a”:“true” “a”:1 “a”:true “a”:true
a=false “a”:“false” “a”:0 “a”:false “a”:false
a=null “a”:"" “a”:0 “a”:false “a”:null

تبدیل یک رشتهٔ غیرعددی به عدد، طول رشته را در خروجی تولید می‌کند.

تبدیل یک رشتهٔ غیربولی به بولی، در صورت خالی بودن رشته مقدار false و در غیر این صورت true را در خروجی تولید می‌کند.

تبدیل نوع فقط برای wordهای key=value و wordهای مجزا در یک آرایهٔ -a اعمال می‌شود. تبدیل نوع سایر wordها هیچ اثری ندارد..SH "مثال‌ها (EXAMPLES)"

ایجاد یک شیء. توجه کنید که چگونه مقدار ممیز شناور با قالب‌بندی نادرست به یک رشته تبدیل می‌شود:

$ jo tst=1457081292 lat=12.3456 cc=FR badfloat=3.14159.26 name="JP Mens" nada= coffee@T
{"tst":1457081292,"lat":12.3456,"cc":"FR","badfloat":"3.14159.26","name":"JP Mens","nada":null,"coffee":true}

چاپ مرتب و خوانا (pretty-print) یک آرایه با فهرستی از فایل‌های دایرکتوری جاری:

$ jo -p -a *
[
 "Makefile",
 "README.md",
 "jo.1",
 "jo.c",
 "jo.pandoc",
 "json.c",
 "json.h"
]

ایجاد اشیاء درون اشیاء؛ این قابلیت به این دلیل کار می‌کند که اگر نویسه اول مقدار یک آکولاد باز یا یک براکت باشد، تلاش می‌شود باقی‌مانده آن به عنوان JSON تفسیر و رمزگشایی شود. مراقب فاصله‌ها در رشته‌ها باشید ...

$ jo -p name=JP object=$(jo fruit=Orange hungry@0 point=$(jo x=10 y=20 list=$(jo -a 1 2 3 4 5)) number=17) sunday@0
{
 "name": "JP",
 "object": {
  "fruit": "Orange",
  "hungry": false,
  "point": {
   "x": 10,
   "y": 20,
   "list": [
    1,
    2,
    3,
    4,
    5
   ]
  },
  "number": 17
 },
 "sunday": false
}

مقادیر بولی به عنوان رشته یا به صورت بولی (به switch توجه ویژه داشته باشید؛ گزینه -B تشخیص پیش‌فرض رشته‌های “true”، “false” و “null” را غیرفعال می‌کند):

$ jo switch=true morning@0
{"switch":true,"morning":false}
$ jo -B switch=true morning@0
{"switch":"true","morning":false}

عناصر (اشیاء و آرایه‌ها) می‌توانند به صورت تو در تو قرار گیرند. مثال زیر یک آرایه با نام point و یک شیء با نام geo را تو در تو قرار می‌دهد:

$ jo -p name=Jane point[]=1 point[]=2 geo[lat]=10 geo[lon]=20
{
   "name": "Jane",
   "point": [
      1,
      2
   ],
   "geo": {
      "lat": 10,
      "lon": 20
   }
}

همان مثال، با استفاده از مسیرهای شیء (object paths):

$ jo -p -d. name=Jane point[]=1 point[]=2 geo.lat=10 geo.lon=20
{
   "name": "Jane",
   "point": [
      1,
      2
   ],
   "geo": {
      "lat": 10,
      "lon": 20
   }
}

بدون -d، شیء متفاوتی تولید می‌شود:

$ jo -p name=Jane point[]=1 point[]=2 geo.lat=10 geo.lon=20
{
   "name": "Jane",
   "point": [
      1,
      2
   ],
   "geo.lat": 10,
   "geo.lon": 20
}

ایجاد اشیاء یا آرایه‌های خالی، به صورت عمدی یا احتمالی:

$ jo < /dev/null
{}
$ MY_ARRAY=(a=1 b=2)
$ jo -a "${MY_ARRAY[@]}" < /dev/null
["a=1","b=2"]

تبدیل اجباری نوع (Type coercion):

$ jo -p -- -s a=true b=true -s c=123 d=123 -b e="1" -b f="true" -n g="This is a test" -b h="This is a test"
{
   "a": "true",
   "b": true,
   "c": "123",
   "d": 123,
   "e": true,
   "f": true,
   "g": 14,
   "h": true
}
$ jo -a -- -s 123 -n "This is a test" -b C_Rocks 456
["123",14,true,456]

خواندن مقادیر عناصر از فایل‌ها: مقداری که با @ آغاز شود به صورت متن خام خوانده می‌شود، در حالی که اگر با یک % شروع شود، به شکل base64 کُدگذاری خواهد شد و اگر با : آغاز گردد محتویات آن به عنوان JSON تفسیر می‌شود:

$ jo program=jo authors=@AUTHORS
{"program":"jo","authors":"Jan-Piet Mens <jpmens@gmail.com>"}
$ jo filename=AUTHORS content=%AUTHORS
{"filename":"AUTHORS","content":"SmFuLVBpZXQgTWVucyA8anBtZW5zQGdtYWlsLmNvbT4K"}
$ jo nested=:nested.json
{"nested":{"field1":123,"field2":"abc"}}
برای جلوگیری از تفسیر شدن، می‌توان این نویسه‌ها را گریزدهی (escape) کرد:
$ jo name="JP Mens" twitter='\@jpmens'
{"name":"JP Mens","twitter":"@jpmens"}
$ jo char=" " URIescape=\\%20
{"char":" ","URIescape":"%20"}
$ jo action="split window" vimcmd="\:split"
{"action":"split window","vimcmd":":split"}

خواندن مقادیر عناصر از یک فایل به‌منظور غلبه بر محدودیت‌های ARG_MAX هنگام انتساب شیء:

$ ls | jo -a > child.json
$ jo files:=child.json
{"files":["AUTHORS","COPYING","ChangeLog" ....
$ ls *.c | jo -a > source.json; ls *.h | jo -a > headers.json
$ jo -a :source.json :headers.json
[["base64.c","jo.c","json.c"],["base64.h","json.h"]]

افزودن عناصر به JSON موجود:

$ jo -f source.json 1 | jo -f - 2 3
["base64.c","jo.c","json.c",1,2,3]
$ curl -s 'https://noembed.com/embed?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ' | jo -f - status=Rickrolled
{ ...., "type":"video","author_url":"https://www.youtube.com/user/RickAstleyVEVO","status":"Rickrolled"}

حذف کلیدهای تکراری شیء (jo به‌طور پیش‌فرض کلیدهای تکراری شیء را ضمیمه می‌کند):

$ jo a=1 b=2 a=3
{"a":1,"b":2,"a":3}
$ jo -D a=1 b=2 a=3
{"a":3,"b":2}

دستور jo گزینه‌های سراسری زیر را می‌شناسد.

فهرست words را به‌صورت مقادیر آرایه تفسیر می‌کند و به‌جای یک شیء، یک آرایه تولید می‌کند.
به‌طور پیش‌فرض، jo رشته‌های “true” و “false” را به‌ترتیب به‌عنوان عناصر بولی true و false، و “null” را به‌صورت null تفسیر می‌کند. با این گزینه، این رفتار را غیرفعال کنید.
حذف کلیدهای تکراری شیء.
نادیده گرفتن stdin خالی (یعنی زمانی که stdin خالی است، خطای تشخیصی صادر نشود).
کلیدهای دارای مقادیر خالی اضافه نشوند.
قالب‌بندی زیبا و خوانا (Pretty-print) رشتهٔ JSON در خروجی به‌جای خروجی مختصر یک‌خطی که به‌طور پیش‌فرض چاپ می‌شود.
نمایش نسخه و خروج.
نمایش نسخه در قالب یک شیء JSON و خروج..SH "گزارش باگ‌ها (BUGS)"

احتمالاً وجود دارند.

اگر مقداری که به jo داده می‌شود در شل به یک مقدار خالی بسط یابد، آن‌گاه jo در حالت شیء مقدار null تولید می‌کند، و ممکن است به نظر برسد در حالت آرایه معلق شده است؛ برنامه معلق نشده، بلکه در حال خواندن از stdin است. این یک باگ نیست.

مقادیر عددی به عدد تبدیل می‌شوند که می‌تواند نتایج ناخواسته‌ای به همراه داشته باشد. اگر یک مقدار عددی را درون نقل‌قول قرار دهید، jo آن را به یک رشته تبدیل می‌کند. موارد زیر را مقایسه کنید:

$ jo a=1.0
{"a":1}
$ jo a=\"1.0\"
{"a":"1.0"}

از قلم انداختن براکت پایانی در یک عنصر تو‌در‌تو باعث چاپ یک پیام تشخیصی می‌شود، اما خروجی در هر صورت حاوی داده‌های نامعتبر خواهد بود. این رفتار عمداً به این شکل طراحی شده است.

برنامهٔ jo در صورت موفقیت با کد 0 و در صورت شکست، پس از مشخص کردن دلیل بروز خطا، با مقداری غیر صفر خارج می‌شود.

http://github.com/jpmens/jo

•
این برنامه از json.[ch]، اثر Joseph A. Adams استفاده می‌کند.

•
https://stedolan.github.io/jq
•
https://github.com/micha/jsawk
•
https://github.com/jtopjian/jsed
•
strtod(3)

Jan-Piet Mens http://jpmens.net

User Manuals