"Dovahkiin, Dovahkiin, naal ok zin los vahriin..."

The Ancient Scrolls Speak

TINVAAK (teen-VAHK) - verb - "to speak, to talk"

The ancient art of communication, of transforming thought into voice, silence into sound.

Long ago, before the invention of JavaScript, the dragons of Skyrim wrote their code in Dovahzul - the dragon language. Now, you too can harness the power of the Thu'um to write programs that would make even Alduin proud!

DovahScript is a mystical programming language that channels the ancient power of Dovahzul into modern JavaScript. It's not just a transpiler - it's a bridge between the ancient world of Tamriel and the digital realm of web development.

Why DovahScript?

• For Glory! - Write code like a true Dragonborn
• For the Dragons! - Honor the ancient language of the Dovah
• For Fun! - Because programming should be an adventure
• For Learning! - A playful way to understand transpilers and language design

Preparing for Your Journey (Installation)

The Wanderer's Path (No Installation)

Like a true adventurer, you need only your wits and Node.js:

# Begin your quest
git clone https://github.com/basteez/DovahScript.git
cd DovahScript

# Speak the words of power
node tinvaak.js <your-spell.dov> [-o <output.js>]

The Thane's Path (Global Installation)

For those who have proven themselves worthy, install the transpiler across all holds:

# Gain the Thu'um globally
npm install -g .

# Now summon DovahScript from anywhere in Skyrim... er, your filesystem
dovahscript <your-spell.dov> [-o <output.js>]

Mastering the Thu'um (Usage Guide)

Your First Shout

Every Dragonborn must start somewhere. Let's learn the basic Word of Power:

# Transform DovahScript into the common tongue (JavaScript)
node tinvaak.js examples/00-hello-world.dov

The transpiler reads your DovahScript and creates a JavaScript scroll in the same location.

Choosing Your Destiny

Direct the output to a specific location, like choosing where to store your dragon souls:

node tinvaak.js examples/00-hello-world.dov -o output/hello.js

Unleashing Your Creation

Once transpiled, execute your code and watch the magic unfold:

# Transpile the ancient text
node tinvaak.js mycode.dov -o mycode.js

# Unleash its power!
node mycode.js

The Lexicon of Power (Language Reference)

As discovered in the deepest chambers of Apocrypha, these are the Words of Power that fuel DovahScript...

The Thu'um - Core Shouts (Keywords)

Binding and Summoning (Variables & Functions)

• gron → let - "to bind" - Bind a value to a name, like binding a soul to a gem
• hah → function - "mind" - Create a function, a container of thoughts and logic
• ofan → return - "give" - Return a value from the depths of your function

The Paths of Fate (Conditionals)

• waan → if - "when/if" - Choose your destiny based on truth
• voz → else - "or" - The alternative path when fate decides otherwise
• voz waan → else if - "or when" - Multiple fates, multiple choices

The Eternal Cycles (Loops)

• kenlok waan → while - "to watch when" - Repeat while a condition holds true, like the eternal guard
• zuvir X gon A oblaan B → for (let X = A; X < B; X++) - Count your steps through the realm
• kenlik X voth Y → for (let X of Y) - "to see with" - Journey through each element, like visiting each hold

The Dragon Hierarchy (Classes & Objects)

• vorul → class - "through magic" - Declare a class, a template of power
• gesaak → extends - "to reach" - Inherit power from another class, like a dragon inheriting from its ancestors
• daar → this - "this" - Refer to yourself, your current instance
• zinul → super - "to honor" - Call upon your parent class, honor those who came before
• mulhaan → static - "strong" - Static methods, belonging to the class itself
• yun → new - "to bring/create" - Create a new instance, breathe life into a class

Patience and Catastrophe (Async & Error Handling)

