vimwiki/tech/Crow.wiki

= Crow =

Crow is a fast, [[flask]]-like C++ microframework

== Apps ==

Crow provides a `crow::App` type that comes in two flavors

* `crow::SimpleApp`
  * no middle ware
* `crow::App<m1, m2>`
  * uses m1, m2, etc. middleware

Some other usefule interfaces

* `bindaddr(192.168.1.144)`
  * takes an IP addr to bind to
* `.port(443)`
  * takes an int port to listen on
* `.multithreaded()`
  * enable multithreaded request handling
* `.run()`
  * Run the app
  * Run is blocking, use `run_async` for non blocking

== Routes ==

Routes assign URLs to function calls. To assign a route, use the macro

`CROW_ROUTE(app, url)`

where,
* `app` is the app class to assign the route to
* `url` is the relative path is assigned to the route
  * paths can take paramaters
    * `/hello/<int>`
  * paramaters can be
    * `int`
    * `uint`
    * `double`
    * `string`
    * `path`

HTTP methods can also be changed on routes via the `.method()` call, appended
to the `CROW_ROUTE` macro.

HTTP methods include
* `crow::HTTPMethod::GET`
* `crow::HTTPMethod::PATCH`
* `crow::HTTPMethod::POST`

=== Catchall route ===

By default, crow will return a 404 page for not defined routes. However the
special `CROW_CATCHALL_ROUTE(app)` macro can be used the same as other routes,
however the catchall route will be used to catch all undefined routes

== JSON ==

Crow has built in JSON support. Json values are broken into a read and write
object, `rvalue` and `wvalue`. They can take
* bool
* Number
  * double
  * int
  * unsigned int
* std::string
* std::vector (LIST)
* Object (`crow::json::wvalue` or `crow::json::rvalue`)

`rvalue` is used for taking a JSON string and parsing it into `crow::json`. You
can only READ from a `rvalue`. To write to one, convert to `wvalue`. This is
done via `crow::json::wvalue wval(rval);`, where `rval` is the `rvalue` you
want to convert.

Assign values to a `crow::json` value via the index operator.

You can return a `wvalue` in a route handler, and the type is automatically
casted and the header Content-Type header is automatically set to
`application/json`.

== Mustache ==

See [[Mustache]]

An HTML page template with mustache tags is loaded into a
`crow::mustache::template_t`. The file needs to be in a templates directory.
These templates are read at runtime, and therefore need to be available to the
binary. A global templates directory can be set via
`crow::mustache::set_global_base("new_template_dir")`.

== Query Strings ==

A query string is part of a URL that has a `?` char at the end, with the same
format as a POST request. In a handler you will have access to a
`crow::request::url_params`. It supports
* `get(name)`
  * get `name` and return value as a `char*`
  * if not found return `nullptr`
* `get_list(name)`
  * return a `std::vector<std::string>` of values if key in query string is of
    format `key[]=val1&key[]=val2`
* `get_dict(name)`
  * return a `std::unordered_map<std::string, std::string>` of values for dict
    style query string

All of the above `get_*` operation has a `pop_*` counterpart that modifies the
object. Note that the provided `crow::request::url_params` object is `const` by
default, and therefore you will not be able to call `pop_*` on it unless a copy
is made.

== Compression ==

Compression is disabled by default. To enable it be sure to include
`-DCROW_ENABLE_COMPRESSION` in your compilation calls. Then call
`use_compression(crow::compression::algorithm)` on your `crow::App` or
`crow::SimpleApp` object. Also be sure to include ZLIB as a dependency.

The compression algorithms provided include
`crow::compression::algorithm::DEFLATE` and
`crow::compression:algorithm::GZIP`.