Unverified Commit ed43af7d authored by Tachi's avatar Tachi

Complete documentation rewrite

parent d8790b48
---
id: doc1
title: Style Guide
sidebar_label: Style Guide
---
You can write content using [GitHub-flavored Markdown syntax](https://github.github.com/gfm/).
## Markdown Syntax
To serve as an example page when styling markdown based Docusaurus sites.
## Headers
# H1 - Create the best documentation
## H2 - Create the best documentation
### H3 - Create the best documentation
#### H4 - Create the best documentation
##### H5 - Create the best documentation
###### H6 - Create the best documentation
---
## Emphasis
Emphasis, aka italics, with *asterisks* or _underscores_.
Strong emphasis, aka bold, with **asterisks** or __underscores__.
Combined emphasis with **asterisks and _underscores_**.
Strikethrough uses two tildes. ~~Scratch this.~~
---
## Lists
1. First ordered list item
1. Another item
- Unordered sub-list.
1. Actual numbers don't matter, just that it's a number
1. Ordered sub-list
1. And another item.
* Unordered list can use asterisks
- Or minuses
+ Or pluses
---
## Links
[I'm an inline-style link](https://www.google.com/)
[I'm an inline-style link with title](https://www.google.com/ "Google's Homepage")
[I'm a reference-style link][arbitrary case-insensitive reference text]
[You can use numbers for reference-style link definitions][1]
Or leave it empty and use the [link text itself].
URLs and URLs in angle brackets will automatically get turned into links. http://www.example.com/ or <http://www.example.com/> and sometimes example.com (but not on GitHub, for example).
Some text to show that the reference links can follow later.
[arbitrary case-insensitive reference text]: https://www.mozilla.org/
[1]: http://slashdot.org/
[link text itself]: http://www.reddit.com/
---
## Images
Here's our logo (hover to see the title text):
Inline-style: ![alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png 'Logo Title Text 1')
Reference-style: ![alt text][logo]
[logo]: https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png 'Logo Title Text 2'
Images from any folder can be used by providing path to file. Path should be relative to markdown file.
![img](../static/img/logo.svg)
---
## Code
```javascript
var s = 'JavaScript syntax highlighting';
alert(s);
```
```python
s = "Python syntax highlighting"
print(s)
```
```
No language indicated, so no syntax highlighting.
But let's throw in a <b>tag</b>.
```
```js {2}
function highlightMe() {
console.log('This line can be highlighted!');
}
```
---
## Tables
Colons can be used to align columns.
| Tables | Are | Cool |
| ------------- | :-----------: | -----: |
| col 3 is | right-aligned | \$1600 |
| col 2 is | centered | \$12 |
| zebra stripes | are neat | \$1 |
There must be at least 3 dashes separating each header cell. The outer pipes (|) are optional, and you don't need to make the raw Markdown line up prettily. You can also use inline Markdown.
| Markdown | Less | Pretty |
| -------- | --------- | ---------- |
| _Still_ | `renders` | **nicely** |
| 1 | 2 | 3 |
---
## Blockquotes
> Blockquotes are very handy in email to emulate reply text. This line is part of the same quote.
Quote break.
> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can _put_ **Markdown** into a blockquote.
---
## Line Breaks
Here's a line for us to start with.
This line is separated from the one above by two newlines, so it will be a _separate paragraph_.
This line is also a separate paragraph, but... This line is only separated by a single newline, so it's a separate line in the _same paragraph_.
---
## Admonitions
:::note
This is a note
:::
:::tip
This is a tip
:::
:::important
This is important
:::
:::caution
This is a caution
:::
:::warning
This is a warning
:::
---
id: http-handler
title: HTTP handler
slug: /
---
Requests that are received by Pistache are handled by a special class called `Http::Handler`. This class declares a bunch of virtual methods that can be overriden to handle special events that occur on the socket and/or connection.
......
---
title: Getting started
slug: /
---
Pistache is a web framework written in Modern C++ that focuses on performance and provides an elegant and asynchronous API.
```cpp
#include <pistache/pistache.h>
```
## Installing Pistache
[git](https://git-scm.com) is needed to retrieve the sources. Compiling the sources will require [CMake](https://cmake.org) to generate build files and a recent compiler that supports C++17.
If you're on Ubuntu and want to skip the compilation process you can add the official PPA providing nightly builds:
```sh
sudo add-apt-repository ppa:pistache+team/unstable
sudo apt update
sudo apt install libpistache-dev
```
Otherwise, here's how to build and install the latest release:
```sh
git clone --recurse-submodules https://github.com/pistacheio/pistache.git
cd pistache
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make
sudo make install
```
Also, Pistache does not support Windows yet, but should work fine under [WSL](https://docs.microsoft.com/windows/wsl/about).
## Serving requests
### Include
First, let’s start by including the right header.
```cpp
#include <pistache/endpoint.h>
```
### Hello world
Requests received by Pistache are handled with an `Http::Handler`.
Let’s start by defining a simple `HelloHandler`:
```cpp
using namespace Pistache;
class HelloHandler : public Http::Handler {
public:
HTTP_PROTOTYPE(HelloHandler)
void onRequest(const Http::Request& request, Http::ResponseWriter response) {
response.send(Http::Code::Ok, "Hello, World\n");
}
};
```
Handlers must inherit the `Http::Handler` class and at least define the `onRequest` member function. They must also define a `clone()` member function. Simple handlers can use the special `HTTP_PROTOTYPE` macro, passing in the name of the class. The macro will take care of defining the `clone()` member function for you.
### Final touch
After defining the handler, the server can now be started:
```cpp
int main() {
Address addr(Ipv4::any(), Port(9080));
auto opts = Http::Endpoint::options().threads(1);
Http::Endpoint server(addr);
server.init(opts);
server.setHandler(Http::make_handler<HelloHandler>());
server.serve();
}
```
For simplicity, you can also use the special `listenAndServe` function that will automatically create an endpoint and instantiate your handler:
```cpp
int main() {
Http::listenAndServe<HelloHandler>("*:9080");
}
```
And that’s it, now you can fire up your favorite curl request and observe the final result:
```sh
curl http://localhost:9080/
Hello, World
```
Complete code for this example can be found on GitHub: [examples/hello_server.cc](https://github.com/pistacheio/pistache/blob/master/examples/hello_server.cc)
---
title: REST description
---
Documentation writing for this part is still in progress, please refer to the [rest_description](https://github.com/pistacheio/pistache/blob/master/examples/rest_description.cc) example.
......@@ -20,3 +20,80 @@ A bunch of HTTP methods (verbs) are supported by Pistache:
- _DELETE_: the `DELETE` method is used to delete a resource associated to a given Request-URI. For example, to remove an user, a client might issue a `DELETE` call to the `/users/:id` Request-URI.
To sum up, `POST` and `PUT` are used to Create and/or Update, `GET` is used to Read and `DELETE` is used to Delete information.
## Route patterns
### Static routes
Static routes are the simplest ones as they do rely on dynamic parts of the Request-URI. For example `/users/all` is a static route that will exactly match the `/users/all` Request-URI.
### Dynamic routes
However, it is often useful to define routes that have dynamic parts. For example, to retrieve a specific user by its id, the id is needed to query the storage. Dynamic routes thus have parameters that are then matched one by one by the HTTP router. In a dynamic route, parameters are identified by a column `:`
`/users/:id`
Here, `:id` is a dynamic parameter. When a request comes in, the router will try to match the `:id` parameter to the corresponding part of the request. For example, if the server receives a request to `/users/13`, the router will match the `13` value to the `:id` parameter.
Some parameters, like `:id` are named. However, Pistache also allows _splat_ (wildcard) parameters, identified by a star `*`:
`/link/*/to/*`
## Defining routes
To define your routes, you first have to instantiate an HTTP router:
```cpp
Http::Router router;
```
Then, use the `Routes::<Method>()` functions to add some routes:
```cpp
Routes::Get(router, "/users/all", Routes::bind(&UsersApi::getAllUsers, this));
Routes::Post(router, "/users/:id", Routes::bind(&UsersApi::getUserId, this));
Routes::Get(router, "/link/*/to/*", Routes::bind(&UsersApi::linkUsers, this));
```
`Routes::bind` is a special function that will generate a corresponding C++ callback that will then be called by the router if a given route matches the Request-URI.
### Callbacks
A C++ callback associated to a route must have the following signature:
```cpp
void(const Rest::Request&, Http::ResponseWriter);
```
A callback can either be a non-static free or member function. For member functions, a pointer to the corresponding instance must be passed to the Routes::bind function so that the router knows on which instance to invoke the member function.
The first parameter of the callback is `Rest::Request` and not an `Http::Request`. A `Rest::Request` is an `Http::Request` will additional functions. Named and splat parameters are for example retrieved through this object:
```cpp
void UsersApi::getUserId(const Rest::Request& request, Http::ResponseWriter response) {
auto id = request.param(":id").as<int>();
// ...
}
void UsersApi::linkUsers(const Rest::Request& request, Http::ResponseWriter response) {
auto u1 = request.splatAt(0).as<std::string>();
auto u2 = request.splatAt(1).as<std::string>();
// ...
}
```
As you can see, parameters are also typed. To cast a parameter to the appropriate type, use the `as<T>` member template.
:::note Cast safety
An exception will be thrown if the parameter can not be casted to the right type
:::
### Installing the handler
Once the routes have been defined, the final `Http::Handler` must be set to the HTTP Endpoint. To retrieve the handler, just call the `handler()` member function on the router object:
```cpp
endpoint.setHandler(router.handler());
```
module.exports = {
someSidebar: {
Pistache: ['http-handler', 'asynchronous-http-programming', 'headers', 'routing'],
leftSidebar: {
Pistache: ['quickstart', 'http-handler', 'asynchronous-http-programming', 'headers', 'routing'],
},
};
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment