lipsum-cpp

A header-only library written in C++ for generating sample lorem-ipsum text. Useful for prototyping apps, UI testing, benchmarking Markdown/HTML/XML/JSON parser libraries, and anywhere placeholder text is needed.

Features

• Header-only (also possible to use an amalgamated single-header lipsum.hpp)
• Extremely fast and very lightweight (see Benchmarks section)
• Zero third-party dependencies outside of build dependencies
• Multi-source lorem-ipsum generation including built-in lorem-ipsum, cat-ipsum, dog-ipsum, and corporate-ipsum as well as custom sources
• Markdown, HTML, XML, JSON, and code block (C++ and Python snippet) generation
• Customizable number of paragraphs, sentences, sentence fragments, and words
• CLI tool for integration in projects
• Extensive documentation via Doxygen
• C++, C, and JavaScript support (static/shared library, wrapper, and Emscripten module builds supported)
• CMake support for easy integration
• Example code and live demo available

Installation

lipsum-cpp has been mainly tested on Linux (Debian 13) and WebAssembly, and there have been passing CI/CD on Windows and macOS.

Build prerequisites

• A C/C++ compiler (e.g. GCC, MSVC, Clang) supporting C++20 or newer
• Recommended:
  • CMake (>= 3.20)
  • Make
  • another build system (e.g. Ninja, MSBuild, ...)
  • Git
• Optional:
  • Emscripten (>= 2.0 required, >= 3.x recommended)
  • 7-Zip
  • Doxygen
  • clang-format
  • clang-tidy
  • libxml2 (for ParserStressTest.cpp)
  • libjson-c (for ParserStressTest.cpp)
  • zlib (for CompressionBenchmarks.cpp)
  • quom

Quick Start

Using CMake (Recommended)

1. Add to your CMake project:

   include(FetchContent)
   
   FetchContent_Declare(
       lipsum-cpp
       GIT_REPOSITORY https://github.com/LambBread/lipsum-cpp.git
       GIT_TAG master
   )
   FetchContent_MakeAvailable(lipsum-cpp)
   # ...
   target_link_libraries(your_target PRIVATE lipsum-cpp)

2. To build as a static or shared library with C wrapper support (optional):
   Set LPSM_BUILD_STATIC=ON or LPSM_BUILD_SHARED=ON in your CMake options. For C wrapper builds, also set LPSM_BUILD_CWRAPPER=ON.

Alternatively, instead of FetchContent, use add_subdirectory:

add_subdirectory("/path/to/lipsum-cpp/")
# ...
target_link_libraries(your_target PRIVATE lipsum-cpp)

Header-only usage

Simply copy src/ into your source tree or download and extract an amalgamated single-header release from the Releases section (lipsum-pkg.zip).

Amalgamating

Install quom via pip, such as with:

# may need to use venv on some systems

pip install --user quom

At the root of the project, run make amalgamate, make pkg, or cmake --build build --target amalgamate.

System-wide installation (Optional)

# Debian-based
sudo apt install ./lipsum-cpp-x.x.x-Linux.deb

# RHEL/Fedora-based
sudo dnf install ./lipsum-cpp-x.x.x-Linux.rpm

# Arch-based
sudo pacman -U ./lipsum-cpp-x.x.x-x-x86_64.pkg.tar.zst

# Windows
# Run the .msi file provided.

# macOS
# Install the .dmg provided.

# Cross-platform (build from source)
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DLPSM_BUILD_CLI=ON <... your CMake options here>
cmake --build build --config Release
sudo cmake --install build

From here, it is possible to use find_package in CMake projects.

find_package(lipsum-cpp REQUIRED)
# ...
target_link_libraries(your_target PRIVATE lipsum-cpp::lipsum-cpp)

Usage

Basic example

LIPSUM_IMPLEMENTATION must be defined in exactly one file per project for header-only usage.

#ifndef LIPSUM_BUILD_STATIC
#    define LIPSUM_IMPLEMENTATION // only for header-only usage
#endif

#include <lipsum.hpp>

int main()
{
    // Create a generator.
    lpsm::Generator gen;

    // Generate 5 words.
    std::cout << gen.word(5) << '\n';

    // Generate a sentence fragment.
    std::cout << gen.fragment() << '\n';

    // Generate 6 sentences.
    std::cout << gen.sentence(6, lpsm::USELIPSUM) << '\n';

    // Generate 3 paragraphs.
    std::cout << gen.paragraph(3, lpsm::USELIPSUM);

    // Generate a text.
    std::cout << gen.text(lpsm::USELIPSUM);

    return 0;
}

