docs: Add comprehensive Femcode language documentation

docs/README.md

@@ -1,3 +1,260 @@
-# Femcode
+# Femcode Language Documentation
 
-A femboy-themed programming language.
+Femcode is a femboy-themed programming language designed to be simple, expressive, and fun. It features a unique syntax inspired by femboy terminology, making coding an adorable experience.
+
+## Table of Contents
+
+1.  [Getting Started](#getting-started)
+2.  [Basic Syntax](#basic-syntax)
+3.  [Variables and Assignment](#variables-and-assignment)
+4.  [Data Types](#data-types)
+    *   [Numbers](#numbers)
+    *   [Strings](#strings)
+    *   [Booleans](#booleans)
+    *   [Lists](#lists)
+    *   [Dictionaries](#dictionaries)
+5.  [Operators](#operators)
+    *   [Arithmetic Operators](#arithmetic-operators)
+    *   [Comparison Operators](#comparison-operators)
+    *   [Logical Operators](#logical-operators)
+6.  [Control Flow](#control-flow)
+    *   [Conditional Statements (If/Else)](#conditional-statements-ifelse)
+    *   [Loops (While)](#loops-while)
+7.  [Functions](#functions)
+    *   [Defining Functions](#defining-functions)
+    *   [Calling Functions](#calling-functions)
+    *   [Return Values](#return-values)
+    *   [Built-in Functions](#built-in-functions)
+8.  [Comments](#comments)
+9.  [Input/Output](#inputoutput)
+
+## 1. Getting Started
+
+To run Femcode programs, you need the Femcode interpreter. Navigate to the `femcode/src` directory and run `main.py` with your Femcode file.
+
+```bash
+python3 main.py ../examples/your_program.fem
+```
+
+## 2. Basic Syntax
+
+Femcode uses keywords inspired by femboy terminology. Code blocks are defined using `Femboycore` to start a block and `Periodt` to end it.
+
+## 3. Variables and Assignment
+
+Variables are declared and assigned values using the `is` keyword.
+
+```femcode
+my_variable is 10
+my_name is "Femboy"
+```
+
+## 4. Data Types
+
+### Numbers
+
+Femcode supports integer numbers.
+
+```femcode
+my_number is 123
+```
+
+### Strings
+
+Strings are sequences of characters enclosed in double quotes.
+
+```femcode
+my_string is "Hello, world!"
+```
+
+### Booleans
+
+Femcode has two boolean values: `Kawaii` (True) and `Cringe` (False).
+
+```femcode
+is_cute is Kawaii
+is_bad is Cringe
+```
+
+### Lists
+
+Lists are ordered collections of items, enclosed in square brackets `[]` and separated by commas.
+
+```femcode
+my_list is [1, "apple", Kawaii]
+```
+
+Elements can be accessed using zero-based indexing:
+
+```femcode
+UwU Boy my_list[0] # Prints 1
+```
+
+### Dictionaries
+
+Dictionaries are unordered collections of key-value pairs, enclosed in curly braces `{}`. Keys and values are separated by a colon `:`, and pairs are separated by commas.
+
+```femcode
+my_dict is {"name": "Femboy", "version": 1.0}
+```
+
+Values can be accessed using dot notation (property access):
+
+```femcode
+UwU Boy my_dict.name # Prints "Femboy"
+```
+
+## 5. Operators
+
+### Arithmetic Operators
+
+Femcode supports standard arithmetic operations:
+
+*   `+` (addition)
+*   `-` (subtraction)
+*   `*` (multiplication)
+*   `/` (division)
+
+```femcode
+result is 10 + 5 * 2
+UwU Boy result # Prints 20
+```
+
+### Comparison Operators
+
+Used for comparing values:
+
+*   `==` (equal to)
+*   `!=` (not equal to)
+*   `>` (greater than)
+*   `<` (less than)
+*   `>=` (greater than or equal to)
+*   `<=` (less than or equal to)
+
+```femcode
+UwU Boy 5 == 5 # Prints Kawaii
+UwU Boy 10 < 5 # Prints Cringe
+```
+
+### Logical Operators
+
+Used for combining boolean expressions:
+
+*   `and` (logical AND)
+*   `or` (logical OR)
+*   `not` (logical NOT)
+
+```femcode
+UwU Boy Kawaii and Cringe # Prints Cringe
+UwU Boy Kawaii or Cringe # Prints Kawaii
+UwU Boy not Kawaii # Prints Cringe
+```
+
+## 6. Control Flow
+
+### Conditional Statements (If/Else)
+
+Use `Femboy Feminine` for `if` and `Androgyny` for `else` to control program flow based on conditions.
+
+```femcode
+my_age is 20
+Femboy Feminine my_age > 18 Femboycore
+    UwU Boy "You are an adult femboy!"
+Periodt
+Androgyny Femboycore
+    UwU Boy "You are a young femboy!"
+Periodt
+```
+
+### Loops (While)
+
+Use `Otokonoko` for `while` loops to repeatedly execute a block of code as long as a condition is true.
+
+```femcode
+counter is 0
+Otokonoko counter < 5 Femboycore
+    UwU Boy counter
+    counter is counter + 1
+Periodt
+```
+
+## 7. Functions
+
+### Defining Functions
+
+Functions are defined using the `Femboy` keyword, followed by the function name, optional parameters in parentheses, and a code block enclosed by `Femboycore` and `Periodt`.
+
+```femcode
+Femboy say_hello() Femboycore
+    UwU Boy "Hello from function!"
+Periodt
+
+Femboy add_numbers(a, b) Femboycore
+    Femme a + b
+Periodt
+```
+
+### Calling Functions
+
+Functions are called by their name followed by parentheses, enclosing any arguments.
+
+```femcode
+say_hello()
+result is add_numbers(10, 5)
+```
+
+### Return Values
+
+Use the `Femme` keyword to return a value from a function.
+
+```femcode
+Femboy get_kawaii_status() Femboycore
+    Femme Kawaii
+Periodt
+
+status is get_kawaii_status()
+UwU Boy status # Prints Kawaii
+```
+
+### Built-in Functions
+
+Femcode provides several built-in functions for common tasks:
+
+*   `ask(prompt)`: Prompts the user for input and returns it as a string.
+    ```femcode
+    name is ask("What's your name, femboy? ")
+    UwU Boy "Hello, " + name + "!"
+    ```
+
+*   `len(value)`: Returns the length of a string or a list.
+    ```femcode
+    my_string is "Cute"
+    my_list is [1, 2, 3]
+    UwU Boy len(my_string) # Prints 4
+    UwU Boy len(my_list) # Prints 3
+    ```
+
+*   `type(value)`: Returns the type of a value as a string (e.g., "int", "str", "list", "dict", "bool").
+    ```femcode
+    UwU Boy type(123) # Prints "int"
+    UwU Boy type("hello") # Prints "str"
+    UwU Boy type(Kawaii) # Prints "bool"
+    ```
+
+## 8. Comments
+
+Single-line comments start with a `#` symbol. Anything after `#` on the same line is ignored by the interpreter.
+
+```femcode
+# This is a single-line comment
+UwU Boy "Hello, Femcode!" # This is also a comment
+```
+
+## 9. Input/Output
+
+Input is handled via the `ask` built-in function, and output is handled via the `UwU Boy` (print) command.
+
+```femcode
+name is ask("Enter your name: ")
+UwU Boy "Your name is: " + name
+```