int main() {
// Create an FTP Server on port 2121. We use 2121 instead of the default\
port
// 21, as your application would need root privileges to open port 21.
fineftp::FtpServer ftp_server(2121);
// Add the well known anonymous user. Clients can log in using username
// "anonymous" or "ftp" with any password. The user will be able to access
// your C:\ drive and upload, download, create or delete files. On Linux\
just
// replace "C:\\" with any valid path. FineFTP is designed to be\
cross-platform.
ftp_server.addUserAnonymous("C:\\", fineftp::Permission::All);
// Start the FTP Server with a thread-pool size of 4.
ftp_server.start(4);
// Prevent the application from exiting immediately
for (;;) std::this_thread::sleep_for(std::chrono::milliseconds(100));
return 0;
}
```
## How to checkout and build
There is an example project provided that will create an FTP Server at `C:\`\
(Windows) or `/` (Unix).
1. Install cmake and git / git-for-windows
2. Checkout this repo and the asio submodule
```console
git clone https://github.com/eclipse-ecal/fineftp-server.git
cd fineftp-server
git submodule init
git submodule update
```
3. CMake the project *(Building as debug will add some debug output that is\
helpful so see if everything is working)*
```console
mkdir _build
cd _build
cmake .. -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=_install
```
4. Build the project
- Linux: `make`
- Windows: Open `_build\fineftp.sln` with Visual Studio and build the\
example project
5. Start `fineftp_example` / `fineftp_example.exe` and connect with your\
favorite FTP Client (e.g. FileZilla) on port 2121 *(This port is used so you\
don't need root privileges to start the FTP server)*
## CMake Options
You can set the following CMake Options to control how fineFTP Server is\
built:
**Option** | **Type** | **Default** | **Explanation** \
\
|
|--------------------------------|----------|-------------|------------------\
-----------------------------------------------------------------------------\
------------------|
| `FINEFTP_SERVER_BUILD_SAMPLES` | `BOOL` | `ON` | Build the fineFTP Server\
sample project. \
|
| `FINEFTP_SERVER_BUILD_TESTS` | `BOOL` | `OFF` | Build the the\
fineftp-server tests. Requires C++17. For executing the tests, `curl` must\
be available from the `PATH`. |
| `FINEFTP_SERVER_USE_BUILTIN_ASIO`| `BOOL`| `ON` | Use the builtin asio\
submodule. If set to `OFF`, asio must be available from somewhere else (e.g.\
system libs). |
| `FINEFTP_SERVER_USE_BUILTIN_GTEST`| `BOOL`| `ON`
_(when building\
tests)_ | Use the builtin GoogleTest submodule. Only needed if\
`FINEFTP_SERVER_BUILD_TESTS` is `ON`. If set to `OFF`, GoogleTest must be\
available from somewhere else (e.g. system libs). |
| `BUILD_SHARED_LIBS` | `BOOL` | | Not a fineFTP Server option,\
but use this to control whether you want to have a static or shared library.\
|
## How to integrate in your project
### Option 1: Integrate as binaries
1. Download the latest release from the releases page or compile the binaries\
yourself.
2. Add the fineFTP Server directory to your `CMAKE_PREFIX_PATH`:
```shell
cmake your_command_line -DCMAKE_PREFIX_PATH=path/to/fineftp/install/dir
```
### Option 2: Integrate as source
1. Make the fineFTP Server directory available in your project. You can\
either add it as a git submodule, or use CMake FetchContent to download it.
2. Add it to your CMake Project:
- **Either** by adding the top-level CMakeLists.txt to your project
```cmake
add_subdirectory(path/to/fineftp-server)
```
This which will inherit some behavior:
- You can use the CMake options described below
- You will get the asio version shipped with fineFTP
- The debug / minsize / relwithdebinfo postfix will be set\
automatically
- **Or** if you want to get a very clean version, which doesn't set any\
unnecessary options, include the `fineftp-server/server` subdirectory:
```cmake
add_subdirectory(path/to/fineftp-server/server)
```
You have to provide the required asio target on your own.
### Link against fineFTP Server
```cmake
find_package(fineftp REQUIRED)
target_link_libraries(your_target PRIVATE fineftp::server)
```
## Contribute
Awesome, you want to contribute to FineFTP? Here is how you can do that!
- Leave us a star ⭐️ (That's GitHub money!)
- Create an issue and write about a feature you would like or a bug you have\
found (maybe we will find some spare time to implement it 😉)
- Fork this repository, implement the feature yourself and create a pull\
request
\
description-type: text/markdown;variant=GFM
package-description:
\
# fineFTP Server
This project builds and defines the build2 package for the [fineFTP\
Server](https://github.com/eclipse-ecal/fineftp-server) library.
The packaging code is licensed under the MIT License, the upstream artifacts\
are licensed under the terms and conditions of fineFTP Server.
## Usage
You can simply add this package as dependency to your project by specifying\
it in your `manifest`:
```
depends: libfineftp-server ^1.3.4
```
Then just pick the targets that you need:
```
import libs = libfineftp-server%lib{fineftp-server}
```
\
package-description-type: text/markdown;variant=GFM
url: https://github.com/eclipse-ecal/fineftp-server
depends: * build2 >= 0.16.0
depends: * bpkg >= 0.16.0
depends: libasio ^1.28.0
bootstrap-build:
\
project = libfineftp-server
using version
using config
using test
using install
using dist
\
root-build:
\
# Uncomment to suppress warnings coming from external libraries.
#
#cxx.internal.scope = current
cxx.std = latest
using cxx
hxx{*}: extension = h
cxx{*}: extension = cpp
# Assume headers are importable unless stated otherwise.
#
hxx{*}: cxx.importable = true
# The test target for cross-testing (running tests under Wine, etc).
#
test.target = $cxx.target
\
location: fineftp-server/libfineftp-server-1.5.1.tar.gz
sha256sum: 0a419f8dfced6bcc4efad594d1bf295250862e9f3d792cf6ba901350f8a86304
:
name: libftxui
version: 6.1.9
project: FTXUI
summary: Functional Terminal (X) User interface - A simple C++ library for\
terminal based user interfaces!
license: MIT
topics: C++
description:
\
Documentation ·
Report a Bug ·
Examples\
.
Request\
Feature ·
Send a Pull\
Request
# FTXUI
Functional Terminal (X) User interface
A simple cross-platform C++ library for terminal based user interfaces!
## Feature
* Functional style. Inspired by
[1](https://hackernoon.com/building-reactive-terminal-interfaces-in-c-d392\
ce34e649?gi=d9fb9ce35901)
and [React](https://reactjs.org/)
* Simple and elegant syntax (in my opinion)
* Keyboard & mouse navigation.
* Support for [UTF8](https://en.wikipedia.org/wiki/UTF-8) and [fullwidth\
chars](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms) (→\
测试)
* Support for animations. [Demo 1](https://arthursonzogni.github.io/FTXUI/ex\
amples/?file=component/menu_underline_animated_gallery), [Demo\
2](https://arthursonzogni.github.io/FTXUI/examples/?file=component/button_st\
yle)
* Support for drawing. [Demo](https://arthursonzogni.github.io/FTXUI/example\
s/?file=component/canvas_animated)
* No dependencies
* **Cross platform**: Linux/MacOS (main target), WebAssembly, Windows\
(Thanks to contributors!).
* Learn by [examples](#documentation), and [tutorials](#documentation)
* Multiple packages: CMake [FetchContent]([https://bewagner.net/programming/\
2020/05/02/cmake-fetchcontent/](https://cmake.org/cmake/help/latest/module/Fe\
tchContent.html)) (preferred),Bazel, vcpkg, pkgbuild, conan.
* Good practices: documentation, tests, fuzzers, performance tests,\
automated CI, automated packaging, etc...
## Documentation
- [Starter example project](https://github.com/ArthurSonzogni/ftxui-starter)
- [Documentation](https://arthursonzogni.github.io/FTXUI/)
- [Examples (WebAssembly)](https://arthursonzogni.github.io/FTXUI/examples/)
- [Build using CMake](https://arthursonzogni.github.io/FTXUI/#build-cmake)
## Example
~~~cpp
vbox({
hbox({
text("one") | border,
text("two") | border | flex,
text("three") | border | flex,
}),
gauge(0.25) | color(Color::Red),
gauge(0.50) | color(Color::White),
gauge(0.75) | color(Color::Blue),
});
~~~
## Short gallery
#### DOM
This module defines a hierarchical set of Element. An Element manages layout\
and can be responsive to the terminal dimensions.
They are declared in [](https://arthursonzogni.github\
.io/FTXUI/elements_8hpp_source.html
)
Layout
Element can be arranged together:
- horizontally with `hbox`
- vertically with `vbox`
- inside a grid with `gridbox`
- wrap along one direction using the `flexbox`.
Element can become flexible using the the `flex` decorator.
[Example](https://arthursonzogni.github.io/FTXUI/examples_2dom_2vbox_hbox_8cp\
p-example.html) using `hbox`, `vbox` and `filler`.
[Example](https://arthursonzogni.github.io/FTXUI/examples_2dom_2gridbox_8cpp-\
example.html) using gridbox:
[Example](https://github.com/ArthurSonzogni/FTXUI/blob/master/examples/dom/hf\
low.cpp) using flexbox:
[See](https://arthursonzogni.github.io/FTXUI/examples_2dom_2hflow_8cpp-exampl\
e.html) also this [demo](https://arthursonzogni.github.io/FTXUI/examples/?fil\
e=component/flexbox).
Style
An element can be decorated using the functions:
- `bold`
- `italic`
- `dim`
- `inverted`
- `underlined`
- `underlinedDouble`
- `blink`
- `strikethrough`
- `color`
- `bgcolor`
- `hyperlink`
[Example](https://arthursonzogni.github.io/FTXUI/examples_2dom_2style_gallery\
_8cpp-example.html)
FTXUI supports the pipe operator. It means: `decorator1(decorator2(element))`\
and `element | decorator1 | decorator2` can be used.
Colors
FTXUI support every color palette:
Color [gallery](https://arthursonzogni.github.io/FTXUI/examples_2dom_2color_g\
allery_8cpp-example.html):
Border and separator
Use decorator border and element separator() to subdivide your UI:
```cpp
auto document = vbox({
text("top"),
separator(),
text("bottom"),
}) | border;
```
[Demo](https://arthursonzogni.github.io/FTXUI/examples_2dom_2separator_8cpp-e\
xample.html):
Text and paragraph
A simple piece of text is represented using `text("content")`.
To support text wrapping following spaces the following functions are\
provided:
```cpp
Element paragraph(std::string text);
Element paragraphAlignLeft(std::string text);
Element paragraphAlignRight(std::string text);
Element paragraphAlignCenter(std::string text);
Element paragraphAlignJustify(std::string text);
```
[Paragraph example](https://arthursonzogni.github.io/FTXUI/examples_2dom_2par\
agraph_8cpp-example.html)
Table
A class to easily style a table of data.
[Example](https://arthursonzogni.github.io/FTXUI/examples_2dom_2table_8cpp-ex\
ample.html):
Canvas
Drawing can be made on a Canvas, using braille, block, or simple characters:
Simple [example](https://github.com/ArthurSonzogni/FTXUI/blob/master/examples\
/dom/canvas.cpp):
Complex [examples](https://github.com/ArthurSonzogni/FTXUI/blob/master/exampl\
es/component/canvas_animated.cpp):
Gallery
[Gallery](https://arthursonzogni.github.io/FTXUI/examples_2component_2gallery\
_8cpp-example.html) of multiple components. ([demo](https://arthursonzogni.gi\
thub.io/FTXUI/examples/?file=component/gallery))
Radiobox
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2radiobo\
x_8cpp-example.html):
Checkbox
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2checkbo\
x_8cpp-example.html):
Input
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2input_8\
cpp-example.html):
Toggle
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2toggle_\
8cpp-example.html):
Slider
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2slider_\
8cpp-example.html):
Menu
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2menu_8c\
pp-example.html):
ResizableSplit
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2resizab\
le_split_8cpp-example.html):
Dropdown
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2dropdow\
n_8cpp-example.html):
Tab
[Vertical](https://arthursonzogni.github.io/FTXUI/examples_2component_2tab_ve\
rtical_8cpp-example.html):
[Horizontal](https://arthursonzogni.github.io/FTXUI/examples_2component_2tab_\
horizontal_8cpp-example.html):
\
description-type: text/markdown;variant=GFM
url: https://arthursonzogni.github.io/FTXUI/
doc-url: https://arthursonzogni.github.io/FTXUI/
src-url: https://github.com/ArthurSonzogni/FTXUI
package-url: https://github.com/build2-packaging/FTXUI
package-email: packaging@build2.org; Mailing list.
depends: * build2 >= 0.15.0
depends: * bpkg >= 0.15.0
tests: libftxui-tests == 6.1.9
examples: libftxui-examples == 6.1.9
builds: default
bootstrap-build:
\
project = libftxui
using version
using config
using test
using install
using dist
\
root-build:
\
# Uncomment to suppress warnings coming from external libraries.
#
cxx.internal.scope = current
cxx.std = latest
using cxx
hxx{*}: extension = hpp
ixx{*}: extension = ipp
cxx{*}: extension = cpp
# Assume headers are importable unless stated otherwise.
#
hxx{*}: cxx.importable = true
# The test target for cross-testing (running tests under Wine, etc).
test.target = $cxx.target
config [bool] config.libftxui.use_ms_terminal_fallback ?= true
# This library officially only support static builds,
# but we will prevent them only on Windows.
if($cxx.target.class == 'windows')
{
bin.lib = static
}
\
location: FTXUI/libftxui-6.1.9.tar.gz
sha256sum: dac73616f57d39eda870c7d4f8c333883654477f9c69e1161469afee2ef96004
:
name: libftxui-examples
version: 6.1.9
project: FTXUI
summary: Examples for the FTXUI library.
license: MIT
topics: C++
description:
\
Documentation ·
Report a Bug ·
Examples\
.
Request\
Feature ·
Send a Pull\
Request
# FTXUI
Functional Terminal (X) User interface
A simple cross-platform C++ library for terminal based user interfaces!
## Feature
* Functional style. Inspired by
[1](https://hackernoon.com/building-reactive-terminal-interfaces-in-c-d392\
ce34e649?gi=d9fb9ce35901)
and [React](https://reactjs.org/)
* Simple and elegant syntax (in my opinion)
* Keyboard & mouse navigation.
* Support for [UTF8](https://en.wikipedia.org/wiki/UTF-8) and [fullwidth\
chars](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms) (→\
测试)
* Support for animations. [Demo 1](https://arthursonzogni.github.io/FTXUI/ex\
amples/?file=component/menu_underline_animated_gallery), [Demo\
2](https://arthursonzogni.github.io/FTXUI/examples/?file=component/button_st\
yle)
* Support for drawing. [Demo](https://arthursonzogni.github.io/FTXUI/example\
s/?file=component/canvas_animated)
* No dependencies
* **Cross platform**: Linux/MacOS (main target), WebAssembly, Windows\
(Thanks to contributors!).
* Learn by [examples](#documentation), and [tutorials](#documentation)
* Multiple packages: CMake [FetchContent]([https://bewagner.net/programming/\
2020/05/02/cmake-fetchcontent/](https://cmake.org/cmake/help/latest/module/Fe\
tchContent.html)) (preferred),Bazel, vcpkg, pkgbuild, conan.
* Good practices: documentation, tests, fuzzers, performance tests,\
automated CI, automated packaging, etc...
## Documentation
- [Starter example project](https://github.com/ArthurSonzogni/ftxui-starter)
- [Documentation](https://arthursonzogni.github.io/FTXUI/)
- [Examples (WebAssembly)](https://arthursonzogni.github.io/FTXUI/examples/)
- [Build using CMake](https://arthursonzogni.github.io/FTXUI/#build-cmake)
## Example
~~~cpp
vbox({
hbox({
text("one") | border,
text("two") | border | flex,
text("three") | border | flex,
}),
gauge(0.25) | color(Color::Red),
gauge(0.50) | color(Color::White),
gauge(0.75) | color(Color::Blue),
});
~~~
## Short gallery
#### DOM
This module defines a hierarchical set of Element. An Element manages layout\
and can be responsive to the terminal dimensions.
They are declared in [](https://arthursonzogni.github\
.io/FTXUI/elements_8hpp_source.html
)
Layout
Element can be arranged together:
- horizontally with `hbox`
- vertically with `vbox`
- inside a grid with `gridbox`
- wrap along one direction using the `flexbox`.
Element can become flexible using the the `flex` decorator.
[Example](https://arthursonzogni.github.io/FTXUI/examples_2dom_2vbox_hbox_8cp\
p-example.html) using `hbox`, `vbox` and `filler`.
[Example](https://arthursonzogni.github.io/FTXUI/examples_2dom_2gridbox_8cpp-\
example.html) using gridbox:
[Example](https://github.com/ArthurSonzogni/FTXUI/blob/master/examples/dom/hf\
low.cpp) using flexbox:
[See](https://arthursonzogni.github.io/FTXUI/examples_2dom_2hflow_8cpp-exampl\
e.html) also this [demo](https://arthursonzogni.github.io/FTXUI/examples/?fil\
e=component/flexbox).
Style
An element can be decorated using the functions:
- `bold`
- `italic`
- `dim`
- `inverted`
- `underlined`
- `underlinedDouble`
- `blink`
- `strikethrough`
- `color`
- `bgcolor`
- `hyperlink`
[Example](https://arthursonzogni.github.io/FTXUI/examples_2dom_2style_gallery\
_8cpp-example.html)
FTXUI supports the pipe operator. It means: `decorator1(decorator2(element))`\
and `element | decorator1 | decorator2` can be used.
Colors
FTXUI support every color palette:
Color [gallery](https://arthursonzogni.github.io/FTXUI/examples_2dom_2color_g\
allery_8cpp-example.html):
Border and separator
Use decorator border and element separator() to subdivide your UI:
```cpp
auto document = vbox({
text("top"),
separator(),
text("bottom"),
}) | border;
```
[Demo](https://arthursonzogni.github.io/FTXUI/examples_2dom_2separator_8cpp-e\
xample.html):
Text and paragraph
A simple piece of text is represented using `text("content")`.
To support text wrapping following spaces the following functions are\
provided:
```cpp
Element paragraph(std::string text);
Element paragraphAlignLeft(std::string text);
Element paragraphAlignRight(std::string text);
Element paragraphAlignCenter(std::string text);
Element paragraphAlignJustify(std::string text);
```
[Paragraph example](https://arthursonzogni.github.io/FTXUI/examples_2dom_2par\
agraph_8cpp-example.html)
Table
A class to easily style a table of data.
[Example](https://arthursonzogni.github.io/FTXUI/examples_2dom_2table_8cpp-ex\
ample.html):
Canvas
Drawing can be made on a Canvas, using braille, block, or simple characters:
Simple [example](https://github.com/ArthurSonzogni/FTXUI/blob/master/examples\
/dom/canvas.cpp):
Complex [examples](https://github.com/ArthurSonzogni/FTXUI/blob/master/exampl\
es/component/canvas_animated.cpp):
Gallery
[Gallery](https://arthursonzogni.github.io/FTXUI/examples_2component_2gallery\
_8cpp-example.html) of multiple components. ([demo](https://arthursonzogni.gi\
thub.io/FTXUI/examples/?file=component/gallery))
Radiobox
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2radiobo\
x_8cpp-example.html):
Checkbox
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2checkbo\
x_8cpp-example.html):
Input
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2input_8\
cpp-example.html):
Toggle
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2toggle_\
8cpp-example.html):
Slider
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2slider_\
8cpp-example.html):
Menu
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2menu_8c\
pp-example.html):
ResizableSplit
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2resizab\
le_split_8cpp-example.html):
Dropdown
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2dropdow\
n_8cpp-example.html):
Tab
[Vertical](https://arthursonzogni.github.io/FTXUI/examples_2component_2tab_ve\
rtical_8cpp-example.html):
[Horizontal](https://arthursonzogni.github.io/FTXUI/examples_2component_2tab_\
horizontal_8cpp-example.html):
Documentation ·
Report a Bug ·
Examples\
.
Request\
Feature ·
Send a Pull\
Request
# FTXUI
Functional Terminal (X) User interface
A simple cross-platform C++ library for terminal based user interfaces!
## Feature
* Functional style. Inspired by
[1](https://hackernoon.com/building-reactive-terminal-interfaces-in-c-d392\
ce34e649?gi=d9fb9ce35901)
and [React](https://reactjs.org/)
* Simple and elegant syntax (in my opinion)
* Keyboard & mouse navigation.
* Support for [UTF8](https://en.wikipedia.org/wiki/UTF-8) and [fullwidth\
chars](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms) (→\
测试)
* Support for animations. [Demo 1](https://arthursonzogni.github.io/FTXUI/ex\
amples/?file=component/menu_underline_animated_gallery), [Demo\
2](https://arthursonzogni.github.io/FTXUI/examples/?file=component/button_st\
yle)
* Support for drawing. [Demo](https://arthursonzogni.github.io/FTXUI/example\
s/?file=component/canvas_animated)
* No dependencies
* **Cross platform**: Linux/MacOS (main target), WebAssembly, Windows\
(Thanks to contributors!).
* Learn by [examples](#documentation), and [tutorials](#documentation)
* Multiple packages: CMake [FetchContent]([https://bewagner.net/programming/\
2020/05/02/cmake-fetchcontent/](https://cmake.org/cmake/help/latest/module/Fe\
tchContent.html)) (preferred),Bazel, vcpkg, pkgbuild, conan.
* Good practices: documentation, tests, fuzzers, performance tests,\
automated CI, automated packaging, etc...
## Documentation
- [Starter example project](https://github.com/ArthurSonzogni/ftxui-starter)
- [Documentation](https://arthursonzogni.github.io/FTXUI/)
- [Examples (WebAssembly)](https://arthursonzogni.github.io/FTXUI/examples/)
- [Build using CMake](https://arthursonzogni.github.io/FTXUI/#build-cmake)
## Example
~~~cpp
vbox({
hbox({
text("one") | border,
text("two") | border | flex,
text("three") | border | flex,
}),
gauge(0.25) | color(Color::Red),
gauge(0.50) | color(Color::White),
gauge(0.75) | color(Color::Blue),
});
~~~
## Short gallery
#### DOM
This module defines a hierarchical set of Element. An Element manages layout\
and can be responsive to the terminal dimensions.
They are declared in [](https://arthursonzogni.github\
.io/FTXUI/elements_8hpp_source.html
)
Layout
Element can be arranged together:
- horizontally with `hbox`
- vertically with `vbox`
- inside a grid with `gridbox`
- wrap along one direction using the `flexbox`.
Element can become flexible using the the `flex` decorator.
[Example](https://arthursonzogni.github.io/FTXUI/examples_2dom_2vbox_hbox_8cp\
p-example.html) using `hbox`, `vbox` and `filler`.
[Example](https://arthursonzogni.github.io/FTXUI/examples_2dom_2gridbox_8cpp-\
example.html) using gridbox:
[Example](https://github.com/ArthurSonzogni/FTXUI/blob/master/examples/dom/hf\
low.cpp) using flexbox:
[See](https://arthursonzogni.github.io/FTXUI/examples_2dom_2hflow_8cpp-exampl\
e.html) also this [demo](https://arthursonzogni.github.io/FTXUI/examples/?fil\
e=component/flexbox).
Style
An element can be decorated using the functions:
- `bold`
- `italic`
- `dim`
- `inverted`
- `underlined`
- `underlinedDouble`
- `blink`
- `strikethrough`
- `color`
- `bgcolor`
- `hyperlink`
[Example](https://arthursonzogni.github.io/FTXUI/examples_2dom_2style_gallery\
_8cpp-example.html)
FTXUI supports the pipe operator. It means: `decorator1(decorator2(element))`\
and `element | decorator1 | decorator2` can be used.
Colors
FTXUI support every color palette:
Color [gallery](https://arthursonzogni.github.io/FTXUI/examples_2dom_2color_g\
allery_8cpp-example.html):
Border and separator
Use decorator border and element separator() to subdivide your UI:
```cpp
auto document = vbox({
text("top"),
separator(),
text("bottom"),
}) | border;
```
[Demo](https://arthursonzogni.github.io/FTXUI/examples_2dom_2separator_8cpp-e\
xample.html):
Text and paragraph
A simple piece of text is represented using `text("content")`.
To support text wrapping following spaces the following functions are\
provided:
```cpp
Element paragraph(std::string text);
Element paragraphAlignLeft(std::string text);
Element paragraphAlignRight(std::string text);
Element paragraphAlignCenter(std::string text);
Element paragraphAlignJustify(std::string text);
```
[Paragraph example](https://arthursonzogni.github.io/FTXUI/examples_2dom_2par\
agraph_8cpp-example.html)
Table
A class to easily style a table of data.
[Example](https://arthursonzogni.github.io/FTXUI/examples_2dom_2table_8cpp-ex\
ample.html):
Canvas
Drawing can be made on a Canvas, using braille, block, or simple characters:
Simple [example](https://github.com/ArthurSonzogni/FTXUI/blob/master/examples\
/dom/canvas.cpp):
Complex [examples](https://github.com/ArthurSonzogni/FTXUI/blob/master/exampl\
es/component/canvas_animated.cpp):
Gallery
[Gallery](https://arthursonzogni.github.io/FTXUI/examples_2component_2gallery\
_8cpp-example.html) of multiple components. ([demo](https://arthursonzogni.gi\
thub.io/FTXUI/examples/?file=component/gallery))
Radiobox
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2radiobo\
x_8cpp-example.html):
Checkbox
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2checkbo\
x_8cpp-example.html):
Input
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2input_8\
cpp-example.html):
Toggle
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2toggle_\
8cpp-example.html):
Slider
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2slider_\
8cpp-example.html):
Menu
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2menu_8c\
pp-example.html):
ResizableSplit
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2resizab\
le_split_8cpp-example.html):
Dropdown
[Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2dropdow\
n_8cpp-example.html):
Tab
[Vertical](https://arthursonzogni.github.io/FTXUI/examples_2component_2tab_ve\
rtical_8cpp-example.html):
[Horizontal](https://arthursonzogni.github.io/FTXUI/examples_2component_2tab_\
horizontal_8cpp-example.html):
{
static constexpr auto value{ &S::x };
};
```
or using a lambda:
```c++
template <>
struct glz::meta {
static constexpr auto value = [](auto& self) -> auto& { return self.x; };
};
```
# Error Handling
Glaze is safe to use with untrusted messages. Errors are returned as error\
codes, typically within a `glz::expected`, which behaves just like a\
`std::expected`.
> Glaze works to short circuit error handling, which means the parsing exits\
very rapidly if an error is encountered.
To generate more helpful error messages, call `format_error`:
```c++
auto pe = glz::read_json(obj, buffer);
if (pe) {
std::string descriptive_error = glz::format_error(pe, buffer);
}
```
This test case:
```json
{"Hello":"World"x, "color": "red"}
```
Produces this error:
```
1:17: expected_comma
{"Hello":"World"x, "color": "red"}
^
```
Denoting that x is invalid here.
# Type Support
## Array Types
Array types logically convert to JSON array values. Concepts are used to\
allow various containers and even user containers if they match standard\
library interfaces.
- `glz::array` (compile time mixed types)
- `std::tuple` (compile time mixed types)
- `std::array`
- `std::vector`
- `std::deque`
- `std::list`
- `std::forward_list`
- `std::span`
- `std::set`
- `std::unordered_set`
## Object Types
Object types logically convert to JSON object values, such as maps. Like\
JSON, Glaze treats object definitions as unordered maps. Therefore the order\
of an object layout does not have to match the same binary sequence in C++.
- `glz::object` (compile time mixed types)
- `std::map`
- `std::unordered_map`
- `std::pair` (enables dynamic keys in stack storage)
> `std::pair` is handled as an object with a single key and value, but when\
`std::pair` is used in an array, Glaze concatenates the pairs into a single\
object. `std::vector>` will serialize as a single object. If\
you don't want this behavior set the compile time option `.concatenate =\
false`.
## Variants
- `std::variant`
See [Variant Handling](./docs/variant-handling.md) for more information.
## Nullable Types
- `std::unique_ptr`
- `std::shared_ptr`
- `std::optional`
Nullable types may be allocated by valid input or nullified by the `null`\
keyword.
```c++
std::unique_ptr ptr{};
std::string buffer{};
expect(not glz::write_json(ptr, buffer));
expect(buffer == "null");
expect(not glz::read_json(ptr, "5"));
expect(*ptr == 5);
buffer.clear();
expect(not glz::write_json(ptr, buffer));
expect(buffer == "5");
expect(not glz::read_json(ptr, "null"));
expect(!bool(ptr));
```
## Enums
By default enums will be written and read in integer form. No `glz::meta` is\
necessary if this is the desired behavior.
However, if you prefer to use enums as strings in JSON, they can be\
registered in the `glz::meta` as follows:
```c++
enum class Color { Red, Green, Blue };
template <>
struct glz::meta {
using enum Color;
static constexpr auto value = enumerate(Red,
Green,
Blue
);
};
```
In use:
```c++
Color color = Color::Red;
std::string buffer{};
glz::write_json(color, buffer);
expect(buffer == "\"Red\"");
```
# JSON With Comments (JSONC)
Comments are supported with the specification defined here:\
[JSONC](https://github.com/stephenberry/JSONC)
Read support for comments is provided with `glz::read_jsonc` or\
`glz::read(...)`.
Comments may be included in the `glz::meta` description for your types. These\
comments can be written out to provide a description of your JSON interface.\
Calling `write_jsonc` as opposed to `write_json` will write out any comments\
included in the `meta` description.
```c++
struct thing {
double x{5.0};
int y{7};
};
template <>
struct glz::meta {
using T = thing;
static constexpr auto value = object(
&T::x, "x is a double"_c,
&T::y, "y is an int"_c
);
};
```
Prettified output:
```json
{
"x": 5 /*x is a double*/,
"y": 7 /*y is an int*/
}
```
> The `_c` is necessary if member object pointer names are reflected. You can\
also write `comment("x is a double")`
# Prettify JSON
Formatted JSON can be written out directly via a compile time option:
```c++
auto ec = glz::write(obj, buffer);
```
Or, JSON text can be formatted with the `glz::prettify_json` function:
```c++
std::string buffer = R"({"i":287,"d":3.14,"hello":"Hello World","arr":[1,2,3]\
})");
auto beautiful = glz::prettify_json(buffer);
```
`beautiful` is now:
```json
{
"i": 287,
"d": 3.14,
"hello": "Hello World",
"arr": [
1,
2,
3
]
}
```
# Minify JSON
To write minified JSON:
```c++
auto ec = glz::write_json(obj, buffer); // default is minified
```
To minify JSON text call:
```c++
std::string minified = glz::minify_json(buffer);
```
## Minified JSON Reading
If you wish require minified JSON or know your input will always be minified,\
then you can gain a little more performance by using the compile time option\
`.minified = true`.
```c++
auto ec = glz::read(obj, buffer);
```
## Boolean Flags
Glaze supports registering a set of boolean flags that behave as an array of\
string options:
```c++
struct flags_t {
bool x{ true };
bool y{};
bool z{ true };
};
template <>
struct glz::meta {
using T = flags_t;
static constexpr auto value = flags("x", &T::x, "y", &T::y, "z", &T::z);
};
```
Example:
```c++
flags_t s{};
expect(glz::write_json(s) == R"(["x","z"])");
```
Only `"x"` and `"z"` are written out, because they are true. Reading in the\
buffer will set the appropriate booleans.
> When writing BEVE, `flags` only use one bit per boolean (byte aligned).
## Logging JSON
Sometimes you just want to write out JSON structures on the fly as\
efficiently as possible. Glaze provides tuple-like structures that allow you\
to stack allocate structures to write out JSON with high speed. These\
structures are named `glz::obj` for objects and `glz::arr` for arrays.
Below is an example of building an object, which also contains an array, and\
writing it out.
```c++
auto obj = glz::obj{"pi", 3.14, "happy", true, "name", "Stephen", "arr",\
glz::arr{"Hello", "World", 2}};
std::string s{};
expect(not glz::write_json(obj, s));
expect(s == R"({"pi":3.14,"happy":true,"name":"Stephen","arr":["Hello","World\
",2]})");
```
> This approach is significantly faster than `glz::json_t` for generic JSON.\
But, may not be suitable for all contexts.
## Merge
`glz::merge` allows the user to merge multiple JSON object types into a\
single object.
```c++
glz::obj o{"pi", 3.141};
std::map map = {{"a", 1}, {"b", 2}, {"c", 3}};
auto merged = glz::merge{o, map};
std::string s{};
glz::write_json(merged, s); // will write out a single, merged object
// s is now: {"pi":3.141,"a":0,"b":2,"c":3}
```
> `glz::merge` stores references to lvalues to avoid copies
## Generic JSON
See [Generic JSON](./docs/generic-json.md) for `glz::json_t`.
```c++
glz::json_t json{};
std::string buffer = R"([5,"Hello World",{"pi":3.14}])";
glz::read_json(json, buffer);
assert(json[2]["pi"].get() == 3.14);
```
## Raw Buffer Performance
Glaze is just about as fast writing to a `std::string` as it is writing to a\
raw char buffer. If you have sufficiently allocated space in your buffer you\
can write to the raw buffer, as shown below, but it is not recommended.
```
glz::read_json(obj, buffer);
const auto n = glz::write_json(obj, buffer.data()).value_or(0);
buffer.resize(n);
```
## Compile Time Options
The `glz::opts` struct defines compile time optional settings for\
reading/writing.
Instead of calling `glz::read_json(...)`, you can call `glz::read(...)` and customize the options.
For example: `glz::read(...)` will\
turn off erroring on unknown keys and simple skip the items.
`glz::opts` can also switch between formats:
- `glz::read(...)` -> `glz::read_binary(...\
)`
- `glz::read(...)` -> `glz::read_json(...)`
## Available Compile Time Options
The struct below shows the available options and the default behavior.
```c++
struct opts {
uint32_t format = json;
bool comments = false; // Write out or support reading in JSONC style\
comments
bool error_on_unknown_keys = true; // Error when an unknown key is\
encountered
bool skip_null_members = true; // Skip writing out params in an object if\
the value is null
bool use_hash_comparison = true; // Will replace some string equality\
checks with hash checks
bool prettify = false; // Write out prettified JSON
bool minified = false; // Require minified input for JSON, which results in\
faster read performance
char indentation_char = ' '; // Prettified JSON indentation char
uint8_t indentation_width = 3; // Prettified JSON indentation size
bool new_lines_in_arrays = true; // Whether prettified arrays should have\
new lines for each element
bool shrink_to_fit = false; // Shrinks dynamic containers to new size to\
save memory
bool write_type_info = true; // Write type info for meta objects in variants
bool force_conformance = false; // Do not allow invalid json normally\
accepted such as nan, inf.
bool error_on_missing_keys = false; // Require all non nullable keys to be\
present in the object. Use
// skip_null_members = false to require\
nullable members
bool error_on_const_read =
false; // Error if attempt is made to read into a const value, by\
default the value is skipped without error
uint32_t layout = rowwise; // CSV row wise output/input
// The maximum precision type used for writing floats, higher precision\
floats will be cast down to this precision
float_precision float_max_write_precision{};
bool bools_as_numbers = false; // Read and write booleans with 1's and 0's
bool quoted_num = false; // treat numbers as quoted or array-like types as\
having quoted numbers
bool number = false; // read numbers as strings and write these string as\
numbers
bool raw = false; // write out string like values without quotes
bool raw_string = false; // do not decode/encode escaped characters for\
strings (improves read/write performance)
bool structs_as_arrays = false; // Handle structs (reading/writing) without\
keys, which applies to reflectable and
bool partial_read =
false; // Reads into only existing fields and elements and then exits\
without parsing the rest of the input
// glaze_object_t concepts
bool partial_read_nested = false; // Advance the partially read struct to\
the end of the struct
bool concatenate = true; // Concatenates ranges of std::pair into single\
objects when writing
bool hide_non_invocable =
true; // Hides non-invocable members from the cli_menu (may be applied\
elsewhere in the future)
};
```
> Many of these compile time options have wrappers to apply the option to\
only a single field. See [Wrappers](./docs/wrappers.md) for more details.
## Skip
It can be useful to acknowledge a keys existence in an object to prevent\
errors, and yet the value may not be needed or exist in C++. These cases are\
handled by registering a `glz::skip` type with the meta data.
```c++
struct S {
int i{};
};
template <>
struct glz::meta {
static constexpr auto value = object("key_to_skip", skip{}, &S::i);
};
```
```c++
std::string buffer = R"({"key_to_skip": [1,2,3], "i": 7})";
S s{};
glz::read_json(s, buffer);
// The value [1,2,3] will be skipped
expect(s.i == 7); // only the value i will be read into
```
## Hide
Glaze is designed to help with building generic APIs. Sometimes a value needs\
to be exposed to the API, but it is not desirable to read in or write out\
the value in JSON. This is the use case for `glz::hide`.
`glz::hide` hides the value from JSON output while still allowing API (and\
JSON pointer) access.
```c++
struct hide_struct {
int i = 287;
double d = 3.14;
std::string hello = "Hello World";
};
template <>
struct glz::meta {
using T = hide_struct;
static constexpr auto value = object(&T::i, //
&T::d, //
"hello", hide{&T::hello});
};
```
```c++
hide_struct s{};
auto b = glz::write_json(s);
expect(b == R"({"i":287,"d":3.14})"); // notice that "hello" is hidden from\
the output
```
## Quoted Numbers
You can parse quoted JSON numbers directly to types like `double`, `int`,\
etc. by utilizing the `glz::quoted` wrapper.
```c++
struct A {
double x;
std::vector y;
};
template <>
struct glz::meta {
static constexpr auto value = object("x", glz::quoted_num<&A::x>, "y",\
glz::quoted_num<&A::y>;
};
```
```json
{
"x": "3.14",
"y": ["1", "2", "3"]
}
```
The quoted JSON numbers will be parsed directly into the `double` and\
`std::vector`. The `glz::quoted` function works for nested objects\
and arrays as well.
## JSON Lines (NDJSON) Support
Glaze supports [JSON Lines](https://jsonlines.org) (or Newline Delimited\
JSON) for array-like types (e.g. `std::vector` and `std::tuple`).
```c++
std::vector x = { "Hello", "World", "Ice", "Cream" };
std::string s = glz::write_ndjson(x).value_or("error");
auto ec = glz::read_ndjson(x, s);
```
# More Features
### [Data Recorder](./docs/recorder.md)
### [Command Line Interface Menu](./docs/cli-menu.md)
### [JSON Include System](./docs/json-include.md)
### [JSON Pointer Syntax](./docs/json-pointer-syntax.md)
### [JSON-RPC 2.0](./docs/rpc/json-rpc.md)
### [JSON Schema](./docs/json-schema.md)
### [Shared Library API](./docs/glaze-interfaces.md)
### [Tagged Binary Messages](./docs/binary.md)
### [Thread Pool](./docs/thread-pool.md)
### [Time Trace Profiling](./docs/time-trace.md)
- Output performance profiles to JSON and visualize using [Perfetto](https://\
ui.perfetto.dev)
### [Wrappers](./docs/wrappers.md)
# Extensions
See the `ext` directory for extensions.
- [Eigen](https://gitlab.com/libeigen/eigen)
- [JSON-RPC 2.0](./docs/rpc/json-rpc.md)
- [Command Line Interface Menu (cli_menu)](./docs/cli-menu.md)
# License
Glaze is distributed under the MIT license with an exception for embedded\
forms:
> --- Optional exception to the license ---
>
> As an exception, if, as a result of your compiling your source code,\
portions of this Software are embedded into a machine-executable object form\
of such source code, you may redistribute such embedded portions in such\
object form without including the copyright and permission notices.
\
description-type: text/markdown;variant=GFM
package-description:
\
# libglaze - In memory, JSON and interface library for C++
This is a `build2` package for the [`glaze`](https://github.com/stephenberry/\
glaze)
C++ library. It provides an in memory, JSON and interface library for C++.
## Usage
To start using `libglaze` in your project, add the following `depends`
value to your `manifest`, adjusting the version constraint as appropriate:
```
depends: libglaze ^2.5.3
```
Then import the library in your `buildfile`:
```
import libs = libglaze%lib{glaze}
```
\
package-description-type: text/markdown;variant=GFM
url: https://github.com/stephenberry/glaze
package-url: https://github.com/build2-packaging/glaze
email: stephenberry.developer@gmail.com
package-email: packaging@build2.org; Mailing list.
depends: * build2 >= 0.16.0
depends: * bpkg >= 0.16.0
depends: libasio ^1.29.0 ? ($config.libglaze.repe_rpc)
tests: libglaze-tests == 2.9.5
bootstrap-build:
\
project = libglaze
using version
using config
using test
using install
using dist
\
root-build:
\
cxx.internal.scope = current
cxx.std = latest
using cxx
hxx{*}: extension = hpp
ixx{*}: extension = ipp
txx{*}: extension = tpp
cxx{*}: extension = cpp
config [bool] config.libglaze.repe_rpc ?= true
# The test target for cross-testing (running tests under Wine, etc).
#
test.target = $cxx.target
\
location: glaze/libglaze-2.9.5.tar.gz
sha256sum: d2194450c3b0e5c3d6597d749c1328c3dc5999c46204bedc8a14084040a5c584
:
name: libglaze
version: 4.0.0
type: lib,binless
language: c++
project: glaze
summary: JSON and interface library for C++
license: MIT; MIT License.
topics: json, json rpc 2.0, csv, beve, serialization
description:
\
# Glaze
One of the fastest JSON libraries in the world. Glaze reads and writes from\
object memory, simplifying interfaces and offering incredible performance.
Glaze also supports:
- [BEVE](https://github.com/beve-org/beve) (binary efficient versatile\
encoding)
- [CSV](./docs/csv.md) (comma separated value)
## With compile time reflection for MSVC, Clang, and GCC!
- Read/write aggregate initializable structs without writing any metadata or\
macros!
- See [example on Compiler Explorer](https://gcc.godbolt.org/z/T4To5fKfz)
## Highlights
- Pure, compile time reflection for structs
- Powerful meta specialization system for custom names and behavior
- JSON [RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259) compliance\
with UTF-8 validation
- Standard C++ library support
- Header only
- Direct to memory serialization/deserialization
- Compile time maps with constant time lookups and perfect hashing
- Powerful wrappers to modify read/write behavior ([Wrappers](./docs/wrappers\
.md))
- Use your own custom read/write functions ([Custom Read/Write](#custom-readw\
rite))
- [Handle unknown keys](./docs/unknown-keys.md) in a fast and flexible manner
- Direct memory access through [JSON pointer syntax](./docs/json-pointer-synt\
ax.md)
- [Binary data](./docs/binary.md) through the same API for maximum performance
- No exceptions (compiles with `-fno-exceptions`)
- If you desire helpers that throw for cleaner syntax see [Glaze\
Exceptions](./docs/exceptions.md)
- No runtime type information necessary (compiles with `-fno-rtti`)
- Rapid error handling with short circuiting
- [JSON-RPC 2.0 support](./docs/rpc/json-rpc.md)
- [JSON Schema generation](./docs/json-schema.md)
- Extremely portable, uses carefully optimized SWAR (SIMD Within A Register)\
for broad compatibility
- [Partial Read](./docs/partial-read.md) and [Partial Write](./docs/partial-w\
rite.md) support
- [CSV Reading/Writing](./docs/csv.md)
- [Much more!](#more-features)
See [DOCS](https://github.com/stephenberry/glaze/tree/main/docs) for more\
documentation.
## Performance
| Library | Roundtrip\
Time (s) | Write (MB/s) | Read (MB/s) |
| ------------------------------------------------------------ |\
------------------ | ------------ | ----------- |
| [**Glaze**](https://github.com/stephenberry/glaze) | **1.04** \
| **1366** | **1224** |
| [**simdjson (on demand)**](https://github.com/simdjson/simdjson) | **N/A** \
| **N/A** | **1198** |
| [**yyjson**](https://github.com/ibireme/yyjson) | **1.23** \
| **1005** | **1107** |
| [**daw_json_link**](https://github.com/beached/daw_json_link) | **2.93** \
| **365** | **553** |
| [**RapidJSON**](https://github.com/Tencent/rapidjson) | **3.65** \
| **290** | **450** |
| [**Boost.JSON (direct)**](https://boost.org/libs/json) | **4.76** \
| **199** | **447** |
| [**json_struct**](https://github.com/jorgen/json_struct) | **5.50** \
| **182** | **326** |
| [**nlohmann**](https://github.com/nlohmann/json) | **15.71** \
| **84** | **80** |
[Performance test code available here](https://github.com/stephenberry/json_p\
erformance)
*Performance caveats: [simdjson](https://github.com/simdjson/simdjson) and\
[yyjson](https://github.com/ibireme/yyjson) are great, but they experience\
major performance losses when the data is not in the expected sequence or\
any keys are missing (the problem grows as the file size increases, as they\
must re-iterate through the document).*
*Also, [simdjson](https://github.com/simdjson/simdjson) and\
[yyjson](https://github.com/ibireme/yyjson) do not support automatic escaped\
string handling, so if any of the currently non-escaped strings in this\
benchmark were to contain an escape, the escapes would not be handled.*
[ABC Test](https://github.com/stephenberry/json_performance) shows how\
simdjson has poor performance when keys are not in the expected sequence:
| Library | Read (MB/s) |
| ------------------------------------------------------------ | ----------- |
| [**Glaze**](https://github.com/stephenberry/glaze) | **678** |
| [**simdjson (on demand)**](https://github.com/simdjson/simdjson) | **93** \
|
## Binary Performance
Tagged binary specification: [BEVE](https://github.com/stephenberry/beve)
| Metric | Roundtrip Time (s) | Write (MB/s) | Read (MB/s) |
| --------------------- | ------------------ | ------------ | ----------- |
| Raw performance | **0.42** | **3235** | **2468** |
| Equivalent JSON data* | **0.42** | **3547** | **2706** |
JSON size: 670 bytes
BEVE size: 611 bytes
*BEVE packs more efficiently than JSON, so transporting the same data is even\
faster.
## Example
Your struct will automatically get reflected! No metadata is required by the\
user.
```c++
struct my_struct
{
int i = 287;
double d = 3.14;
std::string hello = "Hello World";
std::array arr = { 1, 2, 3 };
std::map map{{"one", 1}, {"two", 2}};
};
```
**JSON** (prettified)
```json
{
"i": 287,
"d": 3.14,
"hello": "Hello World",
"arr": [
1,
2,
3
],
"map": {
"one": 1,
"two": 2
}
}
```
**Write JSON**
```c++
my_struct s{};
std::string buffer = glz::write_json(s).value_or("error");
```
or
```c++
my_struct s{};
std::string buffer{};
auto ec = glz::write_json(s, buffer);
if (ec) {
// handle error
}
```
**Read JSON**
```c++
std::string buffer = R"({"i":287,"d":3.14,"hello":"Hello World","arr":[1,2,3]\
,"map":{"one":1,"two":2}})";
auto s = glz::read_json(buffer);
if (s) // check std::expected
{
s.value(); // s.value() is a my_struct populated from buffer
}
```
or
```c++
std::string buffer = R"({"i":287,"d":3.14,"hello":"Hello World","arr":[1,2,3]\
,"map":{"one":1,"two":2}})";
my_struct s{};
auto ec = glz::read_json(s, buffer); // populates s from buffer
if (ec) {
// handle error
}
```
### Read/Write From File
```c++
auto ec = glz::read_file_json(obj, "./obj.json", std::string{});
auto ec = glz::write_file_json(obj, "./obj.json", std::string{});
```
> [!IMPORTANT]
>
> The file name (2nd argument), must be null terminated.
## Compiler/System Support
- Requires C++23
- Tested for both 64bit and 32bit
- Only supports little-endian systems
[Actions](https://github.com/stephenberry/glaze/actions) build and test with\
[Clang](https://clang.llvm.org) (15+), [MSVC](https://visualstudio.microsoft\
.com/vs/features/cplusplus/) (2022), and [GCC](https://gcc.gnu.org) (12+) on\
apple, windows, and linux.
  
> Glaze seeks to maintain compatibility with the latest three versions of GCC\
and Clang, as well as the latest version of MSVC and Apple Clang.
### MSVC Compiler Flags
Glaze requires a C++ standard conformant pre-processor, which requires the\
`/Zc:preprocessor` flag when building with MSVC.
### SIMD CMake Options
The CMake has the option `glaze_ENABLE_AVX2`. This will attempt to use `AVX2`\
SIMD instructions in some cases to improve performance, as long as the\
system you are configuring on supports it. Set this option to `OFF` to\
disable the AVX2 instruction set, such as if you are cross-compiling for\
Arm. If you aren't using CMake the macro `GLZ_USE_AVX2` enables the feature\
if defined.
## How To Use Glaze
### [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.ht\
ml)
```cmake
include(FetchContent)
FetchContent_Declare(
glaze
GIT_REPOSITORY https://github.com/stephenberry/glaze.git
GIT_TAG main
GIT_SHALLOW TRUE
)
FetchContent_MakeAvailable(glaze)
target_link_libraries(${PROJECT_NAME} PRIVATE glaze::glaze)
```
### [Conan](https://conan.io)
- Included in [Conan Center](https://conan.io/center/) 
```
find_package(glaze REQUIRED)
target_link_libraries(main PRIVATE glaze::glaze)
```
### [build2](https://build2.org)
- Available on [cppget](https://cppget.org/libglaze)
```
import libs = libglaze%lib{glaze}
```
### Arch Linux
- AUR packages: [glaze](https://aur.archlinux.org/packages/glaze) and\
[glaze-git](https://aur.archlinux.org/packages/glaze-git)
### See this [Example Repository](https://github.com/stephenberry/glaze_examp\
le) for how to use Glaze in a new project
---
## See [FAQ](./docs/FAQ.md) for Frequently Asked Questions
# Explicit Metadata
If you want to specialize your reflection then you can optionally write the\
code below:
> This metadata is also necessary for non-aggregate initializable structs.
```c++
template <>
struct glz::meta {
using T = my_struct;
static constexpr auto value = object(
&T::i,
&T::d,
&T::hello,
&T::arr,
&T::map
);
};
```
## Local Glaze Meta
Glaze also supports metadata within its associated\
class:
```c++
struct my_struct
{
int i = 287;
double d = 3.14;
std::string hello = "Hello World";
std::array arr = { 1, 2, 3 };
std::map map{{"one", 1}, {"two", 2}};
struct glaze {
using T = my_struct;
static constexpr auto value = glz::object(
&T::i,
&T::d,
&T::hello,
&T::arr,
&T::map
);
};
};
```
See example:
```c++
struct custom_encoding
{
uint64_t x{};
std::string y{};
std::array z{};
void read_x(const std::string& s) {
x = std::stoi(s);
}
uint64_t write_x() {
return x;
}
void read_y(const std::string& s) {
y = "hello" + s;
}
auto& write_z() {
z[0] = 5;
return z;
}
};
template <>
struct glz::meta
{
using T = custom_encoding;
static constexpr auto value = object("x", custom<&T::read_x, &T::write_x>,\
//
"y", custom<&T::read_y, &T::y>, //
"z", custom<&T::z, &T::write_z>);
};
suite custom_encoding_test = [] {
"custom_reading"_test = [] {
custom_encoding obj{};
std::string s = R"({"x":"3","y":"world","z":[1,2,3]})";
expect(!glz::read_json(obj, s));
expect(obj.x == 3);
expect(obj.y == "helloworld");
expect(obj.z == std::array{1, 2, 3});
};
"custom_writing"_test = [] {
custom_encoding obj{};
std::string s = R"({"x":"3","y":"world","z":[1,2,3]})";
expect(!glz::read_json(obj, s));
std::string out{};
expect(not glz::write_json(obj, out));
expect(out == R"({"x":3,"y":"helloworld","z":[5,2,3]})");
};
};
```
{
static constexpr auto value{ &S::x };
};
```
or using a lambda:
```c++
template <>
struct glz::meta {
static constexpr auto value = [](auto& self) -> auto& { return self.x; };
};
```
# Error Handling
Glaze is safe to use with untrusted messages. Errors are returned as error\
codes, typically within a `glz::expected`, which behaves just like a\
`std::expected`.
> Glaze works to short circuit error handling, which means the parsing exits\
very rapidly if an error is encountered.
To generate more helpful error messages, call `format_error`:
```c++
auto pe = glz::read_json(obj, buffer);
if (pe) {
std::string descriptive_error = glz::format_error(pe, buffer);
}
```
This test case:
```json
{"Hello":"World"x, "color": "red"}
```
Produces this error:
```
1:17: expected_comma
{"Hello":"World"x, "color": "red"}
^
```
Denoting that x is invalid here.
# Input Buffer (Null) Termination
A non-const `std::string` is recommended for input buffers, as this allows\
Glaze to improve performance with temporary padding and the buffer will be\
null terminated.
## JSON
By default the option `null_terminated` is set to `true` and null-terminated\
buffers must be used when parsing JSON. The option can be turned off with a\
small loss in performance, which allows non-null terminated buffers:
```c++
constexpr glz::opts options{.null_terminated = false};
auto ec = glz::read(value, buffer); // read in a non-null terminated\
buffer
```
## BEVE
Null-termination is not required when parsing BEVE (binary). It makes no\
difference in performance.
## CSV
> [!WARNING]
>
> Currently, `null_terminated = false` is not valid for CSV parsing and\
buffers must be null terminated.
# Type Support
## Array Types
Array types logically convert to JSON array values. Concepts are used to\
allow various containers and even user containers if they match standard\
library interfaces.
- `glz::array` (compile time mixed types)
- `std::tuple` (compile time mixed types)
- `std::array`
- `std::vector`
- `std::deque`
- `std::list`
- `std::forward_list`
- `std::span`
- `std::set`
- `std::unordered_set`
## Object Types
Object types logically convert to JSON object values, such as maps. Like\
JSON, Glaze treats object definitions as unordered maps. Therefore the order\
of an object layout does not have to match the same binary sequence in C++.
- `glz::object` (compile time mixed types)
- `std::map`
- `std::unordered_map`
- `std::pair` (enables dynamic keys in stack storage)
> `std::pair` is handled as an object with a single key and value, but when\
`std::pair` is used in an array, Glaze concatenates the pairs into a single\
object. `std::vector>` will serialize as a single object. If\
you don't want this behavior set the compile time option `.concatenate =\
false`.
## Variants
- `std::variant`
See [Variant Handling](./docs/variant-handling.md) for more information.
## Nullable Types
- `std::unique_ptr`
- `std::shared_ptr`
- `std::optional`
Nullable types may be allocated by valid input or nullified by the `null`\
keyword.
```c++
std::unique_ptr ptr{};
std::string buffer{};
expect(not glz::write_json(ptr, buffer));
expect(buffer == "null");
expect(not glz::read_json(ptr, "5"));
expect(*ptr == 5);
buffer.clear();
expect(not glz::write_json(ptr, buffer));
expect(buffer == "5");
expect(not glz::read_json(ptr, "null"));
expect(!bool(ptr));
```
## Enums
By default enums will be written and read in integer form. No `glz::meta` is\
necessary if this is the desired behavior.
However, if you prefer to use enums as strings in JSON, they can be\
registered in the `glz::meta` as follows:
```c++
enum class Color { Red, Green, Blue };
template <>
struct glz::meta {
using enum Color;
static constexpr auto value = enumerate(Red,
Green,
Blue
);
};
```
In use:
```c++
Color color = Color::Red;
std::string buffer{};
glz::write_json(color, buffer);
expect(buffer == "\"Red\"");
```
# JSON With Comments (JSONC)
Comments are supported with the specification defined here:\
[JSONC](https://github.com/stephenberry/JSONC)
Read support for comments is provided with `glz::read_jsonc` or\
`glz::read(...)`.
# Prettify JSON
Formatted JSON can be written out directly via a compile time option:
```c++
auto ec = glz::write(obj, buffer);
```
Or, JSON text can be formatted with the `glz::prettify_json` function:
```c++
std::string buffer = R"({"i":287,"d":3.14,"hello":"Hello World","arr":[1,2,3]\
})");
auto beautiful = glz::prettify_json(buffer);
```
`beautiful` is now:
```json
{
"i": 287,
"d": 3.14,
"hello": "Hello World",
"arr": [
1,
2,
3
]
}
```
# Minify JSON
To write minified JSON:
```c++
auto ec = glz::write_json(obj, buffer); // default is minified
```
To minify JSON text call:
```c++
std::string minified = glz::minify_json(buffer);
```
## Minified JSON Reading
If you wish require minified JSON or know your input will always be minified,\
then you can gain a little more performance by using the compile time option\
`.minified = true`.
```c++
auto ec = glz::read(obj, buffer);
```
## Boolean Flags
Glaze supports registering a set of boolean flags that behave as an array of\
string options:
```c++
struct flags_t {
bool x{ true };
bool y{};
bool z{ true };
};
template <>
struct glz::meta {
using T = flags_t;
static constexpr auto value = flags("x", &T::x, "y", &T::y, "z", &T::z);
};
```
Example:
```c++
flags_t s{};
expect(glz::write_json(s) == R"(["x","z"])");
```
Only `"x"` and `"z"` are written out, because they are true. Reading in the\
buffer will set the appropriate booleans.
> When writing BEVE, `flags` only use one bit per boolean (byte aligned).
## Logging JSON
Sometimes you just want to write out JSON structures on the fly as\
efficiently as possible. Glaze provides tuple-like structures that allow you\
to stack allocate structures to write out JSON with high speed. These\
structures are named `glz::obj` for objects and `glz::arr` for arrays.
Below is an example of building an object, which also contains an array, and\
writing it out.
```c++
auto obj = glz::obj{"pi", 3.14, "happy", true, "name", "Stephen", "arr",\
glz::arr{"Hello", "World", 2}};
std::string s{};
expect(not glz::write_json(obj, s));
expect(s == R"({"pi":3.14,"happy":true,"name":"Stephen","arr":["Hello","World\
",2]})");
```
> This approach is significantly faster than `glz::json_t` for generic JSON.\
But, may not be suitable for all contexts.
## Merge
`glz::merge` allows the user to merge multiple JSON object types into a\
single object.
```c++
glz::obj o{"pi", 3.141};
std::map map = {{"a", 1}, {"b", 2}, {"c", 3}};
auto merged = glz::merge{o, map};
std::string s{};
glz::write_json(merged, s); // will write out a single, merged object
// s is now: {"pi":3.141,"a":0,"b":2,"c":3}
```
> `glz::merge` stores references to lvalues to avoid copies
## Generic JSON
See [Generic JSON](./docs/generic-json.md) for `glz::json_t`.
```c++
glz::json_t json{};
std::string buffer = R"([5,"Hello World",{"pi":3.14}])";
glz::read_json(json, buffer);
assert(json[2]["pi"].get() == 3.14);
```
## Raw Buffer Performance
Glaze is just about as fast writing to a `std::string` as it is writing to a\
raw char buffer. If you have sufficiently allocated space in your buffer you\
can write to the raw buffer, as shown below, but it is not recommended.
```
glz::read_json(obj, buffer);
const auto n = glz::write_json(obj, buffer.data()).value_or(0);
buffer.resize(n);
```
## Compile Time Options
The `glz::opts` struct defines compile time optional settings for\
reading/writing.
Instead of calling `glz::read_json(...)`, you can call `glz::read(...)` and customize the options.
For example: `glz::read(...)` will\
turn off erroring on unknown keys and simple skip the items.
`glz::opts` can also switch between formats:
- `glz::read(...)` -> `glz::read_beve(...)`
- `glz::read(...)` -> `glz::read_json(...)`
## Available Compile Time Options
The struct below shows the available options and the default behavior.
```c++
struct opts {
uint32_t format = json;
bool comments = false; // Support reading in JSONC style comments
bool error_on_unknown_keys = true; // Error when an unknown key is\
encountered
bool skip_null_members = true; // Skip writing out params in an object if\
the value is null
bool use_hash_comparison = true; // Will replace some string equality\
checks with hash checks
bool prettify = false; // Write out prettified JSON
bool minified = false; // Require minified input for JSON, which results in\
faster read performance
char indentation_char = ' '; // Prettified JSON indentation char
uint8_t indentation_width = 3; // Prettified JSON indentation size
bool new_lines_in_arrays = true; // Whether prettified arrays should have\
new lines for each element
bool shrink_to_fit = false; // Shrinks dynamic containers to new size to\
save memory
bool write_type_info = true; // Write type info for meta objects in variants
bool error_on_missing_keys = false; // Require all non nullable keys to be\
present in the object. Use
// skip_null_members = false to\
require nullable members
bool error_on_const_read =
false; // Error if attempt is made to read into a const value, by\
default the value is skipped without error
bool validate_skipped = false; // If full validation should be performed on\
skipped values
bool validate_trailing_whitespace =
false; // If, after parsing a value, we want to validate the trailing\
whitespace
uint8_t layout = rowwise; // CSV row wise output/input
// The maximum precision type used for writing floats, higher precision\
floats will be cast down to this precision
float_precision float_max_write_precision{};
bool bools_as_numbers = false; // Read and write booleans with 1's and 0's
bool escaped_unicode_key_conversion =
false; // JSON does not require escaped unicode keys to match with\
unescaped UTF-8
// This enables automatic escaped unicode unescaping and matching for keys\
in glz::object, but it comes at a
// performance cost.
bool quoted_num = false; // treat numbers as quoted or array-like types as\
having quoted numbers
bool number = false; // read numbers as strings and write these string as\
numbers
bool raw = false; // write out string like values without quotes
bool raw_string =
false; // do not decode/encode escaped characters for strings (improves\
read/write performance)
bool structs_as_arrays = false; // Handle structs (reading/writing) without\
keys, which applies
bool allow_conversions = true; // Whether conversions between convertible\
types are
// allowed in binary, e.g. double -> float
bool partial_read =
false; // Reads into only existing fields and elements and then exits\
without parsing the rest of the input
// glaze_object_t concepts
bool partial_read_nested = false; // Advance the partially read struct to\
the end of the struct
bool concatenate = true; // Concatenates ranges of std::pair into single\
objects when writing
bool hide_non_invocable =
true; // Hides non-invocable members from the cli_menu (may be applied\
elsewhere in the future)
};
```
> Many of these compile time options have wrappers to apply the option to\
only a single field. See [Wrappers](./docs/wrappers.md) for more details.
## JSON Conformance
By default Glaze is strictly conformant with the latest JSON standard except\
in two cases with associated options:
- `validate_skipped`
This option does full JSON validation for skipped values when parsing. This\
is not set by default because values are typically skipped when the user is\
unconcerned with them, and Glaze still validates for major issues. But, this\
makes skipping faster by not caring if the skipped values are exactly JSON\
conformant. For example, by default Glaze will ensure skipped numbers have\
all valid numerical characters, but it will not validate for issues like\
leading zeros in skipped numbers unless `validate_skipped` is on. Wherever\
Glaze parses a value to be used it is fully validated.
- `validate_trailing_whitespace`
This option validates the trailing whitespace in a parsed document. Because\
Glaze parses C++ structs, there is typically no need to continue parsing\
after the object of interest has been read. Turn on this option if you want\
to ensure that the rest of the document has valid whitespace, otherwise\
Glaze will just ignore the content after the content of interest has been\
parsed.
> [!NOTE]
>
> Glaze does not automatically unicode escape control characters (e.g.\
`"\x1f"` to `"\u001f"`), as this poses a risk of embedding null characters\
and other invisible characters in strings. A compile time option will be\
added to enable these conversions (open issue: [unicode escaped\
write](https://github.com/stephenberry/glaze/issues/812)), but it will not\
be the default behavior.
## Skip
It can be useful to acknowledge a keys existence in an object to prevent\
errors, and yet the value may not be needed or exist in C++. These cases are\
handled by registering a `glz::skip` type with the meta data.
See example:
```c++
struct S {
int i{};
};
template <>
struct glz::meta {
static constexpr auto value = object("key_to_skip", skip{}, &S::i);
};
```
```c++
std::string buffer = R"({"key_to_skip": [1,2,3], "i": 7})";
S s{};
glz::read_json(s, buffer);
// The value [1,2,3] will be skipped
expect(s.i == 7); // only the value i will be read into
```
See example:
```c++
struct hide_struct {
int i = 287;
double d = 3.14;
std::string hello = "Hello World";
};
template <>
struct glz::meta {
using T = hide_struct;
static constexpr auto value = object(&T::i, //
&T::d, //
"hello", hide{&T::hello});
};
```
```c++
hide_struct s{};
auto b = glz::write_json(s);
expect(b == R"({"i":287,"d":3.14})"); // notice that "hello" is hidden from\
the output
```
Glaze also supports metadata within its associated\
class:
```c++
struct my_struct
{
int i = 287;
double d = 3.14;
std::string hello = "Hello World";
std::array arr = { 1, 2, 3 };
std::map map{{"one", 1}, {"two", 2}};
struct glaze {
using T = my_struct;
static constexpr auto value = glz::object(
&T::i,
&T::d,
&T::hello,
&T::arr,
&T::map
);
};
};
```
See example:
```c++
struct custom_encoding
{
uint64_t x{};
std::string y{};
std::array z{};
void read_x(const std::string& s) {
x = std::stoi(s);
}
uint64_t write_x() {
return x;
}
void read_y(const std::string& s) {
y = "hello" + s;
}
auto& write_z() {
z[0] = 5;
return z;
}
};
template <>
struct glz::meta
{
using T = custom_encoding;
static constexpr auto value = object("x", custom<&T::read_x, &T::write_x>,\
//
"y", custom<&T::read_y, &T::y>, //
"z", custom<&T::z, &T::write_z>);
};
suite custom_encoding_test = [] {
"custom_reading"_test = [] {
custom_encoding obj{};
std::string s = R"({"x":"3","y":"world","z":[1,2,3]})";
expect(!glz::read_json(obj, s));
expect(obj.x == 3);
expect(obj.y == "helloworld");
expect(obj.z == std::array{1, 2, 3});
};
"custom_writing"_test = [] {
custom_encoding obj{};
std::string s = R"({"x":"3","y":"world","z":[1,2,3]})";
expect(!glz::read_json(obj, s));
std::string out{};
expect(not glz::write_json(obj, out));
expect(out == R"({"x":3,"y":"helloworld","z":[5,2,3]})");
};
};
```
{
static constexpr auto value{ &S::x };
};
```
or using a lambda:
```c++
template <>
struct glz::meta {
static constexpr auto value = [](auto& self) -> auto& { return self.x; };
};
```
# Error Handling
Glaze is safe to use with untrusted messages. Errors are returned as error\
codes, typically within a `glz::expected`, which behaves just like a\
`std::expected`.
> Glaze works to short circuit error handling, which means the parsing exits\
very rapidly if an error is encountered.
To generate more helpful error messages, call `format_error`:
```c++
auto pe = glz::read_json(obj, buffer);
if (pe) {
std::string descriptive_error = glz::format_error(pe, buffer);
}
```
This test case:
```json
{"Hello":"World"x, "color": "red"}
```
Produces this error:
```
1:17: expected_comma
{"Hello":"World"x, "color": "red"}
^
```
Denoting that x is invalid here.
# Input Buffer (Null) Termination
A non-const `std::string` is recommended for input buffers, as this allows\
Glaze to improve performance with temporary padding and the buffer will be\
null terminated.
## JSON
By default the option `null_terminated` is set to `true` and null-terminated\
buffers must be used when parsing JSON. The option can be turned off with a\
small loss in performance, which allows non-null terminated buffers:
```c++
constexpr glz::opts options{.null_terminated = false};
auto ec = glz::read(value, buffer); // read in a non-null terminated\
buffer
```
## BEVE
Null-termination is not required when parsing BEVE (binary). It makes no\
difference in performance.
## CSV
> [!WARNING]
>
> Currently, `null_terminated = false` is not valid for CSV parsing and\
buffers must be null terminated.
# Type Support
## Array Types
Array types logically convert to JSON array values. Concepts are used to\
allow various containers and even user containers if they match standard\
library interfaces.
- `glz::array` (compile time mixed types)
- `std::tuple` (compile time mixed types)
- `std::array`
- `std::vector`
- `std::deque`
- `std::list`
- `std::forward_list`
- `std::span`
- `std::set`
- `std::unordered_set`
## Object Types
Object types logically convert to JSON object values, such as maps. Like\
JSON, Glaze treats object definitions as unordered maps. Therefore the order\
of an object layout does not have to match the same binary sequence in C++.
- `glz::object` (compile time mixed types)
- `std::map`
- `std::unordered_map`
- `std::pair` (enables dynamic keys in stack storage)
> `std::pair` is handled as an object with a single key and value, but when\
`std::pair` is used in an array, Glaze concatenates the pairs into a single\
object. `std::vector>` will serialize as a single object. If\
you don't want this behavior set the compile time option `.concatenate =\
false`.
## Variants
- `std::variant`
See [Variant Handling](./docs/variant-handling.md) for more information.
## Nullable Types
- `std::unique_ptr`
- `std::shared_ptr`
- `std::optional`
Nullable types may be allocated by valid input or nullified by the `null`\
keyword.
```c++
std::unique_ptr ptr{};
std::string buffer{};
expect(not glz::write_json(ptr, buffer));
expect(buffer == "null");
expect(not glz::read_json(ptr, "5"));
expect(*ptr == 5);
buffer.clear();
expect(not glz::write_json(ptr, buffer));
expect(buffer == "5");
expect(not glz::read_json(ptr, "null"));
expect(!bool(ptr));
```
## Enums
By default enums will be written and read in integer form. No `glz::meta` is\
necessary if this is the desired behavior.
However, if you prefer to use enums as strings in JSON, they can be\
registered in the `glz::meta` as follows:
```c++
enum class Color { Red, Green, Blue };
template <>
struct glz::meta {
using enum Color;
static constexpr auto value = enumerate(Red,
Green,
Blue
);
};
```
In use:
```c++
Color color = Color::Red;
std::string buffer{};
glz::write_json(color, buffer);
expect(buffer == "\"Red\"");
```
# JSON With Comments (JSONC)
Comments are supported with the specification defined here:\
[JSONC](https://github.com/stephenberry/JSONC)
Read support for comments is provided with `glz::read_jsonc` or\
`glz::read(...)`.
# Prettify JSON
Formatted JSON can be written out directly via a compile time option:
```c++
auto ec = glz::write(obj, buffer);
```
Or, JSON text can be formatted with the `glz::prettify_json` function:
```c++
std::string buffer = R"({"i":287,"d":3.14,"hello":"Hello World","arr":[1,2,3]\
})");
auto beautiful = glz::prettify_json(buffer);
```
`beautiful` is now:
```json
{
"i": 287,
"d": 3.14,
"hello": "Hello World",
"arr": [
1,
2,
3
]
}
```
# Minify JSON
To write minified JSON:
```c++
auto ec = glz::write_json(obj, buffer); // default is minified
```
To minify JSON text call:
```c++
std::string minified = glz::minify_json(buffer);
```
## Minified JSON Reading
If you wish require minified JSON or know your input will always be minified,\
then you can gain a little more performance by using the compile time option\
`.minified = true`.
```c++
auto ec = glz::read(obj, buffer);
```
## Boolean Flags
Glaze supports registering a set of boolean flags that behave as an array of\
string options:
```c++
struct flags_t {
bool x{ true };
bool y{};
bool z{ true };
};
template <>
struct glz::meta {
using T = flags_t;
static constexpr auto value = flags("x", &T::x, "y", &T::y, "z", &T::z);
};
```
Example:
```c++
flags_t s{};
expect(glz::write_json(s) == R"(["x","z"])");
```
Only `"x"` and `"z"` are written out, because they are true. Reading in the\
buffer will set the appropriate booleans.
> When writing BEVE, `flags` only use one bit per boolean (byte aligned).
## Logging JSON
Sometimes you just want to write out JSON structures on the fly as\
efficiently as possible. Glaze provides tuple-like structures that allow you\
to stack allocate structures to write out JSON with high speed. These\
structures are named `glz::obj` for objects and `glz::arr` for arrays.
Below is an example of building an object, which also contains an array, and\
writing it out.
```c++
auto obj = glz::obj{"pi", 3.14, "happy", true, "name", "Stephen", "arr",\
glz::arr{"Hello", "World", 2}};
std::string s{};
expect(not glz::write_json(obj, s));
expect(s == R"({"pi":3.14,"happy":true,"name":"Stephen","arr":["Hello","World\
",2]})");
```
> This approach is significantly faster than `glz::json_t` for generic JSON.\
But, may not be suitable for all contexts.
## Merge
`glz::merge` allows the user to merge multiple JSON object types into a\
single object.
```c++
glz::obj o{"pi", 3.141};
std::map map = {{"a", 1}, {"b", 2}, {"c", 3}};
auto merged = glz::merge{o, map};
std::string s{};
glz::write_json(merged, s); // will write out a single, merged object
// s is now: {"pi":3.141,"a":0,"b":2,"c":3}
```
> `glz::merge` stores references to lvalues to avoid copies
## Generic JSON
See [Generic JSON](./docs/generic-json.md) for `glz::json_t`.
```c++
glz::json_t json{};
std::string buffer = R"([5,"Hello World",{"pi":3.14}])";
glz::read_json(json, buffer);
assert(json[2]["pi"].get() == 3.14);
```
## Raw Buffer Performance
Glaze is just about as fast writing to a `std::string` as it is writing to a\
raw char buffer. If you have sufficiently allocated space in your buffer you\
can write to the raw buffer, as shown below, but it is not recommended.
```
glz::read_json(obj, buffer);
const auto n = glz::write_json(obj, buffer.data()).value_or(0);
buffer.resize(n);
```
## Compile Time Options
The `glz::opts` struct defines compile time optional settings for\
reading/writing.
Instead of calling `glz::read_json(...)`, you can call `glz::read(...)` and customize the options.
For example: `glz::read(...)` will\
turn off erroring on unknown keys and simple skip the items.
`glz::opts` can also switch between formats:
- `glz::read(...)` -> `glz::read_beve(...)`
- `glz::read(...)` -> `glz::read_json(...)`
## Available Compile Time Options
The struct below shows the available options and the default behavior.
```c++
struct opts {
uint32_t format = json;
bool comments = false; // Support reading in JSONC style comments
bool error_on_unknown_keys = true; // Error when an unknown key is\
encountered
bool skip_null_members = true; // Skip writing out params in an object if\
the value is null
bool use_hash_comparison = true; // Will replace some string equality\
checks with hash checks
bool prettify = false; // Write out prettified JSON
bool minified = false; // Require minified input for JSON, which results in\
faster read performance
char indentation_char = ' '; // Prettified JSON indentation char
uint8_t indentation_width = 3; // Prettified JSON indentation size
bool new_lines_in_arrays = true; // Whether prettified arrays should have\
new lines for each element
bool shrink_to_fit = false; // Shrinks dynamic containers to new size to\
save memory
bool write_type_info = true; // Write type info for meta objects in variants
bool error_on_missing_keys = false; // Require all non nullable keys to be\
present in the object. Use
// skip_null_members = false to\
require nullable members
bool error_on_const_read =
false; // Error if attempt is made to read into a const value, by\
default the value is skipped without error
bool validate_skipped = false; // If full validation should be performed on\
skipped values
bool validate_trailing_whitespace =
false; // If, after parsing a value, we want to validate the trailing\
whitespace
uint8_t layout = rowwise; // CSV row wise output/input
// The maximum precision type used for writing floats, higher precision\
floats will be cast down to this precision
float_precision float_max_write_precision{};
bool bools_as_numbers = false; // Read and write booleans with 1's and 0's
bool escaped_unicode_key_conversion =
false; // JSON does not require escaped unicode keys to match with\
unescaped UTF-8
// This enables automatic escaped unicode unescaping and matching for keys\
in glz::object, but it comes at a
// performance cost.
bool quoted_num = false; // treat numbers as quoted or array-like types as\
having quoted numbers
bool number = false; // read numbers as strings and write these string as\
numbers
bool raw = false; // write out string like values without quotes
bool raw_string =
false; // do not decode/encode escaped characters for strings (improves\
read/write performance)
bool structs_as_arrays = false; // Handle structs (reading/writing) without\
keys, which applies
bool allow_conversions = true; // Whether conversions between convertible\
types are
// allowed in binary, e.g. double -> float
bool partial_read =
false; // Reads into only existing fields and elements and then exits\
without parsing the rest of the input
// glaze_object_t concepts
bool partial_read_nested = false; // Advance the partially read struct to\
the end of the struct
bool concatenate = true; // Concatenates ranges of std::pair into single\
objects when writing
bool hide_non_invocable =
true; // Hides non-invocable members from the cli_menu (may be applied\
elsewhere in the future)
};
```
> Many of these compile time options have wrappers to apply the option to\
only a single field. See [Wrappers](./docs/wrappers.md) for more details.
## JSON Conformance
By default Glaze is strictly conformant with the latest JSON standard except\
in two cases with associated options:
- `validate_skipped`
This option does full JSON validation for skipped values when parsing. This\
is not set by default because values are typically skipped when the user is\
unconcerned with them, and Glaze still validates for major issues. But, this\
makes skipping faster by not caring if the skipped values are exactly JSON\
conformant. For example, by default Glaze will ensure skipped numbers have\
all valid numerical characters, but it will not validate for issues like\
leading zeros in skipped numbers unless `validate_skipped` is on. Wherever\
Glaze parses a value to be used it is fully validated.
- `validate_trailing_whitespace`
This option validates the trailing whitespace in a parsed document. Because\
Glaze parses C++ structs, there is typically no need to continue parsing\
after the object of interest has been read. Turn on this option if you want\
to ensure that the rest of the document has valid whitespace, otherwise\
Glaze will just ignore the content after the content of interest has been\
parsed.
> [!NOTE]
>
> Glaze does not automatically unicode escape control characters (e.g.\
`"\x1f"` to `"\u001f"`), as this poses a risk of embedding null characters\
and other invisible characters in strings. A compile time option will be\
added to enable these conversions (open issue: [unicode escaped\
write](https://github.com/stephenberry/glaze/issues/812)), but it will not\
be the default behavior.
## Skip
It can be useful to acknowledge a keys existence in an object to prevent\
errors, and yet the value may not be needed or exist in C++. These cases are\
handled by registering a `glz::skip` type with the meta data.
See example:
```c++
struct S {
int i{};
};
template <>
struct glz::meta {
static constexpr auto value = object("key_to_skip", skip{}, &S::i);
};
```
```c++
std::string buffer = R"({"key_to_skip": [1,2,3], "i": 7})";
S s{};
glz::read_json(s, buffer);
// The value [1,2,3] will be skipped
expect(s.i == 7); // only the value i will be read into
```
See example:
```c++
struct hide_struct {
int i = 287;
double d = 3.14;
std::string hello = "Hello World";
};
template <>
struct glz::meta {
using T = hide_struct;
static constexpr auto value = object(&T::i, //
&T::d, //
"hello", hide{&T::hello});
};
```
```c++
hide_struct s{};
auto b = glz::write_json(s);
expect(b == R"({"i":287,"d":3.14})"); // notice that "hello" is hidden from\
the output
```
Glaze also supports metadata within its associated\
class:
```c++
struct my_struct
{
int i = 287;
double d = 3.14;
std::string hello = "Hello World";
std::array arr = { 1, 2, 3 };
std::map map{{"one", 1}, {"two", 2}};
struct glaze {
using T = my_struct;
static constexpr auto value = glz::object(
&T::i,
&T::d,
&T::hello,
&T::arr,
&T::map
);
};
};
```
ChaiScript
http://www.chaiscript.com
(c) 2009-2012 Jonathan Turner
(c) 2009-2017 Jason Turner
Release under the BSD license, see "license.txt" for details.
Introduction
============
[](https://gitter.im/ChaiScri\
pt/ChaiScript?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_con\
tent=badge)
ChaiScript is one of the only embedded scripting language designed from the
ground up to directly target C++ and take advantage of modern C++ development
techniques, working with the developer like he expects it to work. Being a
native C++ application, it has some advantages over existing embedded\
scripting
languages:
1. It uses a header-only approach, which makes it easy to integrate with
existing projects.
2. It maintains type safety between your C++ application and the user scripts.
3. It supports a variety of C++ techniques including callbacks, overloaded
functions, class methods, and stl containers.
Requirements
============
ChaiScript requires a C++14 compiler to build with support for variadic
templates. It has been tested with gcc 4.9 and clang 3.6 (with libcxx).
For more information see the build
[dashboard](http://chaiscript.com/ChaiScript-BuildResults/index.html).
Usage
=====
* Add the ChaiScript include directory to your project's header search path
* Add `#include 
](https://www.patreon.com/onqtam)
The framework is and will stay free but needs your support to sustain its\
development. There are lots of new features and maintenance to do. If you work for a\
company using **doctest** or have the means to do so, please consider\
financial support. Monthly donations via Patreon and one-offs via PayPal.
[
](https://www.paypal.me/onqtam/\
10)
A complete example with a self-registering test that compiles to an\
executable looks like this:
There are many C++ testing frameworks - [Catch](https://github.com/catchorg/C\
atch2), [Boost.Test](http://www.boost.org/doc/libs/1_64_0/libs/test/doc/html/\
index.html), [UnitTest++](https://github.com/unittest-cpp/unittest-cpp),\
[cpputest](https://github.com/cpputest/cpputest), [googletest](https://githu\
b.com/google/googletest) and [others](https://en.wikipedia.org/wiki/List_of_u\
nit_testing_frameworks#C.2B.2B).
The **key** differences between it and other testing frameworks are that it\
is light and unintrusive:
- Ultra light on compile times both in terms of [**including the\
header**](doc/markdown/benchmarks.md#cost-of-including-the-header) and\
writing [**thousands of asserts**](doc/markdown/benchmarks.md#cost-of-an-ass\
ertion-macro)
- Doesn't produce any warnings even on the [**most aggressive**](scripts/cmak\
e/common.cmake#L84) warning levels for **MSVC**/**GCC**/**Clang**
- Can remove **everything** testing-related from the binary with the\
[**```DOCTEST_CONFIG_DISABLE```**](doc/markdown/configuration.md#doctest_con\
fig_disable) identifier
- [**thread-safe**](doc/markdown/faq.md#is-doctest-thread-aware) - asserts\
can be used from multiple threads spawned from a single test case -\
[**example**](examples/all_features/concurrency.cpp)
- asserts can be used [**outside of a testing context**](doc/markdown/asserti\
ons.md#using-asserts-out-of-a-testing-context) - as a general purpose assert\
library - [**example**](examples/all_features/asserts_used_outside_of_tests.\
cpp)
- No global namespace pollution (everything is in ```doctest::```) & doesn't\
drag **any** headers with it
- [**Portable**](doc/markdown/features.md#extremely-portable) C++11 (use tag\
[**1.2.9**](https://github.com/doctest/doctest/tree/1.2.9) for C++98) with\
over 100 different CI builds (static analysis, sanitizers..)
- binaries (exe/dll) can use the test runner of another binary => tests in a\
single registry - [**example**](examples/executable_dll_and_plugin/)
This allows the framework to be used in more ways than any other - tests can\
be written directly in the production code!
*Tests can be a form of documentation and should be able to reside near the\
production code which they test.*
- This makes the barrier for writing tests **much lower** - you don't have\
to: **1)** make a separate source file **2)** include a bunch of stuff in it\
**3)** add it to the build system and **4)** add it to source control - You\
can just write the tests for a class or a piece of functionality at the\
bottom of its source file - or even header file!
- Tests in the production code can be thought of as documentation/up-to-date\
comments - showcasing the APIs
- Testing internals that are not exposed through the public API and headers\
is no longer a mind-bending exercise
- [**Test-driven development**](https://en.wikipedia.org/wiki/Test-driven_dev\
elopment) in C++ has never been easier!
The framework can be used just like any other without mixing production code\
and tests - check out the [**features**](doc/markdown/features.md).
**doctest** is modeled after [**Catch**](https://github.com/catchorg/Catch2)\
and some parts of the code have been taken directly - check out [**the\
differences**](doc/markdown/faq.md#how-is-doctest-different-from-catch).
[This table](https://github.com/martinmoene/catch-lest-other-comparison)\
compares **doctest** / [**Catch**](https://github.com/catchorg/Catch2) /\
[**lest**](https://github.com/martinmoene/lest) which are all very similar.
Checkout the [**CppCon 2017 talk**](https://cppcon2017.sched.com/event/BgsI/m\
ix-tests-and-production-code-with-doctest-implementing-and-using-the-fastest-\
modern-c-testing-framework) on [**YouTube**](https://www.youtube.com/watch?v=\
eH1CxEC29l8) to get a better understanding of how the framework works and\
read about how to use it in [**the JetBrains article**](https://blog.jetbrai\
ns.com/rscpp/better-ways-testing-with-doctest/) - highlighting the unique\
aspects of the framework! On a short description on how to use the framework\
along production code you could refer to [**this GitHub issue**](https://git\
hub.com/doctest/doctest/issues/252). There is also an [**older\
article**](https://accu.org/var/uploads/journals/Overload137.pdf) in the\
february edition of ACCU Overload 2017.
[](https://www.youtube.com/watch?v=eH1CxEC29l8)
Documentation
-------------
Project:
- [Features and design goals](doc/markdown/features.md) - the complete list\
of features
- [Community driven roadmap](https://github.com/doctest/doctest/issues/600) -\
upcoming features
- [Benchmarks](doc/markdown/benchmarks.md) - compile-time and runtime\
supremacy
- [Contributing](CONTRIBUTING.md) - how to make a proper pull request
- [Changelog](CHANGELOG.md) - generated changelog based on closed issues/PRs
Usage:
- [Tutorial](doc/markdown/tutorial.md) - make sure you have read it before\
the other parts of the documentation
- [Assertion macros](doc/markdown/assertions.md)
- [Test cases, subcases and test fixtures](doc/markdown/testcases.md)
- [Parameterized test cases](doc/markdown/parameterized-tests.md)
- [Command line](doc/markdown/commandline.md)
- [Logging macros](doc/markdown/logging.md)
- [```main()``` entry point](doc/markdown/main.md)
- [Configuration](doc/markdown/configuration.md)
- [String conversions](doc/markdown/stringification.md)
- [Reporters](doc/markdown/reporters.md)
- [Extensions](doc/markdown/extensions.md)
- [FAQ](doc/markdown/faq.md)
- [Build systems](doc/markdown/build-systems.md)
- [Examples](examples)
Bugs and feature proposals
------------
If you find a bug, report it!
If you have an idea on how to improve the project, be it anything from better\
documentation to adding new features, consider preparing a **feature\
proposal**.
We call it proposal because the word "request" has the wrong intention, no\
one will auto-magically fix it for you, but the idea can be discussed and\
accepted or rejected before **you** implement it.
Please make sure to read through the [**Contributing**](CONTRIBUTING.md) page\
before submitting any issue, the triaging procedure is documented there.
Contributing
------------
[
*glbinding* is a cross-platform C++ binding for the [OpenGL\
API](http://www.opengl.org).
[](https://travis-ci.org/cginternals/glbinding)
[](https://ci.appveyor.com/project/scheibel/glbin\
ding)
[](https://github.c\
om/Aaronepower/tokei)
[](https://glbinding.org/docs.html)
[](h\
ttps://github.com/cginternals/glbinding/wiki/Examples)
[](https:/\
/github.com/cginternals/glbinding/wiki/Tools)
[//]: # (HEADER_END)
*glbinding* leverages C++11 features like enum classes, lambdas, and variadic\
templates, instead of relying on macros;
all OpenGL symbols are real functions and variables.
It provides type-safe parameters, per-feature API headers, lazy function\
resolution, multi-context and multi-thread support, global and local\
function callbacks, meta information about the generated OpenGL binding and\
the OpenGL runtime, as well as tools and examples for quick-starting your\
projects.
Based on the OpenGL API specification ([gl.xml](https://github.com/KhronosGro\
up/OpenGL-Registry/blob/main/xml/gl.xml)) *glbinding* is generated using\
[python scripts and templates](https://github.com/cginternals/khrbinding-gen\
erator) that can be easily adapted to fit custom needs.
Code that is written using a typical C binding for OpenGL, e.g.,\
[GLEW](http://glew.sourceforge.net/), is fully compatible for the use with\
*glbinding* and causes no significant impact on runtime performance (see\
[compare example](https://github.com/cginternals/glbinding/wiki/examples#com\
pare)): just replace all includes to the former binding, replace the\
initialization code and *use* the appropriate API namespace, e.g., ```gl```\
for full availability of the OpenGL API.
```cpp
#include