vimwiki/tech/Crow.wiki

123 lines
3.6 KiB
Plaintext
Raw Normal View History

2022-04-28 18:30:01 +00:00
= 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 ===
2022-04-28 18:45:01 +00:00
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.
2022-04-28 19:00:01 +00:00
Assign values to a `crow::json` value via the index operator.
2022-04-28 18:45:01 +00:00
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
2022-04-28 19:00:01 +00:00
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`.