Inspect

This page explains the inspection helper provided by rix/debug.

The examples use the public Rix facade:

cpp

#include <rix.hpp>

and access inspection through:

cpp

rix.debug.inspect

Inspection is useful when you want a clearer development-time view of a value while writing examples, debugging small tools, or checking package behavior.

For production application logs, prefer the Vix logging system.

Basic example

Create a file:

bash

mkdir -p ~/rix-debug-inspect
cd ~/rix-debug-inspect
touch inspect.cpp

Add:

cpp

#include <rix.hpp>

#include <string>

int main()
{
  const std::string package = "rix/debug";

  rix.debug.print("normal print:");
  rix.debug.print(package);

  rix.debug.print("----------------------------------------");
  rix.debug.print("inspect:");
  rix.debug.inspect(package);

  return 0;
}

Run it:

bash

vix run inspect.cpp

If Rix is not available yet for single-file usage:

bash

vix install -g rix/rix
vix run inspect.cpp

Expected output

The normal print output should look like this:

txt

normal print:
rix/debug
----------------------------------------
inspect:

The exact inspection output depends on the inspected value and the debug renderer.

`rix.debug.inspect`

Use:

cpp

rix.debug.inspect(value);

Example:

cpp

std::string package = "rix/debug";

rix.debug.inspect(package);

Use inspection when you want to see a value during development.

Inspect strings

cpp

std::string name = "Ada";

rix.debug.inspect(name);

Inspection is useful when you want output that makes the value clearer than a normal print.

For normal user-facing output, use:

cpp

rix.debug.print(name);

Inspect numbers

cpp

int rows = 3;
double ratio = 1.5;

rix.debug.inspect(rows);
rix.debug.inspect(ratio);

Use this while checking local values.

Inspect booleans

cpp

bool ready = true;
bool failed = false;

rix.debug.inspect(ready);
rix.debug.inspect(failed);

This is useful in small examples and tests.

Inspect formatted strings

Inspection works well with formatted output:

cpp

const auto message =
    rix.debug.format("Package: {}", "rix/debug");

rix.debug.inspect(message);

Use format to build the string.

Use inspect to view it during development.

Inspect print-style strings

You can also inspect a string created with sprint:

cpp

const auto line =
    rix.debug.sprint("rows:", 3);

rix.debug.inspect(line);

sprint creates a string using the same rendering style as print.

inspect displays the value.

Inspect CSV data

Inspection can help when checking parsed CSV values.

cpp

#include <rix.hpp>

int main()
{
  const auto table = rix.csv.parse(
      "name,language\n"
      "Ada,C++\n"
      "Gaspard,Vix\n");

  rix.debug.print("rows:", table.size());

  if (!table.empty())
  {
    rix.debug.inspect(table[0][0]);
  }

  return 0;
}

For full table output, a normal loop is often clearer:

cpp

for (const auto &row : table)
{
  for (const auto &field : row)
  {
    rix.debug.print(field);
  }
}

Inspect Auth values carefully

Inspection can help while developing Auth examples, but avoid sensitive values.

Safe examples:

cpp

auto auth = rix.auth.memory();

auto registered = auth.register_user({
    "ada@example.com",
    "correct-password"});

if (registered.ok())
{
  rix.debug.inspect(registered.value().email());
}

Avoid inspecting or printing:

txt

plain-text passwords
password hashes
session ids
raw token values

This matters especially in production, logs, screenshots, examples, and issue reports.

Inspect Auth errors

Errors are safer to inspect than secrets.

Example:

cpp

#include <rix.hpp>

int main()
{
  auto auth = rix.auth.memory();

  auto login = auth.login({
      "ada@example.com",
      "wrong-password"});

  if (login.failed())
  {
    const auto &error = login.error();

    rix.debug.eprint(
        "auth error:",
        rix.auth.error.to_string(error),
        error.message());

    return 1;
  }

  return 0;
}

For Auth errors, eprint is usually clearer than inspect.

Inspect PDF results

Inspection can be useful when checking PDF metadata or generated messages.

cpp

#include <rix.hpp>

int main()
{
  auto doc = rix.pdf.document();

  doc.set_title("Rix PDF Inspect Example");

  rix.debug.inspect(doc.metadata().title());

  auto saved = rix.pdf.make_text(
      "inspect.pdf",
      "Hello from rix.pdf",
      "Rix PDF");

  if (saved.failed())
  {
    rix.debug.eprint(
        "pdf error:",
        rix.pdf.error.to_string(saved.error()),
        saved.error().message());

    return 1;
  }

  rix.debug.print("created:", "inspect.pdf");

  return 0;
}

`inspect` vs `print`

Use print for simple output:

cpp

rix.debug.print("package:", "rix/debug");

Use inspect when you want to examine a value while developing:

cpp

rix.debug.inspect(package);

A simple rule:

txt

print   -> output a message
inspect -> examine a value

`inspect` vs `format`

Use format to build text:

cpp

const auto message =
    rix.debug.format("Package: {}", "rix/debug");

Use inspect to view a value:

cpp

rix.debug.inspect(message);

They solve different problems.

Complete example

cpp

#include <rix.hpp>

#include <string>

