Skip to content

Commit

Permalink
Merge pull request #178 from KennyOliver/issue-54
Browse files Browse the repository at this point in the history 
Issue 54: Numerous Places in README Need Updating
  • Loading branch information
@KennyOliver
KennyOliver authored Jan 4, 2025
2 parents d110d4f + de8b280 commit 8692dfc
Show file tree
Hide file tree
Showing 3 changed files with 262 additions and 201 deletions.
237 changes: 36 additions & 201 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,25 +33,21 @@ FlavorLang blends coding with culinary creativity! Write programs like recipes &

3. [🚀 Execution Flags & Behaviors](#execution-flags--behaviors)

4. [Syntax Keywords](#syntax-keywords)

5. [Data Types](#data-types)

6. [Extended Backus-Naur Form (EBNF)](#ebnf)

7. [Install Syntax Highlighter Extension](#extension)
4. [🎨 Install Syntax Highlighter Extension](#extension)

### `docs/`

8. [Syntax Examples](docs/syntax_examples.md)
5. [Syntax Examples](docs/syntax_examples.md)

9. [Debugging](docs/debugging.md)
6. [Debugging](docs/debugging.md)

10. [Lexer](docs/lexer.md)
7. [Language Design](docs/language_design.md)

11. [Parser](docs/parser.md)
8. [Lexer](docs/lexer.md)

12. [Interpreter](docs/interpreter.md)
9. [Parser](docs/parser.md)

10. [Interpreter](docs/interpreter.md)

---

Expand All @@ -70,24 +66,6 @@ FlavorLang blends coding with culinary creativity! Write programs like recipes &

### 1. Install the Compiler

<details>
<summary>
<h4>Make it yourself</h4>
</summary>

```bash
$ git clone https://github.com/KennyOliver/FlavorLang.git
$ cd src
$ make
```

> [!Note]
>
> Unless you move `flavor` to `/usr/local/bin/`,
> you'll have to use `./flavor` for commands with relative file paths.
</details>

#### For macOS Users

##### 1. Download & Extract the ZIP
Expand All @@ -105,7 +83,7 @@ $ make
##### 3. Handle macOS Security Prompt (If Any)

- If macOS prompts a security warning, navigate to <kbd>System Preferences</kbd> > <kbd>Security & Privacy</kbd> > <kbd>General</kbd>.
- Click "Open Anyway" for `flavor`.
- Click <kbd>Open Anyway</kbd> for `flavor`.

##### 4. Verify Installation

Expand Down Expand Up @@ -133,6 +111,19 @@ flavor --about
flavor --about
```

#### Make it Yourself

```bash
$ git clone https://github.com/KennyOliver/FlavorLang.git
$ cd src
$ make
```

> [!Note]
>
> Unless you move `flavor` to `/usr/local/bin/`,
> you'll have to use `./flavor` for commands with relative file paths.
### 2. Write Your First Recipe

```py
Expand Down Expand Up @@ -173,180 +164,25 @@ The `--debug` flag is really useful for understanding how FlavorLang is executin

---

<details>
<summary><h2>Syntax Keywords</h2></summary>

| Keyword | Usage | Description | Implemented? |
| --------- | ---------------------------- | ------------------------------------------------------------------------------------------- | ------------ |
| `let` | Define variables | Declares and initializes variables. | ✅ |
| `const` | Define constants | Declares and initializes constants. | ✅ |
| `if` | Conditional logic | Executes code only if a condition is true. | ✅ |
| `elif` | Conditional logic fallback | Executes only if a prior `if` condition is false. | ✅ |
| `else` | Conditional fallback | Executes code if any prior `if`/`is` conditions are false. | ✅ |
| `for` | For-loop | Iterates over a range or sequence, executing a block of code for each step. | ✅ |
| `in` | Range declaration | Specifies the range or sequence to iterate over. | ✅ |
| `by` | Optional step specifier | Defines the step interval for iteration; defaults to `1`/`-1` (range dependent) if omitted. | ✅ |
| `while` | While-loop | Repeatedly runs code while a condition is true. | ✅ |
| `check` | Switch-case equivalent | Matches a value to multiple cases. | ✅ |
| `is` | Case clause | Defines a case inside `check`. | ✅ |
| `break` | Exit control flow | Stops execution of further cases in `check` and exits the current flow. | ✅ |
| `create` | Define a function | Creates a reusable block of logic. | ✅ |
| `deliver` | Return statement | Returns a value and stops function execution. | ✅ |
| `try` | Try block | Executes code that might fail. | ❌ |
| `crumbs` | Catch block | Handles errors during execution. | ❌ |
| `burn` | Force exit or raise an error | Stops execution immediately with a message. | ✅ |
| `serve` | Print or output | Outputs a value or message immediately. | ✅ |
| `sample` | Input from console | Reads user input. | ✅ |
| `plate` | Write to file | Writes data to a file. | ✅ |
| `garnish` | Append to file | Appends data to a file. | ✅ |
| `taste` | Read from file | Reads data from a file. | ✅ |
| `recipe` | Import `.flv` file | Imports logic from another `.flv` file. | ❌ |

</details>

---

## Data Types

| Data Type | Capacity/Range |
| --------- | -------------------------------------------------------------------- |
| `string` | Dependent on system memory & encoding (e.g., UTF-8). |
| `float` | (64-bit to 128-bit): Platform-dependent, typically up to ±1.1E±4932. |
| `integer` | (64-bit): ±9e18 (quintillion). |
| `boolean` | `1` for `True`, `0` for `False`. Typically stored as 1 byte. |

<details>

<summary><h3>Explanation</h3></summary>

- **string**:

In C, the language used to make FlavorLang, strings are null-terminated arrays of characters. The length is limited by system memory and encoding. For example, in UTF-8 encoding, a string can take varying amounts of space per character depending on the character set.

- **float**:

The `FLOAT_SIZE` type is a `long double`, offering a precision and range larger than the standard `double`. Its range is platform-dependent but typically up to ±1.1E±4932 on 128-bit implementations.

- **integer**:

The `INT_SIZE` type is a `long long int` with a range from −9,223,372,036,854,775,808 to 9,223,372,036,854,775,807, suitable for large integer values.

- **boolean**:

Booleans are typically stored as `1` (`True`) and `0` (`False`). While logically they are 1-bit, they are typically stored in 1 byte for practical reasons.
</details>

---

<details>
<summary>
<h2>
<a id="ebnf">Extended Backus-Naur Form (EBNF) of FlavorLang's Syntax</a>
</h2>
</summary>

```ebnf
program ::= statement* ;
statement ::= variable_declaration
| print_statement
| if_statement
| loop_statement
| function_definition
| error_handling
| file_operation
| switch_case
| user_input
| random_statement
| type_casting
| return_statement
| raise_error ;
variable_declaration ::= "let" IDENTIFIER "=" expression ";" ;
print_statement ::= "serve" expression ("," expression)* ";" ;
if_statement ::= "if" condition block
("elif" condition block)*
("else" block)? ;
loop_statement ::= "while" condition block
| "for" IDENTIFIER "in" range [ "by" step ] block ;
function_definition ::= "create" IDENTIFIER parameter_list block ;
error_handling ::= "try" block "rescue" block ;
file_operation ::= "plate" STRING "," expression ";"
| "garnish" STRING "," expression ";"
| "taste" STRING ";" ;
switch_case ::= "check" expression block case_clause* [ "else" block ] ;
case_clause ::= "is" expression ":" block
| "is" expression ":" block "break" ";" ;
## 🎨 Install the VS Code Syntax Highlighter <a id="extension"></a>

user_input ::= "sample" "(" ")" ";" ;
### Installation Instructions

random_statement ::= "random" "(" [expression ["," expression]] ")" ;
#### 1. Download & Extract the ZIP

type_casting ::= "string" "(" expression ")"
| "int" "(" expression ")"
| "float" "(" expression ")" ;
return_statement ::= "deliver" expression ";" ;
raise_error ::= "burn" expression ("," expression)* ";" ;
block ::= "{" statement+ "}" ;
condition ::= expression comparison_operator expression ;
expression ::= NUMBER
| STRING
| IDENTIFIER
| boolean
| math_expression
| function_call
| random_statement ;
math_expression ::= "(" expression math_operator expression ")" ;
function_call ::= IDENTIFIER "(" [expression ("," expression)*] ")" ;
boolean ::= "True" | "False" ;
comparison_operator ::= "==" | "!=" | "<" | "<=" | ">" | ">=" ;
math_operator ::= "+" | "-" | "*" | "**" | "/" | "//" | "%" ;
logical_operator ::= "&&" | "||" ;
bitwise_operator ::= "~" ;
assignment_operator ::= "=" ;
range_operator ::= ".." | "..=" ;
parameter_list ::= "(" [IDENTIFIER ("," IDENTIFIER)*] ")" ;
[FlavorLang Releases](https://github.com/KennyOliver/FlavorLang/releases)

range ::= expression range_operator expression ;
#### 2. Open VS Code and Navigate to the Extensions Tab

step ::= expression ;
```
#### 3. Click the <kbd>...</kbd> Menu and Select <kbd>Install from VSIX...</kbd>

</details>
#### 4. Select the File in Finder or your File Explorer

---
#### 5. Restart your Extensions via the Popup Notification

<details>
<summary>
<h2>
<a id="extension">Install the VS Code Syntax Highlighter</a>
</h2>
</summary>
### Make it Yourself

### 1. Build the Extension
#### 1. Build the Extension

Navigate to the `vscode-extension` folder and install dependencies:

Expand All @@ -355,21 +191,20 @@ cd vscode-extension
npm install
```

### 2. Package the Extension
#### 2. Package the Extension

Use vsce (Visual Studio Code Extension Manager) to build the `.vsix` package:

```bash
npx vsce package
```

### 3. Install in VS Code
#### 3. Install in VS Code

- Open VS Code.
- Press <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (or <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> on Mac) and select _`Extensions: Install from VSIX…`_.
- Press <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (or <kbd>&#8984;</kbd>+<kbd>&#8679;</kbd>+<kbd>P</kbd> on macOS) and select _`Extensions: Install from VSIX…`_.
- Select the generated `.vsix` file within the `vscode-extension` folder.

</details>
- Restart your extensions via the popup notificaiton.

---

Expand Down
Loading

0 comments on commit 8692dfc

Please sign in to comment.