remove old builders (bash) + update readme

README.md

@@ -2,22 +2,113 @@
 
 
 
-**Aicra** is a self-working API coded in *Go*:
+**Aicra** is a self-working framework coded in *Go* that allows anyone to create a fully featured REST API. It features :
+
+- type checking
+
+- authentication management
+
+- rich argument management (url slash-separated, urlencoded, form-data, json)
+
+- nested routes
+
+- request and response interfaces
+
+- a project builder (cf. *aicra*)
+
+- Optional arguments and default values
+
+- ...
+
+
+
+It is based over some of the following concepts.
+
+| concept | explanation |
+|---|---|
+| meaningful defaults | Defaults and default values work without further understanding |
+| config-driven | Avoid information duplication. Automate anything that can be without losing control. Have *one* configuration that summarizes the whole project, its behavior and its automation flow. |
 
-- It allows anyone to create a fully featured REST API
-- it can be used in *Go* as a library, or as a proxy to launch external commands (*e.g. php scripts*)
 
-It is based on the *all-in-config* idea, where you only have a configuration file, and your implementation and it works without no further work.
 
 
 > A working example is available [here](https://git.xdrm.io/example/gfw)
 
 
+
+#### 1. Installation
+
+You need a recent machine with `go` installed.
+
+> This package has not been tested under the version **1.10**.
+
+
+
+##### (1) Installation
+
+Run the following command to fetch and install the package :
+
+```bash
+go get -u git.xdrm.io/go/aicra
+```
+
+It should now be available locally and available for your imports.
+
+
+
+You should then install the project builder to help you manage your projects, run the following command :
+
+```bash
+go install git.xdrm.io/go/aicra/cmd/aicra
+```
+
+The executable `aicra` will be placed into your `$GOPATH/bin` folder, if added to your environment PATH it should be available as a standalone command in your terminal. If not, you can simply run `$GOPATH/bin/aicra` to use the command or create a symlink into `/usr/local/bin` or the PATH folder of your choice for less characters to type.
+
+
+
+#### 2. Setup a project
+
+To create a project using **aicra**, simply create an empty folder. Then you'll have to create a `manifest.json` file containing your API description. To write your manifest file, follow this [example](https://git.xdrm.io/example/aicra/src/master/manifest.json).
+
+
+
+##### (1) Controllers
+
+For each *uri*, you'll have to place your implementation into the local `root` folder following the following naming convention : add `i.go` at the end of the route.
+
+> **Example** - `/path/to/some/uri` will be implemented in the *./root* local folder inside the file : `/path/to/some/urii.go`.
+
+A fully working example is available [here](https://git.xdrm.io/example/aicra).
+
+
+
+##### (2) Custom types
+
+If you want to create custom types for the type checker or override built-in types place them inside the `./custom-types` folder. You can check what structure to follow by looking at the [built-in types](https://git.xdrm.io/go/aicra/src/master/checker/default).
+
+
+
+#### 3. Build your project
+
+After each controller or custom type edition, you'll have to rebuild the project. This can be achieved through the command-line builder.
+Usage is `aicra [options] /path/to/your/project`.
+
+Options:
+
+- `-c controller/path` - overrides the default controllers path ; default is `./root`
+
+- `-t custom/types` - overrides the default custom types path ; default is `./custom-types`
+
+
+
+
+
+
 ##### changelog
 
-- [x] human-readable json configuration
+- [x] human-readable json configuration
-- [x] nested routes (*i.e. `/user/:id:` and `/user/post/​:id:​`*)
+- [x] nested routes (*i.e. `/user/:id:` and `/user/post/​:id:​`*)
-- [ ] nested URL arguments (*i.e. `/user/:id:` and `/user/:id:/post/​:id:​`*)
+- [ ] nested URL arguments (*i.e. `/user/:id:` and `/user/:id:/post/​:id:​`*)
 - [x] useful http methods: GET, POST, PUT, DELETE
 - [x] manage URL, query and body arguments:
   - [x] multipart/form-data (variables and file uploads)
@@ -25,8 +116,8 @@ It is based on the *all-in-config* idea, where you only have a configuration fi
   - [x] application/json
 - [x] required vs. optional parameters with a default value
 - [x] parameter renaming
-- [ ] generic authentication system (*i.e. you can override the built-in one*)
+- [ ] generic authentication system (*i.e. you can override the built-in one*)
-- [x] generic type check (*i.e. implement custom types alongside built-in ones*)
+- [x] generic type check (*i.e. implement custom types alongside built-in ones*)
 - [ ] built-in types
 	- [x] `any` - wildcard matching all values
 	- [x] `int` - any number (*e.g. float, int, uint*)

build-controllers.sh

@@ -1,42 +0,0 @@
-#!/bin/bash
-
-# (1) Check argument
-#--------------------------------------------------------#
-if [ "$#" -lt 1 -o ! -d "$1" ]; then
-	echo -e "\e[33mERROR\e[0m missing parameter\n"
-	echo -e "+ expected first argument to be the controller's folder"
-	exit 1;
-fi
-
-
-
-# (1) Get controller path #
-BASE_DIR="`realpath $(pwd)`"
-CTL_PATH="`realpath $1`";
-
-# (2) List go files #
-cd $CTL_PATH
-GO_FILES="`ls *i.go **/*i.go 2>/dev/null`"
-
-# (3) Create target directory in execution dir #
-mkdir -p $BASE_DIR/controllers;
-
-# (4) Build each file #
-d=1
-for file in $GO_FILES; do
-	ctl="${file%.*}" # remove extension from path
-	echo -e "($d) Building \e[33m$ctl\e[0m";
-	# build into execution dir
-	go build -buildmode=plugin -ldflags "-s -w" -o "$BASE_DIR/controllers/$ctl.so" ./$file;
-
-	# Manage failure
-	if [ "$?" -ne "0" ]; then
-		echo -e "\e[31m/!\\ \e[0merror building \e[33m$ctl\e[0m\n"
-	fi
-
-	d=""`expr $d + 1`""
-done;
-
-# (5) ACK #
-echo -e "\n[ \e[32mfinished\e[0m ]\n"
-echo -e "files are located inside the relative \e[33m./controllers\e[0m directory"

build-types.sh

@@ -1,31 +0,0 @@
-#!/bin/bash
-
-# (1) Get default path #
-DEFAULT_PATH="`realpath $GOPATH`/src/git.xdrm.io/go/aicra/checker/default";
-# fail if do not exist
-test -d $DEFAULT_PATH || (echo "$DEFAULT_PATH does not exists.. aborting"; exit 1) || exit 1;
-
-# (2) List go files #
-GO_FILES="`ls $DEFAULT_PATH/**/*.go`"
-
-# (3) Create target directory #
-mkdir -p ./types;
-
-# (4) Build each file #
-d=1
-for Type in $GO_FILES; do
-	plugin_name="`basename $(dirname $Type)`"
-	echo -e "($d) Building \e[33m$plugin_name\e[0m";
-	go build -buildmode=plugin -o "./types/$plugin_name.so" $Type;
-
-	# Manage failure
-	if [ "$?" -ne "0" ]; then
-		echo -e "\e[31m/!\\ \e[0merror building \e[33m$plugin_name\e[0m\n"
-	fi
-
-	d=""`expr $d + 1`""
-done;
-
-# (5) ACK #
-echo -e "\n[ \e[32mfinished\e[0m ]\n"
-echo -e "files are located inside the relative \e[33m./types\e[0m directory"