README.md

Below is a polished, reference‑quality README.md you can drop directly into a GitHub repository.
It’s structured, logical, developer‑friendly, and explains the full CANG language‑selection system with clarity and purpose.

---

CANG — Configurable Alphanumeric Generator

CANG is a lightweight, extensible system for generating strings based on predefined language profiles.
Each profile defines a character set, a logical type, and a semantic description, allowing developers to produce output strings that match specific formatting, security, or compatibility requirements.

CANG is ideal for:

• Token generation
• File‑ID or resource‑ID creation
• URL‑safe identifiers
• Password or key generation
• Systems requiring predictable, rule‑driven output formats

---

🔧 Core Concept

CANG operates on a simple principle:

Choose a Language → Load Its Character Set → Generate a Compatible Output String

Each Language is defined by:

• Language Name — Human‑readable identifier
• Language Type — Regex‑style character class
• Language Description — Semantic explanation of intended use

---

📚 Language Reference Table

ID	Language Name	Language Type	Description
1	Alphabet_Upper	[A-Z]	Alphabetical → Simple: Capital letters
2	Alphabet_Lower	[a-z]	Alphabetical → Simple: Small letters
3	Alphabet_Mix	[A-Z,a-z]	Alphabetical → Mix: Capital and Small letters
4	Numeric	[0-9]	Numerical → Simple
5	Alphabet_Upper_Num	[A-Z,0-9]	Alphabetical + Numerical → Simple: Capital letters (Microsoft/Megaupload‑style)
6	Alphabet_Lower_Num	[a-z,0-9]	Alphabetical + Numerical → Simple: Small letters
7	Alphabet_Mix_Num	[A-Z,a-z,0-9]	Alphabetical + Numerical → Mix: Capital and Small letters
8	Alphabet_Mix_Num_SpecialShort	[A-Z,a-z,0-9,-_]	Mix + Short Special chars (YouTube‑style)
9	Alphabet_Mix_Num_SpecialFull	[A-Z,a-z,0-9,-_]	Mix + Full Special chars (Safe Password)

---

🧠 Language Selector Logic

CANG uses a simple numeric selector to load the correct language profile.

Example Selector Map

$CANG_Language = [
    1 => 'Alphabet_Upper',
    2 => 'Alphabet_Lower',
    3 => 'Alphabet_Mix',
    4 => 'Numeric',
    5 => 'Alphabet_Upper_Num',
    6 => 'Alphabet_Lower_Num',
    7 => 'Alphabet_Mix_Num',
    8 => 'Alphabet_Mix_Num_SpecialShort',
    9 => 'Alphabet_Mix_Num_SpecialFull'
];

Character Set Definitions

$CANG_Type = [
    1 => '[A-Z]',
    2 => '[a-z]',
    3 => '[A-Z,a-z]',
    4 => '[0-9]',
    5 => '[A-Z,0-9]',
    6 => '[a-z,0-9]',
    7 => '[A-Z,a-z,0-9]',
    8 => '[A-Z,a-z,0-9,-_]',
    9 => '[A-Z,a-z,0-9,-_]'
];

Descriptions

$CANG_Description = [
    1 => 'Alphabetical -> Simple: Capital letters',
    2 => 'Alphabetical -> Simple: Small letters',
    3 => 'Alphabetical -> Mix: Capital and Small letters',
    4 => 'Numerical -> Simple',
    5 => 'Alphabetical And Numerical -> Simple: Capital letters (Microsoft/Megaupload.com)',
    6 => 'Alphabetical and Numerical -> Simple: Small letters',
    7 => 'Alphabetical and Numerical -> Mix: Capital and Small letters',
    8 => 'Alphabetical and Numerical -> Mix: Capital/Small letters plus Short Special chars (YouTube.com)',
    9 => 'Alphabetical and Numerical -> Mix: Capital/Small letters plus Full Special chars (Safe Password)'
];

---

⚙️ How CANG Works Internally

1. Select a Language ID

$languageID = 7; // Alphabet_Mix_Num

2. Load the Character Set

$charset = $CANG_Type[$languageID];

3. Convert Character Class to Actual Characters

Example logic:

function expandCharset($pattern) {
    $chars = '';

    if (strpos($pattern, 'A-Z') !== false) {
        $chars .= implode('', range('A', 'Z'));
    }
    if (strpos($pattern, 'a-z') !== false) {
        $chars .= implode('', range('a', 'z'));
    }
    if (strpos($pattern, '0-9') !== false) {
        $chars .= implode('', range('0', '9'));
    }
    if (strpos($pattern, '-') !== false) {
        $chars .= '-';
    }
    if (strpos($pattern, '_') !== false) {
        $chars .= '_';
    }

    return $chars;
}

4. Generate Output String

function CANG_Generate($charset, $length = 12) {
    $output = '';
    $max = strlen($charset) - 1;

    for ($i = 0; $i < $length; $i++) {
        $output .= $charset[random_int(0, $max)];
    }

    return $output;
}

5. Full Example

$charset = expandCharset($CANG_Type[$languageID]);
$token = CANG_Generate($charset, 16);

echo $token; // Example: Ab9ZtQ3mP1xR7cD2

---

🚀 Use Cases

Use Case	Recommended Language
Simple uppercase IDs	Alphabet_Upper
Lowercase slugs	Alphabet_Lower
Human‑friendly mixed IDs	Alphabet_Mix
Numeric codes	Numeric
Legacy file hosts (Microsoft/Megaupload‑style)	Alphabet_Upper_Num
Lowercase URL tokens	Alphabet_Lower_Num
General‑purpose tokens	Alphabet_Mix_Num
YouTube‑style video IDs	Alphabet_Mix_Num_SpecialShort
Secure passwords	Alphabet_Mix_Num_SpecialFull

---

🧩 Extending CANG

CANG is intentionally modular.
To add a new language:

1. Add a new entry to Language Name
2. Add a matching Language Type
3. Add a Description
4. Ensure your charset parser supports the new pattern

This design keeps CANG future‑proof and easy to evolve.

---

🏁 Conclusion

CANG provides a clean, structured, and extensible way to generate strings with predictable rules.
Its language‑based architecture makes it ideal for developers who value clarity, control, and compatibility across systems.