From 966eaa9bf1c3120d3ac55c99f89025a37fdb87a0 Mon Sep 17 00:00:00 2001 From: pommicket Date: Tue, 16 Sep 2025 21:49:54 -0400 Subject: Better READMEs --- .gitignore | 1 + CMakeLists.txt | 47 ++++++++++++++++++++++++++--------------------- README.md | 19 +++++++++++++++++-- cpp/README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 95 insertions(+), 23 deletions(-) diff --git a/.gitignore b/.gitignore index bc23d9f..c8c2413 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ Release .cache build* compile_commands.json +README.html diff --git a/CMakeLists.txt b/CMakeLists.txt index 4a3b896..bfe3ba0 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -3,6 +3,8 @@ cmake_minimum_required(VERSION 3.8...3.31) project(pom) option(LIBPOM_CXX "Build C++ library" ON) +option(LIBPOM_EXAMPLES "Build examples" ON) +option(LIBPOM_TESTS "Build tests" ON) set(CMAKE_C_STANDARD 11) set(CMAKE_CXX_STANDARD 17) @@ -19,21 +21,24 @@ add_library(pom-shared SHARED pom.c) set_target_properties(pom-shared PROPERTIES OUTPUT_NAME pom) # Tests -add_executable(tests tests/errors.c tests/location.c tests/parsing.c tests/interpretation.c tests/main.c) -target_include_directories(tests PRIVATE .) -target_link_libraries(tests pom) +if (LIBPOM_TESTS) + add_executable(tests tests/errors.c tests/location.c tests/parsing.c tests/interpretation.c tests/main.c) + target_include_directories(tests PRIVATE .) + target_link_libraries(tests pom) +endif() # Examples -add_executable(example_read_conf examples/read_conf.c) -target_include_directories(example_read_conf PRIVATE .) -target_link_libraries(example_read_conf pom) -add_executable(example_custom_alloc examples/custom_alloc.c) -target_include_directories(example_custom_alloc PRIVATE .) -target_link_libraries(example_custom_alloc pom) -add_executable(example_all_functions examples/all_functions.c) -target_include_directories(example_all_functions PRIVATE .) -target_link_libraries(example_all_functions pom) - +if (LIBPOM_EXAMPLES) + add_executable(example_read_conf examples/read_conf.c) + target_include_directories(example_read_conf PRIVATE .) + target_link_libraries(example_read_conf pom) + add_executable(example_custom_alloc examples/custom_alloc.c) + target_include_directories(example_custom_alloc PRIVATE .) + target_link_libraries(example_custom_alloc pom) + add_executable(example_all_functions examples/all_functions.c) + target_include_directories(example_all_functions PRIVATE .) + target_link_libraries(example_all_functions pom) +endif() # Installation install(TARGETS pom pom-shared DESTINATION lib) @@ -51,14 +56,14 @@ if (LIBPOM_CXX) target_link_libraries(pom++-shared PRIVATE pom-shared) # C++ Examples - add_executable(example++_read_conf cpp/examples/read_conf.cpp) - target_include_directories(example++_read_conf PRIVATE cpp) - target_link_libraries(example++_read_conf pom++) - - # C++ Examples - add_executable(example++_all_functions cpp/examples/all_functions.cpp) - target_include_directories(example++_all_functions PRIVATE cpp) - target_link_libraries(example++_all_functions pom++) + if (LIBPOM_EXAMPLES) + add_executable(example++_read_conf cpp/examples/read_conf.cpp) + target_include_directories(example++_read_conf PRIVATE cpp) + target_link_libraries(example++_read_conf pom++) + add_executable(example++_all_functions cpp/examples/all_functions.cpp) + target_include_directories(example++_all_functions PRIVATE cpp) + target_link_libraries(example++_all_functions pom++) + endif() # Installation install(TARGETS pom++ pom++-shared DESTINATION lib) diff --git a/README.md b/README.md index e9c37fa..47a7b1a 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,15 @@ # libpom -C parser for [POM configuration language](https://pom.computer) +C/C++ parser for [POM configuration language](https://pom.computer). + +This library is implemented in C, with C++-friendly bindings available as well. +See dedicated C++ README [here](cpp/README.md). ## About libpom has -- small size (~20KB code+data) +- small size (~30KB code+data) - support for custom memory allocation - no dependencies other than libc @@ -25,6 +28,18 @@ sudo make install You can also do `PROFILE=Debug make` to build with debug information. +The `Makefile` creates a build directory and runs cmake for you by default. +You can also do this manually for more control over cmake options: + +``` +mkdir special-build +cd special-build +# e.g. don't build C++ library, tests, or examples +cmake -DLIBPOM_CXX=OFF -DLIBPOM_TESTS=OFF -DLIBPOM_EXAMPLES=OFF -DCMAKE_BUILD_TYPE=Release .. +make -j`nproc` +``` + + ## Basic usage ```c diff --git a/cpp/README.md b/cpp/README.md index 5367cfe..9344934 100644 --- a/cpp/README.md +++ b/cpp/README.md @@ -3,3 +3,54 @@ C++ parser for the [POM configuration language](https://pom.computer). Requires at least C++17. + +## Building + +See [C building instructions](../README.md) (C++ library will be built alongside it automatically by default). + +## Basic usage + +```c++ +#include +#include + +int main(void) { + try { + pom::Configuration conf = pom::Configuration("conf.pom", nullptr); + auto indentation_type = conf.get("indentation-type"); + if (indentation_type.has_value()) + std::cout << "Indenting with " << indentation_type.value() << "\n"; + else + std::cout << "No indentation type set!\n"; + } catch (pom::Error &error) { + // Parsing error! + std::cerr << error << "\n"; + } +} +``` + +Assuming you have run `make install`, you just need to add `-l:libpom++.a -l:libpom.a` (or `-lpom++ -lpom` to +use the shared library) to your compiler flags. + + +See `examples/` directory for more examples. + +## Contributing + +Contributions are welcome, including bug fixes, examples, improvements +to documentation or code readability, and error message translations (see `../errors.c`). + +## License + +```text +Permission to use, copy, modify, and/or distribute this software for +any purpose with or without fee is hereby granted. + +THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL +WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES +OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE +FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY +DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN +AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT +OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +``` -- cgit v1.2.3