This project aims at providing a solution for source code edition services, decoupled from any user interface, with an effort of abstraction of the underlying models. We call it: the backend.

This is for now concretely applied to specific things:

• Edition services modules (called modes):
  • JavaScript
  • HTML
  • Aria Templates, using the two above

The file system layout can be surprising, but comes from the way the module system works for Node.js and a will not to mix application modules and third-party modules.

Introduction

Please read the introduction if you never did it and don't know what the project is all about.

Please see the meta-documentation before reading or WRITING any documentation. This helps understanding the documentation, and is required to maintain it consistent while adding content.

Current development state

For now the work is focused on HTML (easy for tests). The structure of the language is close to Aria Templates, which is a good thing.

You can launch a backend instance (see procedure below) and interact with it the way you want.

File system layout

• README.md: this current file
• roadmap.md: a roadmap for the project
• client.md: a recap documentation explaining how clients can use the backend
• introduction.md: an introduction to the project
• documentation.md: a documentation about the documentation in this project (meta-documentation)
• .gitignore: Git related file
• package.json: npm package.json
• node_modules: all third-party libraries used by the application.

app

Applications files.

The application follows a modular architecture, and all the module are hierarchically organized into this root folder.

Under this root, there are pseudo-standard modules and modules of the application: this is described in the respective documentation.

A pseudo-standard module is a module that is not installed through the package management system ( npm here) since it is home-made. However this is a module that is not specific to this application, it could be re-used in many other ones.

Versioning

To ignore:

• node_modules: can be installed from the package.json data with the use of npm

To version: everything else.

Documentation

As mentioned, the goal is to implement a generic solution to handle source code edition, whatever the language, whatever the UI used behind (i.e. the tool(s)).

If you want to implement a client using this backend, please read this tutorial.

Architecture

We call the tools used to actually edit source code: frontends. They provide the (G)UI.

We call the application serving source edition features (processing): the backend.

A frontend is a client of this backend (then acting as a server application), and they communicate through standard means.

Here is a quick description of the stack:

• backend: a Node.js based application, providing services used by editors and IDEs
• API: a classical programming interface for the backend, used by the JSON-RPC (Remote Procedure Call protocol using JSON) layer (which is the end point of the communication interface - see below - for the backend)
• communication interface: JSON-RPC through HTTP (default listening port: 3000)
• frontend: any IDE or editor with extension capability, using the backend through the communication interface

This project aims at providing everything except the last part: indeed, a frontend is a consumer of the project.

List of frontends

Existing:

• Eclipse

Ideas:

• Sublime Text
• Notepad++
• Cloud9
• a custom/standard frontend (IDE for instance)

Even any other specific tools not even doing edition (but analysis for instance).

Contribute

I would first give an advice to apply everywhere: READ CAREFULLY THE DOCS.

Environment

To be able to develop the project or even use the product you need to:

• Install Node.js - tested with latest version (0.10.12 at the time of writing)
  • the node binary must in in the PATH environment variable
• Install npm (releases)

Tested on Microsoft Windows 7 Enterprise 64-bit SP1.

Setup

Install the node modules, by launching the program with the following properties:

• program name: npm
• program arguments (command in this case): install
• current working directory (context): the folder containing package.json

In more simple words: launch from this directory the command npm install.

Also, build the HTML parser.

Try

• make sure the port 3000 is free on your system
• open a terminal emulator executing a system shell
• execute the command: npm start from this directory
• (you can check it works if this sends OK)

Development

Please refer to the subfolders of the project for details about corresponding modules specific development: every folder containing a documentation like this contains a section talking about contributions you can make to it.

Sections below discuss about development at the whole project scale.

Please have a look at the roadmap too for a prioritization of what has to be done. It will link to specific documentations' sections (including some of below ones).

Package definition

You can update the package by modifying the content of the package.json file.

For that you'll need to know the npm package.json specifications.

What can be done among others:

• check required modules
  • remove unecessary modules
  • maybe put version constraints
• update the description, tags, ...
• work on the packaging: installation, generated commands, local vs. global, ...

Application code

Please refer to the content of the app folder.

Performances of process interactions

Reduce the overhead introduced by HTTP, JSON serialization and also RPC.

Maybe the use of JSON-RPC through HTTP can be too heavy for very frequent and simple operations done while editing. I'm mainly thinking about the frequent update of the models (source, AST (graph) and so on) concerning content, positions, etc., while the user enters text.

Think about using a custom protocol built on top of lower-level ones (TCP for instance).

The following aspects can be improved:

• connection setup: keeping connected state (contrary to basic HTTP)
• protocol overhead: limit amount of data used only for the information transmission. HTTP is pure text and thus easy to read, debug, but it can be too much. Prefer binary, and a minimum amount of required data.
• serialization: limit verbosity, prefer binary over text (JSON is already better than XML), ...
• bonus - two ways sockets: rather than a client-server model, simply make the two entities communicate both ways

There are also other standard solutions like CORBA (but I'm not sure there is an available mapping for JavaScript in this case).

I (ymeine) found recently (05 Jul 2013) an article talking about Thrift. The description at least corresponds exactly to what we want to do: provide services to clients whatever the system they use, and automatically deal with remote procedure calls and so on.

Documentation

Review the documentation of the documentation (the meta-documentation), written in documentation.md for now.

Contribute section

Check how to structure the Contribute section.

Two things can be distinguished:

• content talking about how to setup the project, configure the environment, and also how to try the project, to manually/visually test it: all of this is optional
• content talking about what can be done to actually develop the project

For the second one, it's harder to see how to structure it. At least we can bring out two aspects: development for the code, and work on the documentation. One last thing is the section about fixes to be done: it must appear first and be concise, since this concerns urgent tasks.

So here are the main parts in order in this section:

1. Setup: optional
2. Try/Test: optional
3. Develop
   1. FIXMEs
   2. Code
   3. Documentation

Inside the code section, theer can be many things, from little tasks to more complex ones, requiring detailed paragraphs.

I would put everything in a dedicated section with a meaningful name, followed by a single emphased line summarizing the nature of the task, and then possibly a description paragraph.

Guidelines

Complete the guidelines section.

Documentation / Contribute order

Choose wether to put the Documentation section before the Contribute one or vice versa.

Seems like the first one is the one mostly used.

Wiki

Determine content with a general purpose trait and consider putting it in a wiki.

Think about putting documentation files other than README.md ones into the wiki. Indeed, they seem to be more general files.

The README.md files are specific, and there can be only one per folder. A folder often being a module, this is logical to use them to describe the module specifically.

Other files might be for more general purposes, so consider putting them into the wiki.

External libraries

Interesting external libraries

• RPC
  • jsonrpclib
  • node-jsonrpc
  • ...

References

• npm package.json