Popularity
2.1
Growing
Activity
0.4
Declining
70
6
14

Description

JSON is easy for humans to read and write... in theory. In practice JSON gives us plenty of opportunities to make mistakes without even realizing it.

Hjson is a syntax extension to JSON. It's NOT a proposal to replace JSON or to incorporate it into the JSON spec itself. It's intended to be used like a user interface for humans, to read and edit before passing the JSON data to the machine.

Code Quality Rank: L3
Programming language: PHP
License: MIT License
Tags: Serializer     Parser     Data     Config     JSON     Serialization     Human     Comments     Hjson    
Latest version: v2.1.0
Add another 'Serialization' Library

README

hjson-php

Build Status Packagist

Hjson, the Human JSON. A configuration file format for humans. Relaxed syntax, fewer mistakes, more comments.

Hjson Intro

{
  # specify rate in requests/second (because comments are helpful!)
  rate: 1000

  // prefer c-style comments?
  /* feeling old fashioned? */

  # did you notice that rate doesn't need quotes?
  hey: look ma, no quotes for strings either!

  # best of all
  notice: []
  anything: ?

  # yes, commas are optional!
}

The PHP implementation of Hjson is based on hjson-js. For other platforms see hjson.github.io.

Install from composer

composer require laktak/hjson

Usage

use HJSON\HJSONParser;
use HJSON\HJSONStringifier;

$parser = new HJSONParser();
$obj = $parser->parse(hjsonText);

$stringifier = new HJSONStringifier;
$text = $stringifier->stringify($obj);

API

HJSONParser: parse($text, $options)

This method parses JSON or Hjson text to produce an object or array.

  • text: the string to parse as JSON or Hjson
  • options: array
    • keepWsc: boolean, keep white space and comments. This is useful if you want to edit an hjson file and save it while preserving comments (default false)
    • assoc: boolean, return associative array instead of object (default false)

HJSONStringifier: stringify($value, $options)

This method produces Hjson text from a value.

  • value: any value, usually an object or array.
  • options: array
    • keepWsc: boolean, keep white space. See parse.
    • bracesSameLine: boolean, makes braces appear on the same line as the key name. Default false.
    • quotes: string, controls how strings are displayed.
    • "min": no quotes whenever possible (default)
    • "always": always use quotes
    • space: specifies the indentation of nested structures. If it is a number, it will specify the number of spaces to indent at each level. If it is a string (such as '\t' or ' '), it contains the characters used to indent at each level.
    • eol: specifies the EOL sequence

modify & keep comments

You can modify a Hjson file and keep the whitespace & comments intact. This is useful if an app updates its config file.

$parser = new HJSONParser;
$stringifier = new HJSONStringifier;

$text = "{
  # specify rate in requests/second (because comments are helpful!)
  rate: 1000

  // prefer c-style comments?
  /* feeling old fashioned? */

  # did you notice that rate doesn't need quotes?
  hey: look ma, no quotes for strings either!

  # best of all
  notice: []
  anything: ?

  # yes, commas are optional!

  array: [
    // hello
    0
    1
    2
  ]
}";

// Parse, keep whitespace and comments
$data = $parser->parseWsc($text);

// Modify like you normally would
$data->rate = 500;

// You can also edit comments by accessing __WSC__
$wsc1 = &$data->__WSC__; // for objects
$wsc2 = &$data->array['__WSC__']; // for arrays

// __WSC__ for objects contains { c: {}, o: [] }
// - c with the actual comment and, firts comment is key ' '
// - o (array) with the order of the members
$emptyKey = " ";
$wsc1->c->$emptyKey = "\n  # This is the first comment";
$wsc1->c->rate = "\n  # This is the comment after rate";

// Sort comments order just because we can
sort($wsc1->o);

// Edit array comments
$wsc2[0] .= ' world';

// convert back to Hjson
$text2 = $stringifier->stringifyWsc($data);

History

see releases