idank
add an HTTP API
It might be time to add an HTTP API for tools/websites that want to integrate with explainshell (issue #4 is one).
My current thought is to add a GET endpoint at /api/explain with a cmd parameter, similar to /explain. The response could be a JSON that looks something like this:
{
'help' : ['help text 0', 'help text 1', ..],
'cmd' : <parsed command>
'matches' : [{'startindex' : x,
'endindex' : y,
'helpindex' : <index into help array, or -1 if unknown>], [..]]
}
The rationale for not inlining the help text into matches is that there can be duplicates. The reason for including cmd in the response is that it's possible for explainshell to change it, e.g. due to unicode which is not supported yet.
Example:
GET /api/explain?cmd=echo -n
{
'help' : ['display a line of text',
'-n do not output the trailing newline'],
'cmd' : 'echo -n'
'matches' : [{'startindex' : 0, 'endindex' : 4, 'helpindex' : 0},
{'startindex' : 5, 'endindex' : 7, 'helpindex' : 1}]
}
In the TODO page, it says that the API is done. Should this issue be closed? If so, where is the documentation for the API?
No, that's a mistake. I do have a WIP branch from a few months ago, but haven't had enough demand/need to finish it up.
Is it worth salvaging, or would it be best to start from scratch?
On Sat, Oct 11, 2014 at 2:56 PM, Idan Kamara [email protected] wrote:
No, that's a mistake. I do have a WIP branch from a few months ago, but haven't had enough demand/need to finish it up.
Reply to this email directly or view it on GitHub: https://github.com/idank/explainshell/issues/60#issuecomment-58760454
I seem to have lost the branch, or never actually started working on this.
If you're interested in working on this, please describe roughly what your plans are so we're on the same page. I can point you to places in the code that might be worth looking at.
Since the parser is more capable now and can explain nested constructs, what I wrote above might not be the best approach.
i know this is old, but any idea if anyone managed it? temporarily using the parser someone built for commandline access but i'd love to see a proper RESTful implementation if it exists and/or see it built.
Unfortunately no. Personally I haven't had the time to get this done, and no one has cared enough to add it.
FYI, I have created a quick and dirty wrapper, that fetches the explainshell HTTP output and outputs it as a structured JSON. Fell free to use it or contribute: https://github.com/gryffus/explainshell-api
