After quite some while I finally found the time to fully document the REST API of PSHDL, but maybe it you might want to know why I but such a high emphasis on having a REST API vs. investing time in a command line compiler. Don't worry though, a follow up on how to use the command line (which already exists in some pieces) will follow soon.
To make one thing very clear: I will not use, publish or sell the code that is on my server. I put some effort into the fact that you can not extract the user name or eMail of a workspace, also the workspace is not exposed in such a way that a crawler might find it, unless you post a link to it somewhere. I might take a look at the code if I find that it creates some undesirable behavior (takes unusual long to compile, crashes the compiler, consumes large amount of disk space or is harming the server in some other way). I also might take a look at the interaction with the compiler to learn from it. One particular example I have in mind is: How many edits does it take until the user recovers from a compile error.
You can find the documentation online at the API URL. Unfortunately swagger, the framework that I am using for creating the API documentation, has some issues with correctly filling the forms. So don't be surprised if the sand-box functionality does not work correctly. I hope this will be fixed in a not too future version.
There are good reasons for not using the REST API, especially when you are not just toying around anymore, but are producing something more serious. But most other users can actually benefit from it.
One of the hardest things about designing a language is to predict what people are going to try to do with your language. In a text based language with a fixed grammar some constructs are accepted by the grammar although they don't make any sense on a semantic level. Finding all those strange ways people intend to use your language is difficult for someone who knows the language very well. So occasionally some creative way of doing something can lead to problems that I did not cover well. In the best case they crash the compiler, in the worst case they produce code that is not correct.
My fear when handing out a command line version is that people are trying to solve a problem with PSHDL and fail, either because the compiler crashed, the documentation sucked, the warning wasn't clear enough or they were not using the latest version of the compiler. In a web environment the compiler and the documentation is always the latest version, also crash logs are collected so that I can take a look at them and hopefully fix them. When people are using it on their command line, the chances that they are going to report a bug is quite low, especially on the very crucial first few minutes of toying around with a new language.
With an online API it is very simple to share your code with others. If you run into a problem, you can simply send them a link to your source and they can then take a look at it. Or maybe you're working with someone else and want to work together on the same code base at the same time. This is quite easy to accomplish with the REST API. Especially when you start to make use of the streaming API which brings us to the next point.
In the future I will add the ability to add your own extensions to the web ui. For this a streaming API has been added. The streaming API is essentially a publish subscribe API realized with atmosphere, a web-socket/comet framework. You open a connection to the streaming API and get event notifications for most actions, like adding a file, compiling the workspace etc. In addition to that you can also publish your own messages.
With this API it is possible to create web pages that can react to events on the workspace. For example a local application might automatically download and synthesize your code whenever you hit compile in the workspace. You could also implement some sort of chat facility to discuss the code that you are working on. So far you can not directly hook in to the ui itself, but I am working on that.
Also a REST API is not bound to a particular language. In some circumstances it might not be desirable or even possible to run the Java version of the compiler (think of mobile handsets/tablets). With the REST API this is not much of an issue.
In order to get started with programming in PSHDL all you need is curl/wget or any other http client. No need to install (m)any tools.