simple_qr

Overview

simple_qr generates QR codes from text data using pure Eiffel. It implements the complete QR code specification including all 40 versions, four error correction levels, automatic mode detection, and Reed-Solomon error correction.

Quick Start

Installation

Set the ecosystem environment variable and add to your ECF:

-- Set SIMPLE_EIFFEL=D:\prod (or your installation path)
<library name="simple_qr" location="$SIMPLE_EIFFEL/simple_qr/simple_qr.ecf"/>

Basic Usage

local
    qr: SIMPLE_QR
do
    create qr.make
    qr.set_data ("Hello World")
    qr.generate

    if qr.is_generated then
        print (qr.to_ascii_art)
    end
end

With Error Correction

local
    qr: SIMPLE_QR
do
    -- Use high error correction (30% recovery)
    create qr.make_with_level (4)  -- Level H
    qr.set_data ("https://example.com")
    qr.generate

    -- Save to PBM image file
    qr.save_pbm ("qrcode.pbm")
end

Design by Contract: Proven Correctness

What makes simple_qr special is its aggressive use of Design by Contract. Every class has contracts that capture the mathematical and logical specifications. These aren't just documentation—they're executable code that verifies correctness on every operation.

Galois Field Contracts (QR_GALOIS)

Reed-Solomon error correction requires arithmetic in GF(2^8). Our contracts verify field axioms:

add (a_x, a_y: INTEGER): INTEGER
    require
        x_in_field: a_x >= 0 and a_x <= 255
        y_in_field: a_y >= 0 and a_y <= 255
    ensure
        result_in_field: Result >= 0 and Result <= 255
        commutative: Result = a_y.bit_xor (a_x)
        additive_identity_x: a_y = 0 implies Result = a_x
        self_inverse: a_x = a_y implies Result = 0

Matrix Construction Contracts (QR_MATRIX)

Contracts verify the QR specification is followed exactly:

make (a_version: INTEGER)
    require
        version_valid: a_version >= 1 and a_version <= 40
    ensure
        size_correct: size = 17 + (a_version * 4)
        all_modules_light: across 1 |..| size as r all
            across 1 |..| size as c all not modules.item (r, c) end end

place_finder_patterns
    ensure
        top_left_center_dark: modules.item (4, 4)
        top_right_center_dark: modules.item (4, size - 3)
        bottom_left_center_dark: modules.item (size - 3, 4)

Class Invariants

Every class maintains invariants that can never be violated:

invariant
    -- SIMPLE_QR: State always valid
    error_correction_valid: error_correction >= Level_l and error_correction <= Level_h
    version_valid: version >= 0 and version <= 40
    generated_matrix_valid: attached matrix as m implies (m.size >= 21 and m.size <= 177)

    -- QR_GALOIS: Lookup tables sized correctly
    exp_table_size: exp_table.count = 512
    log_table_size: log_table.count = 256

    -- QR_MATRIX: Matrix dimensions consistent
    size_formula: size = 17 + (version * 4)
    modules_square: modules.height = size and modules.width = size

Comprehensive Test Suite

64 tests verify every component of the library. Tests are organized to prove mathematical properties, verify boundary conditions, and exercise the complete QR generation pipeline.

cd simple_qr
ec.exe -batch -config simple_qr.ecf -target simple_qr_tests -c_compile
./EIFGENs/simple_qr_tests/W_code/simple_qr.exe

Test Coverage by Component

Sample Test: Galois Field Axioms

test_galois_additive_identity
        -- Test: a + 0 = a for all a (XOR with 0 is identity)
    local
        g: QR_GALOIS
        i: INTEGER
    do
        create g.make
        from i := 0 until i > 255 loop
            assert_equal ("add_zero_" + i.out, i, g.add (i, 0))
            i := i + 1
        end
    end

API Reference

SIMPLE_QR (Main Facade)

The primary class for QR code generation. Use this for all typical operations.

Error Correction Levels

Internal Classes

These classes are used internally but can be accessed for advanced use cases:

Architecture

simple_qr/
├── src/
│   ├── simple_qr.e           -- Main facade (public API)
│   ├── qr_encoder.e          -- Data encoding (numeric/alphanumeric/byte)
│   ├── qr_error_correction.e -- Reed-Solomon EC generation
│   ├── qr_galois.e           -- GF(2^8) field arithmetic
│   ├── qr_matrix.e           -- QR matrix construction and masking
│   └── qr_version.e          -- Version/capacity calculations
├── testing/
│   ├── lib_tests.e           -- 64 comprehensive tests
│   └── test_app.e            -- Test runner
├── docs/
│   └── index.html            -- This documentation
└── simple_qr.ecf             -- EiffelStudio project file