int main()
{
  const std::string package = "rix/debug";

  const auto formatted =
      rix.debug.format("Package: {}", package);

  const auto printed =
      rix.debug.sprint("Debug package:", package);

  rix.debug.print("normal output:");
  rix.debug.print(formatted);

  rix.debug.print("----------------------------------------");
  rix.debug.print("inspected values:");
  rix.debug.inspect(package);
  rix.debug.inspect(formatted);
  rix.debug.inspect(printed);

  return 0;
}

Run:

bash

vix run inspect.cpp

Use in a Vix project

Create a Vix application:

bash

vix new debug-inspect --app
cd debug-inspect

Add Rix:

bash

vix add rix/rix
vix install

In vix.app, make sure Rix is listed under deps:

txt

deps = [
  "rix/rix",
]

A small vix.app can look like this:

txt

name = "debug-inspect"
type = "executable"
standard = "c++20"
output_dir = "bin"

sources = [
  "src/main.cpp",
]

include_dirs = [
  "include",
  "src",
]

deps = [
  "rix/rix",
]

packages = [
  "vix",
]

links = [
  "vix::vix",
]

Then use inspection in src/main.cpp:

cpp

#include <rix.hpp>

#include <string>

int main()
{
  const std::string package = "rix/debug";

  rix.debug.inspect(package);

  return 0;
}

Build and run:

bash

vix build
vix run

Single-file usage

For small scripts, examples, and experiments:

bash

vix run inspect.cpp

If Rix is installed globally for single-file usage:

bash

vix install -g rix/rix
vix run inspect.cpp

For project usage, prefer:

bash

vix add rix/rix
vix install

and keep the dependency in vix.app:

txt

deps = [
  "rix/rix",
]

Use only Debug with the facade

If you want the rix.* facade style but only want Debug mounted, define the feature macro before including rix.hpp:

cpp

#define RIX_ENABLE_DEBUG
#include <rix.hpp>

#include <string>

int main()
{
  std::string package = "rix/debug";

  rix.debug.inspect(package);

  return 0;
}

When at least one RIX_ENABLE_* macro is defined, only selected modules are mounted.

Use the independent package

For independent usage, install:

bash

vix add rix/debug
vix install

In vix.app:

txt

deps = [
  "rix/debug",
]

Then include the independent package header:

cpp

#include <rix/debug.hpp>

Use this style when a project only needs Debug and does not need the full unified Rix facade.

For most application documentation, prefer:

cpp

#include <rix.hpp>

Logging note

rix.debug.inspect is for development-time inspection.

It is not production logging.

For real application logs, prefer the Vix logging system.

Use this rule:

txt

rix.debug.inspect -> examine values during development
Vix logging       -> application logs and runtime observability

Common mistakes

Using inspection as production logging

inspect is useful during development.

For deployed applications, prefer Vix logging.

Inspecting secrets

Do not inspect:

txt

plain-text passwords
password hashes
session ids
raw token values
private keys
API tokens

This matters especially with rix/auth.

Expecting `inspect` to format messages

inspect examines one value.

For messages, use print or format.

cpp

rix.debug.print("package:", "rix/debug");

const auto message =
    rix.debug.format("package: {}", "rix/debug");

Forgetting `deps`

For a Vix project, do not put Rix packages in packages.

Use:

txt

deps = [
  "rix/rix",
]

packages is for CMake package discovery.

deps is for Vix Registry packages.

What you should remember

Inspect a value:

cpp

rix.debug.inspect(value);

Use print for normal output:

cpp

rix.debug.print("package:", "rix/debug");

Use format to build strings:

cpp

auto message = rix.debug.format("Package: {}", "rix/debug");

Use inspection for development, examples, and local diagnostics.

Do not inspect secrets.

Prefer Vix logging for real application logs.

For a Vix project, install Rix:

bash

vix add rix/rix
vix install

and use:

txt

deps = [
  "rix/rix",
]

Next step

Continue with the debug API reference.

Next: API Reference

Inspect ​

Basic example ​

Expected output ​

rix.debug.inspect ​

Inspect strings ​

Inspect numbers ​

Inspect booleans ​

Inspect formatted strings ​

Inspect print-style strings ​

Inspect CSV data ​

Inspect Auth values carefully ​

Inspect Auth errors ​

Inspect PDF results ​

inspect vs print ​

inspect vs format ​

Complete example ​

Use in a Vix project ​

Single-file usage ​

Use only Debug with the facade ​

Use the independent package ​

Logging note ​

Common mistakes ​

Using inspection as production logging ​

Inspecting secrets ​

Expecting inspect to format messages ​

Forgetting deps ​

What you should remember ​

Next step ​

Inspect

Basic example

Expected output

`rix.debug.inspect`

Inspect strings

Inspect numbers

Inspect booleans

Inspect formatted strings

Inspect print-style strings

Inspect CSV data

Inspect Auth values carefully

Inspect Auth errors

Inspect PDF results

`inspect` vs `print`

`inspect` vs `format`

Complete example

Use in a Vix project

Single-file usage

Use only Debug with the facade

Use the independent package

Logging note

Common mistakes

Using inspection as production logging

Inspecting secrets

Expecting `inspect` to format messages

Forgetting `deps`

What you should remember

Next step