• drem hah → async function - "patience mind" - An async function, for when time flows differently
• saraan → await - "to wait" - Wait for a promise, like waiting for a dragon to land
• unt → try - "to attempt" - Try something dangerous, be prepared
• horvutah → catch - "to catch" - Catch the error when things go wrong, like catching an arrow
• undaar → finally - "under this" - Execute regardless of success or failure
• fusk → throw - "to strike" - Throw an error, unleash chaos
• tozein → Error - "to pierce" - Create an Error object

Truth and Logic (Literals & Operators)

• vahzah → true - "true" - The truth, unwavering
• nivzah → false - "false" - The lie, the opposite of truth
• nid → null - "no/nothing" - The void, nothingness
• ahrk → && - "and" - Both conditions must be true
• uv → || - "or" - Either condition can be true
• ni → ! - "not" - Negate the truth, flip the coin

The Arts of Manipulation (Array Methods)

Master these techniques to bend arrays to your will, like a master of alteration magic:

• .lingraan → .length - "long" - The size of your collection
• .jahfur → .map - "to change" - Transform each element
• .bozeim → .filter - "to sieve" - Keep only what passes your test
• .lahvraan → .reduce - "to bring down/diminish" - Condense many into one
• .enook → .forEach - "to search" - Visit each element
• .osos → .some - "to show" - Check if any element satisfies
• .pah → .every - "all" - Check if all elements satisfy
• .siiv → .find - "to find" - Locate the first match
• .lost → .includes - "to bring inside" - Check if element exists
• .dah → .push - "to push" - Add to the end
• .kaap → .pop - "to grab" - Remove from the end
• .vuld → .shift - "dark/dim" - Remove from the beginning
• .vovuld → .unshift - "un-dark" - Add to the beginning

A Simple Incantation

Behold! A greeting written in the ancient tongue:

