jsoncomma v0.1.4

jsoncomma is a simple utility which manages the commas in your JSON-like files. It adds needed ones, and removes the others.

jsoncomma runs as a standalone program (written in Go), so it's completely independent of your editor. It's extremely simple to integrate, and there are some already existing solution that you can "plug and play".

It's bloody fast. Almost as fast as simple copying. And there is still some room for improvements.

Plugin Developer Reference

If you are struggling, you can have a look at the reference plugin for Sublime Text, or raise an issue, I'd be very happy to help you out :-)

Guidlines

They all emerge from one question: why did the user install this utility? My answer is because he just wants something which fixes up his JSON for him, in the background.

1. Your plugin should fix JSON files on save by default. That's what most user's will want when they install your plugin. However, there should be an option to disable running on save.
2. Follow your editor's style, not jsoncomma's. Although the features exposed should be common across all the different plugins, your plugin should follow your editor's style (menu items, command palette entries, settings, etc).
3. Try to automatically detect JSON files, and if you can't do it perfectly, be configurable.
   • Detect JSON (.json, known file extension, etc)
   • Support custom file extensions
   • We could try to detect if the file is JSON-like based on the payload exclusively, however it's very important to accomplish this a non-significant number of false positives. If you develop such feature, then it should be implemented in the jsoncomma server, not in a specific editor's plugin (as it would be editor independent).

   Make sure you don't have any false positives (ie. trying to fix something that isn't JSON-like)

4. Allow the user to fix any code explicitely. If the user has some text selected, then your plugin should expose a command like jsoncomma: fix commas to fix just the selection. This is useful in cases where the user would be manually writing some JSON in a Python string for example.
5. Allow the user to chose where the executable is. This will probably always be a simple setting. Default should be jsoncomma (search in $PATH). Remember (2), the name of that setting should follow the style of your editor. If you can, try to keep jsoncomma as one word.
6. Ask to automatically install jsoncomma if the executable can't be found. If the user clicks yes, then you need to be 100% that the next time the user will start the editor, everything will work straight away. If you can't guarantee that, then you should only provide explanations about how to install jsoncomma. That means that should set the path setting explicitly (see point above). Don't rely on the user's $PATH variable.

   This is important because there is nothing worse than click "automatically install for me" (ie. you don't know what's happening behind the scenes), and then having it not work. Here are where the you should put the executables on the different platforms (create the folders in case they don't exist):

   Windows:	%APPDATA%\jsoncomma\jsoncomma.exe
   Linux:	~/.config/jsoncomma/jsoncomma
   OS X:	~/Library/Application Support/jsoncomma/jsoncomma

Using the server

In order to save start up cost every time a user saves his file, jsoncomma exposes an optimized web server which your plugin can use very easily.

Your plugin will need to start the server as the editor starts (start a subprocess), and terminate it as soon as the editor closes. Make sure that there is always 1 jsoncomma server running. Two servers running at the same time won't be a problem, but it's just a waste of resources.

$ jsoncomma server
{"addr":"127.0.0.1:36709","host":"127.0.0.1","port":36709}

By default, jsoncomma will choose a port that isn't already used, and serve on localhost.

Parse this JSON (it's guaranteed to be all on the first line), you'll need it to contact the server.

The server is very simple: just send a POST request with the payload you want to fix, and it'll answer with the fixed payload.

So, when a user saves a file, your plugin will need to check whether it is a JSON-like file that could benefit from jsoncomma.

To fix a file, you just send all of the file's content to the server in a POST request, and it will give you back the fixed up payload.

Server Reference

$ jsoncomma server -help
Runs an optimized web server to fix payloads
  -host string
    	Address to bind the server to. 
    	If empty, it binds to every interface. (default "localhost")
  -port int
    	The port to listen on.
    	0 means 'chose random unused one' (default 0)

The server only handles one URL: /. You should only send POST requests on it, with the body content to be just the JSON you want to fix (ie. the file's content). The encoding should always be UTF-8. If any kind of error occurs on the server, only JSON responses will be issued, explaining the reason of the error. Otherwise, a plain text response is given: the uploaded code with fixed up commas.

Here is the entire list of responses jsoncomma server can give.

FIXME: fuzz that web server, and make sure they match the expected pages

• Endpoint: /
  Method: POST
  Status Code: 200
  Content-Type: text/plain; charset=utf-8
  Body:

  <The uploaded code, with commas fixed up>

  The reason the content type isn't application/json; charset=utf-8 is because the response might contain comments for example, making it invalid JSON.

• Endpoint: /
  Method: not POST
  Status Code: 405
  Content-Type: application/json; charset=utf-8
  Body:

  {
      "kind": "method not allowed",
      "current method": <method used>,
      "msg": <details>
  }

• Endpoint: not /
  Status Code: 404
  Content-Type: application/json; charset=utf-8
  Body:

  {
      "kind": "not found",
      "current path": <path used>
      "msg": <details>
  }

That's it. Any other kind of response is an error and should be reported