Overview
================

This is a web API inspector and generic interactive client - it is
kinda like a browser and script interpreter driven by user line input
and displaying technical results instead of rendering HTML. It runs
inside a text console and works on Windows and Linux (and probably
Mac and BSD too).

It can also be used to browse or modify a JSON file interactively,
with some pretty printing.


	TODO:
		* https (will probably need a dependency :-( )
		* maybe non-text replies.
		* see the histroy easier
		* the auto-complete could be better
		* loading an external editor on an item would be nice
		* colors, back button, etc. UI stuff.
		* ctrl+d should exit.
		* request modification function to add other variables
		* send as: json or form-urlencoded
		* xml too?
		* limit output to fit in the inspection window so it
		  doesn't scroll the UI off screen

Screenshot: http://arsdnet.net/inspect.png

Building
=================

Copy this repo to your computer. Fetch script.d, jsvar.d, http2.d,
terminal.d from my other repo: https://github.com/adamdruppe/arsd

And then just compile all files at once with dmd:

$ dmd inspect.d script.d jsvar.d http2.d terminal.d

It should all just work.

The Makefile in here just does that, assuming the folder names I
use on my computer.

Tip: the provided Makefile should also just work (at least on Linux)
if you copy my other repo to a folder called "arsd" in your home
directory.

Using
==================

The command line inside the program interprets a line of a
Javascript-like language. Each line is typically a function
call or variable assignment.

The result of each interpreted line is displayed in the
inspection area of the window. Clicking on various components
will load them up in the command line for easy reference.

Exiting the program:

	Press ctrl+c to exit, or call the exit(); function
	from the script command line.

Loading and saving json files:

	var obj = loadJsonFile("filename.json");
	/* obj will now be displayed in the inspection area */
	/* ... */
	/* do whatever with obj here */
	/* ... */
	saveJsonFile("filename.json", obj);

Browsing a web API:

	var r = get("http://example.com/something");
	/* see the response in r */
	var r = get("another-page"); // relative urls work too


	There's functions for the HTTP methods get, post, delete,
	patch, and put. You can pass arguments to them with the
	second parameter.

	The returned value from the HTTP methods is available in
	a couple forms: if it returned JSON, it is parsed and put
	into r.reply as an object. If not, r.reply contains the
	text of the answer. r.content has an array of binary data
	and r.contentText always has the answer as a string.

Navigating the data:

	You can click on the line of a datum to drill down into it.
	The [<<] button goes back. [>>] goes forward.

	When a piece of data is displayed, the limits are turned
	off. Thus, to see additional items in an object, array,
	or string, simply click on it or evaluate it on the command
	line.

	The displayed data is available as a script variable called
	inspecting.

Customizing the HTTP client:

	The http client is available to the script as the global
	variable httpClient. You can inspect and modify its
	properties just like any other object.

Loading initial data:

	You can pass command line arguments to the inspect program.

	If you pass a http:// url, it will load that site into the
	buffer just as if you manually ran get(that_url);

	If you pass a .json filename, it will load that file into
	the buffer, as if you manually ran loadJsonFile(that_file);

	If you pass a .js filename, it will load and execute that
	file at startup before presenting the command line.

Tip: if you have settings you use a lot, put them in a .js file
and load it in the command line argument list to initialize
your session the way you like it.

Bugs and quirks
==================

Probably a lot, this is my first real use of http2.d and the line getter
is pretty new too. The script engine is kinda sloppy as well.

Among the bugs/quirks you can expect to hit are:

	* the script language requires you to declare variables
	  so remember to use the var keyword if you are setting one.

	* the script parser doesn't like literals at the front of a line.
	  you can just assign them to a variable or use functions.

	* manipulating the inspectionStack from inside the script is
	  possible, but those commands go on it too, so you probably won't
	  get what you expect.

	* My script language does NOT support json literals like in Javascript.
	  Instead of { members }, it uses json!q{ members }. Since this is a
	  pain to type, I set up a hotkey to insert it automatically: ctrl+x.

Code commentary
==================

It is a practical example of using terminal.d, http2.d, and script.d
from my arsd repo to make an interactive, scriptable program with web
support. It has no dependencies outside of my code and works cross-platform.

While writing this, even I was amazed with how cool D can be. I wrote:

	globals["get"] = delegate var(string path) {
		auto request = client.navigateTo(Uri(path));
		request.send();
		return var(request.waitForCompletion());
	};

to add the HTTP support.... and it just worked in the script engine. The
HTTP response was correctly assimilated automatically. I was honestly
expecting at least some pushback, but it all worked.

script.d has got to be one of the easiest embeddable scripting engines out
there!

About
==============

I (Adam D. Ruppe) started writing this on December 22, 2014. If you
have questions or comments about it it, feel free to email me:
destructionator@gmail.com.