DovahScript (The Dragon's Way):

hah greet(name)
    ofan "Lok, " + name + "!"

gron dragonName = "Paarthurnax"
gron greeting = greet(dragonName)

JavaScript (The Common Tongue):

function greet(name) {
    return "Lok, " + name + "!";
}

let dragonName = "Paarthurnax";
let greeting = greet(dragonName);

"Lok" means "sky" in Dovahzul - a proper dragon greeting!

The Training Grounds (Examples)

Deep in the examples/ directory, you'll find ancient texts left by previous Dragonborn:

The Scrolls of Learning

• 00-hello-world.dov - The First Words - Your initiation into the way of the Voice
• 01-simple.dov - Foundations of Power - Variables, functions, and the paths of choice
• 02-medium.dov - The Cycles of Magic - Loops, arrays, and their manipulation
• 03-advanced.dov - Master Level Conjuration - Classes, async sorcery, and error taming

Training Regimen

Practice all shouts at once (recommended for aspiring Greybeards):

npm test

Or hone specific skills individually:

# Start simple, like training at High Hrothgar
node tinvaak.js examples/00-hello-world.dov -o output/00-hello-world.js

# Progress through the trials
node tinvaak.js examples/01-simple.dov -o output/01-simple.js
node tinvaak.js examples/02-medium.dov -o output/02-medium.js

# Become the master
node tinvaak.js examples/03-advanced.dov -o output/03-advanced.js

The Forge of Creation (Implementation Details)

How the Magic Works

Like the ancient dwemer automatons, the transpiler follows a precise sequence of transformations:

1. Array Methods - The most specific spells are cast first
2. Loop Structures - Eternal cycles are formed
3. Class Hierarchies - Dragon bloodlines are established
4. Async Sorcery - Time manipulation and error catching
5. Conditional Paths - The branching roads of fate
6. Function Declarations - Containers of power are created
7. Basic Incantations - The fundamental words are translated
8. Indentation Alchemy - Python-style spacing becomes JavaScript braces
9. Class Refinement - Final touches for class perfection

The Way of the Greybeards (Indentation)

Like the disciplined monks of High Hrothgar, DovahScript uses Python-style indentation for structure. The transpiler transforms this into JavaScript's braces { } automatically.

The Sacred Rule: Choose your path (spaces or tabs) and follow it consistently. Do not mix them, lest your code anger the dragons!

Dragon's Wisdom (Known Limitations)

Even the mightiest Thu'um has its limits. These are the boundaries of DovahScript's power:

What the Dragons Cannot Do

1. No Deep Validation - Like Paarthurnax, the transpiler is trusting. It assumes your code is well-formed and doesn't check every nested structure. "What is better - to validate complex nesting, or to trust the Dragonborn to write good code?"

2. Consistent Indentation Required - Mix not spaces and tabs, for this path leads to chaos. The ancient texts must be properly formatted!

3. String Literals - Words of power within quoted strings might transform. This is rare, like spotting a dragon in Whiterun. Usually not a problem, but be mindful!

4. Comments Can Change - Even comments containing dragon words may be altered. A small price for speaking the ancient tongue!

5. No Type Sorcery - The transpiler cares not for types. It trusts you know fire from frost, string from number.

These limitations are intentional - a choice made to keep the transpiler as simple as a sweetroll recipe. This is a project for joy and learning, not production dragon-slaying!

The Map of Our Realm (Project Structure)

dovahscript/                    The hold capital
├── tinvaak.js                  TINVAAK - "To Speak" - The Voice that transforms dragon tongue
├── package.json                The manifest of our quest
├── README.md                   The scroll you're reading now
├── words.txt                   The Dovahzul lexicon (ancient dragon dictionary)
├── examples/                   The Hall of Heroes (example programs)
│   ├── 00-hello-world.dov      Your first words
│   ├── 01-simple.dov           Basic Thu'um
│   ├── 02-medium.dov           Intermediate sorcery
│   └── 03-advanced.dov         Master-level dragon magic
└── output/                     Your transpiled treasures

Join the Companions (Contributing)

The Companions welcome all who seek glory! Join our cause:

• Write More Spells - Add example programs showcasing new techniques
• Expand the Lexicon - Suggest new Dovahzul keywords and their mappings
• Improve Defenses - Better error messages and handling
• Slay Bugs - Find and fix issues in the transpiler
• Enhance the Experience - Make DovahScript even more fun!

Remember: "It's a fine day with you around!"

The Laws of Skyrim (License)

MIT License - As free as a wandering adventurer

Honor to the Creators

"Let me guess, someone stole your sweetroll?" - No, but we did borrow inspiration from:

• The Elder Scrolls V: Skyrim - For gifting us the magnificent Dovahzul language and the world of Tamriel
• Bethesda Game Studios - For creating a universe so rich it inspires projects like this
• The Dovahzul Community - Linguists and fans who've documented and expanded the dragon language
• All the Dragonborn - Players who've shouted their way through countless adventures

Easter Eggs & Fun Facts

• The word "DovahScript" combines "Dovah" (Dragon) and "Script" (well, script)
• If you yell "FUS RO DAH" at your computer while running the transpiler, it won't actually do anything... or will it? 🤔
• Paarthurnax would be proud of you for learning a new language, even if it's just for code
• gron (bind) was chosen for variables because you're literally binding values to names
• The transpiler doesn't judge you for using nivzah (false). Sometimes, lies are necessary in code!

---

Final Words from the Greybeards

     *  .  *       .        *    .      *      .     *
  .      🐉    *        ⛰️        *   🏔️   *      .
     *      .    High Hrothgar awaits    *    .    *
  .    *         *    .      *     .   *    .    *

"Dragonborn, your code has the power to shake the very foundations of Tamriel!"

May your functions always return, your loops eventually terminate, and your errors be caught with grace. Remember: even the greatest Dragonborn started by shouting at a simple practice target.

Now go forth and code! The dragons await your commands!

---

FUS RO DAH!

May your code be as powerful as the Thu'um, your bugs as rare as Dragon Priests, and your deployments as smooth as a giant's club!

For the glory of the Dragonborn! For the honor of Skyrim! For the love of coding!