User manual

Harmony's usage is simple. This section will explain how to install and use it, along with the extra software necessary in order to take full advantage of its output. All the examples assume that the user works on a Unix-based operating system.

Installation

NOTE: It is recommended to run cabal sandbox init before any other cabal install command in order to have an isolated environment and collisions with other projects that may require different versions.

The only requirement for installing Harmony is to have the Haskell platform installed in the machine (this means having GHC, Cabal, Alex, Happy) and the BNFC package. git is useful too in order to get the source code.

1. Go to Haskell platform, download and execute the installer.
2. cabal install bnfc.

From Hackage

Harmony is available on Hackage, that means that just running cabal install harmony should install the latest stable version.

From source code

1. git clone https://github.com/SantiMunin/harmony
2. cd harmony && cabal install

After executing the steps above, a harmony executable should be available (otherwise the user should check the path variable).

Usage

The best way of getting quick help regarding Harmony's usage is to execute harmony in the command line. It should output something like:

Usage: harmony [OPTION...] input_file
  -c[CLIENTS]     --client[=CLIENTS]         Desired output for the client
  -s[SERVERS]     --server[=SERVERS]         Desired output for the server
  -o[OUTPUT_DIR]  --output_dir[=OUTPUT_DIR]  Output path

The first step is to write the desired web service specification using the language explained in the Specification language section and save it to a input.hmy file. Afterwards, one should think about the desired output (-cpython, -cjava for Python and Java clients respectively and -sjs for the Javascript server).

As an example, if one needs the Javascript server and Python client and tests, she would execute harmony -sjs -cpython input.hmy. The screen should show something similar to the following code:

Applying yapf to ./harmony_output/client/python/client.py
Applying yapf to ./harmony_output/client/python/test.py
Applying js-beautifier to ./harmony_output/server/js/server.js

Also, a harmony_output folder (by default) should be created, containing the generated platforms. An example of tree harmony_output for the example would show something like:

harmony_output/
|-- client
|   |-- python
|       |-- client.py
|       |-- test.py
|-- server
    |-- js
        |-- package.json
        |-- server.js

The rest of this appendix will describe the different outputs and how to use them. We will use an existing example from the repository (examples/good/tasks.hmy) for each platform, showing what is generated and explaining how to deploy/use it.

The service's specification is the following:

service_name: Tasks
service_version: 1.0.0

struct Task { name : String, description: String}
struct Person { name : String, age: Int , tasks : [Task]}

resource Person("/person")

Javascript server

The dependencies for creating and deploying the server are the following:

• Node.js and npm.
• MongoDB
• js-beautifier (code beautifier used in the generation, optional).

After executing harmony -sjs examples/good/tasks.hmy and tree harmony_output:

Applying js-beautifier to ./harmony\_output/server/js/server.js
harmony_output/
|-- server
    |-- js
        |-- package.json
        |-- server.js

The package.json file lists the dependencies and the server.js file contains the server implementation.

How to deploy the server:

1. cd harmony_output/server/js
2. npm install (this will read the package.json file and download all the dependencies)
3. Start a MongoDB instance.
4. node server.js <server_port> <mongodb_address>

Python client and tests

The dependencies for creating and using the clients and tests are the following:

• python and pip.
• yapf (code beautifier used in the generation, optional).

After executing harmony -cpython examples/good/tasks.hmy and tree harmony_output:

Applying yapf to ./harmony_output/client/python/client.py
Applying yapf to ./harmony_output/client/python/test.py
harmony_output/
|-- client
    |-- python
        |-- client.py
        |-- test.py

The client.py file contains the client functionality, whereas the test.py contains the property based tests.

How to test the server (assuming it is already deployed following previously subsection's instructions on localhost:3132):

1. cd harmony_output/client/python
2. pip install hypothesis==1.2
3. pip install requests
4. python tests.py localhost:3132

The output of the last command should show the following:

Executing tests against http://localhost:3123
.
----------------------------------------------------------------------
Ran 1 test in 3.037s

Java client

TODO complete after implementation is finished