See this example live

Advanced example

#ifndef LIPSUM_BUILD_STATIC
#    define LIPSUM_IMPLEMENTATION // only for header-only usage
#endif

#include <lipsum.hpp>

int main()
{
    // Create a generator using corporate ipsum and the specified seed.
    lpsm::Generator gen("corpo", 1234);

    // Change to 6-9 words per sentence fragment,
    // 3-6 sentence fragments per sentence,
    // 6-9 items in JSON arrays/objects
    gen.change_setting("word", 6, 9);
    gen.change_setting("frag", 3, 6);
    gen.change_setting("jsonLength", 6, 9);

    // Generate a URL.
    std::cout << gen.url() << '\n';

    // Generate a plain URL.
    std::cout << gen.plain_url() << '\n';

    // Generate an email.
    std::cout << gen.email() << '\n';

    // Generate a slug.
    std::cout << gen.slug('_') << '\n';
    
    // Generate a camel case case slug.
    std::cout << gen.case_slug(lpsm::CaseSlugCase::CamelCase) << '\n';

    // Generate a scramble.
    std::cout << gen.scramble(24, 'a', 'z') << '\n';
    
    // Generate a C++ psuedocode block.
    std::cout << gen.code(lpsm::CodeLanguage::Cpp) << '\n';

    // Generate 5 Markdown paragraphs.
    std::cout << gen.fmt_paragraph(5, lpsm::USELIPSUM, lpsm::MARKDOWN);

    // Generate a Markdown document with 20 elements.
    std::cout << gen.fmt_text(20, lpsm::MARKDOWN);

    // Generate a Markdown subtitle.
    std::cout << gen.fmt_header(2, lpsm::MARKDOWN);

    // Generate an italic Markdown sentence.
    std::cout << gen.fmt_emphasis(lpsm::ITALIC, lpsm::MARKDOWN) << '\n';

    // Generate a Markdown link.
    std::cout << gen.fmt_link(lpsm::MARKDOWN) << '\n';

    // Generate an ordered Markdown list.
    std::cout << gen.fmt_list(lpsm::ORDERED, lpsm::MARKDOWN);

    // Generate 5 HTML paragraphs.
    std::cout << gen.fmt_paragraph(5, lpsm::USELIPSUM, lpsm::HTML);

    // Generate an HTML document with 20 elements.
    std::cout << gen.fmt_text(20, lpsm::HTML);

    // Generate an XML document with 40 "choices".
    std::cout << gen.xml(40) << '\n';

    // Generate a JSON object with a max recursion of 5.
    std::cout << gen.json(0, 5, lpsm::OBJECT) << '\n';

    // Generate a JSON value with a max recursion of 5.
    std::cout << gen.json_value(0, 5) << '\n';

    return 0;
}

See this example live

Binding usage

For C projects, use the C wrapper (lipsum.h) and call functions with the lpsm_ prefix. See the examples/README.md for details. For JavaScript projects, usage is similar to the C wrapper. See the src/jsbind/README.md and example for details.

Examples & Documentation

• See the examples/ folder for sample code.
• A live demo of these examples are available here. These can also be built with make em_build or make pkg.
• The documentation is available here. It can also be generated via Doxygen by running make or make pkg.

Benchmarks

All tested with CMake Release build type, with default lpsm::Generator arguments.

Medium-end environment

Debian 13, 8GB DDR4 RAM, Intel i3-6100 (4-core) @ 3.7GHz:

• 23,825,730 words/second
• 1,129,105 sentences/second
• 165,406 paragraphs/second
• 146,052 Markdown paragraphs/second
• 294,004 Markdown "elements"/second

Low-end environment

Puppy Linux (BookwormPup32), 1GB DDR2 RAM, Intel Centrino Duo (2-core) @ 1.6GHz:

• 2,767,236 words/second
• 105,033 sentences/second
• 15,833 paragraphs/second
• 15,267 Markdown paragraphs/second
• 27,966 Markdown "elements"/second

Credits

• scripts/lipsum.txt was generated with lipsum.com.
• scripts/catipsum.txt was generated with catipsum.com.
• scripts/dogipsum.txt was generated with doggoipsum.com.
• scripts/corporateipsum.txt was generated with corporate-ipsum.com.

---

Licensed under 0BSD. (see LICENSE.md for details)

Created by LambBread