JSONにコメントが書けるJSONを拡張したフォーマット、「hjson」の紹介です。
データの受け渡し 〜 設定ファイルまで言語間を超えて様々なシーンで使われるJSONフォーマットですが、設定ファイルとして使う場合 データ数( 配列 or オブジェクト)が多くなると管理が難しくなってきます。
「設定ファイルではJSONじゃなくてXML代替のYAML使えば？」っという意見も出てきそうですが、node.js関連のパッケージ等はJSON一択です。（ * RailsやSymfony等のフレームワークはYAMLが使われています ）
そもそもJSON ( JavaScript Object Notation ) はjavascriptのオブジェクトなのでYAMLの様にコード内にコメントを書くことは想定されていません。
そんなフォーマットの縛りが強いjsonを使いやすくする新しいフォーマットが「hjson」 (Human JSON)です。
hjsonで記述すると下記のスニペットのようにコメントを添えることが出来るようになります。
# HJSON の場合
{
"name": "hjson sample" // comment
"version": "1.0.0" # initial
/*
複数にわたるコメントの場合
*/
"description":
'''
this is not json format.
you can see how difference obviously, can't you?
'''
"main": "app.js" // main js file
"scripts": {
/* server run command */
"server": "npm run"
}
}
# JSONの場合
{
"name": "json sample",
"version": "1.0.0",
"description": "this is json format.
you can see how difference obviously, can't you?",
"main": "app.js",
"scripts": {
"server": "npm run",
"convertBower": "hjson -h bower.hjson < bower.json"
}
}
冒頭でも少し触れましたがhjsonではjsonにコメントが添えられるようになります。そして、拡張子は「.hjson」に変わります。
{
// コメント
# コメント
/* 複数行コメント */
"name1" : "name-val1"
}
オブジェクト間を繋ぐカンマ " , "も省略出来るようになります。
{
// ' , ' はいりません
"name2" : "name-val2"
"name3" : "name-val3"
}
keyをラップするダブルクォーテーションも省略出来るようになります。( *どちらでも可 )
{
"name4" : "name-val4" // before
name5 : "name-val5" // after
}
value内で改行を挟む時、\nの変わりにシングルクォーテーションで3つで囲むと改行も出来ます。
( * ヒアドキュメントのように扱えるようになります )
// before * json
{
"description": " ヒアドキュメントのように\n 自由なことが\n 出来ます"
}
// after * hjson
{
description:
'''
ヒアドキュメントのように
自由なことが
出来ます
'''
}
基本的な記述方法は以上です。
hjsonはライブラリを導入することで、 コマンドライン上でhjson -> jsonに変換することができます。
(下はnode.jsのnpmパッケージですが、Pythonのpip形式、windows用のchocolatelyのライブラリでも提供されています )
npm install hjson -g # hjson ライブラリインストール
# hjson -> jsonへの変換コマンド
hjson -h basefile.hjson > output.json
# hjsonのフォーマットチェック
# 記述ミスがあるとエラーを表示してくれます
hjson basefile.json
bowerを使ってjsやcssのライブラリを管理している場合、どのライブラリがどんな役割をしているのか細かいコメントが書けると便利ですよね! ... っということで、bower.jsonをhjsonで書いて、jsonファイルに変換してみました。
// bower.hjson
{
// bower.jsonを hjsonに書き換えた例
name: "public"
# コメント例: ファイルが増えたらバージョンを上げる
version: "0.0.1"
description:
'''
専用のnode.jsライブラリを導入するとコマンドライン上で
hjson -j fileName.hjson > filename.json
でjsonファイルに変換出来ます。
'''
dependencies: {
/*
デザイン系のライブラリ
*/
hint.css: "latest" # tool tip library
sweetalert: "latest" # alert library
fontawesome: "latest"
fullcalendar: "latest" # colendar library
fullpage.js: "latest" # colendar library
holderjs: "latest"
clockpicker: "latest" # clock library, but depends on bootstrap
highlightjs: "latest" # sourcecode syntax high-light library
jquery.lazyload: "latest" # img load library
/**
Bootstrap dependencies
*/
bootstrap: "latest"
bootbox: "latest" # bootstrap modal library
bootstrap-colorpicker: "latest"
/*
Framework and util
*/
jquery: "latest"
backbone: "latest"
moment: "latest" # date-time handling libarry
lodash: "latest"
jquery-pjax: "latest"
react: "latest"
/*
グラフ関連
*/
d3: "latest"
c3: "latest" # d3 wrapper
}
}
* " hjson -j bower.hjson > bower.json " でJSONに変換されたファイル
{
"name": "public",
"version": "0.0.1",
"description": " 専用のnode.jsライブラリを導入するとコマンドライン上で\n hjson -j fileName.hjson > filename.json\n でjsonファイルに変換出来ます。",
"dependencies": {
"hint.css": "latest",
"sweetalert": "latest",
"fontawesome": "latest",
"fullcalendar": "latest",
"fullpage.js": "latest",
"holderjs": "latest",
"clockpicker": "latest",
"highlightjs": "latest",
"jquery.lazyload": "latest",
"bootstrap": "latest",
"bootbox": "latest",
"bootstrap-colorpicker": "latest",
"jquery": "latest",
"backbone": "latest",
"moment": "latest",
"lodash": "latest",
"jquery-pjax": "latest",
"react": "latest",
"d3": "latest",
"c3": "latest"
}
}
以上がhjsonの紹介でした。
また、jsonに変換せず、そのままhjsonをネイティブにパースするライブラリも公開されています。
- プログラミング言語
Javascript / Node.js / Java / Python / Ruby / C#.net /C / Go
- Build tool
Gulp / Grunt / hjsonify (browserify用) / ... etc
- テキストエディタのシンタックスハイライト プラグイン
ATOM / Sublime Text / Text Mate / Notepad ++
リンク: jhsonのツールやライブラリがまとめられているページ
今回はbower.jsonを元に紹介しましたが、jsonファイルにコメントが欲しいシーンは沢山あるので、気になった方は是非×2チェックしてみてください！
hjson.org
