Skip to content
Permalink
Browse files

Update documentation

  • Loading branch information...
Kripth committed Jan 6, 2019
1 parent 43e2bf1 commit 09bb61419ff3e2d1eb2016d3cf72cba4d4f279c4
Showing with 109 additions and 5 deletions.
  1. +2 −2 .travis.yml
  2. +2 −0 README.md
  3. +1 −1 examples/crud/src/app.d
  4. +73 −1 src/scorpion/controller.d
  5. +1 −1 src/scorpion/starter.d
  6. +30 −0 src/scorpion/validation.d
@@ -2,8 +2,8 @@ language: d

d:
- dmd
- ldc
# - ldc

os:
- linux
- osx
# - osx
@@ -49,3 +49,5 @@ Also, note that scoprion-boot does not work with [single-file packages](https://
- [Controllers](docs/controller.md)

## In depth

- [Creating a CRUD RESTful web service](examples/crud)
@@ -21,7 +21,7 @@ class Book {

JSONValue[string] toJSON() {
return [
"bookId": JSONValue(bookId.value),
"id": JSONValue(bookId.value),
"title": JSONValue(title),
"author": JSONValue(author)
];
@@ -3,7 +3,7 @@
import lighttp.util : Status;

/**
* Annotation for controllers.
* Attribute for controllers.
* Example:
* ---
* @Controller
@@ -21,6 +21,17 @@ struct Controller {

}

/**
* Attributes for routes.
* Indicates the method used (case sensitive, usually uppercase),
* whether the method can have a body and the path.
* Example:
* ---
* @Route("GET", false, "hello", "world") // GET /hello/world
* @Post // POST /
* @Delete("resource", "([a-z]+)") // DELETE /resource/:name
* ---
*/
struct Route {

string method;
@@ -35,28 +46,89 @@ struct Route {

}

/// ditto
Route Get(string[] path...) {
return Route("GET", false, path);
}

/// ditto
Route Post(string[] path...) {
return Route("POST", true, path);
}

/// ditto
Route Put(string[] path...) {
return Route("PUT", true, path);
}

/// ditto
Route Patch(string[] path...) {
return Route("PATCH", true, path);
}

/// ditto
Route Delete(string[] path...) {
return Route("DELETE", true, path);
}

/**
* Attribute that indicates that the paramater is from a path's
* regex capture.
* The number of parameters annotated with `@Path` should correspond
* to the number of captures in the path.
* The type of the parameter can be any type that can be converted
* from a string: it's the programmer's duty to write a regular expression
* that won't cause any conversion exception.
* Example:
* ---
* @Get("([a-z]+)")
* _(Response response, @Path string capture) {
* ...
* }
* ---
*/
enum Path;

/**
* Attribute that indicates that the parameter is from a path's
* query.
* The parameter's type can be any type that can be converted from
* a string. If the conversion fails a `bad request` client error
* is returned to the client and the handler is not called.
* Example:
* ---
* @Get("hello")
* _(Response response, @Param string username) {
* response.body_ = "Your username: " ~ username;
* }
* ---
*/
struct Param { string param; }

/**
* Attribute that indicates that the parameter is converted from
* the request's body.
* The parameter must be either a struct or a class that will be
* insantiated by the validator and validated by it.
* The method is not usually called when the validation fails, but
* if the method also contains a `scorpion.validation.Validation`
* object as paramter the method is called even when the object
* was not successfully validated.
* To learn more about the validation process and the attributes
* that can be added to the object's members to validate see the
* `scorpion.validation` module's documentation.
* Example:
* ---
* struct Message {
*
* string sender, message;
*
* }
*
* @Post("hello")
* _(Response response, @Body Message message) {
* response.body_ = "Hello, " ~ message.sender ~ ", thanks for the message.";
* }
* ---
*/
enum Body;
@@ -45,7 +45,7 @@ void start(string[] args) {
}

ServerOptions options;
options.name = "Scorpion/~master";
options.name = "Scorpion/0.1";
options.max = config.get("scorpion.upload.max", 2 ^^ 24); // 16 MB

Server server = new Server(options);
@@ -132,21 +132,51 @@ private bool emailValidator(string value) { return emailLength(value) == value.l
*/
enum Optional;

/**
* Validation utility class that contains errors.
*/
class Validation {

/**
* Representation of an error.
*/
static struct Error {

/**
* Field that the error is associated to.
* If the error is not associated to any particular field
* or it is associated to all of the them the value of this
* member id `*`.
*/
string field;

/**
* Error message. Can be an error code a sentence in a human-readable
* language.
* It's the last parameter is a custom validator.
*/
string message;

}

/**
* Errors generated during the validation process or by the
* controller.
*/
Error[] errors;

/**
* Indicates whether the validation was successful. A successful
* validation has no error.
*/
@property bool valid() pure nothrow @safe @nogc {
return errors.length == 0;
}

/**
* If the validation failed sets the response's status to
* `bad request` and prints the errors to its body.
*/
void apply(ServerResponse response) {
if(!valid) {
response.status = StatusCodes.badRequest;

0 comments on commit 09bb614

Please sign in to comment.
You can’t perform that action at this time.