Add templates for authentication, enrollment, and greeting flows with detailed explanations and examples
This commit is contained in:
parent
d16f34ca93
commit
1253ef7fad
5 changed files with 191 additions and 159 deletions
|
|
@ -1 +1,21 @@
|
|||
# auth.bas
|
||||
|
||||
```basic
|
||||
REM Simple authentication flow
|
||||
SET attempts = 0
|
||||
LABEL auth_loop
|
||||
HEAR password
|
||||
IF password = "secret123" THEN
|
||||
TALK "Authentication successful."
|
||||
ELSE
|
||||
SET attempts = attempts + 1
|
||||
IF attempts >= 3 THEN
|
||||
TALK "Too many attempts. Goodbye."
|
||||
EXIT
|
||||
ENDIF
|
||||
TALK "Incorrect password. Try again."
|
||||
GOTO auth_loop
|
||||
ENDIF
|
||||
```
|
||||
|
||||
This template demonstrates a basic password check with a limited number of attempts. It uses the `HEAR`, `TALK`, `SET`, `IF`, `ELSE`, `GOTO`, and `EXIT` keywords to manage the dialog flow.
|
||||
|
|
|
|||
31
docs/src/chapter-05/templates/auth.md
Normal file
31
docs/src/chapter-05/templates/auth.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
# auth.bas (Template)
|
||||
|
||||
This template demonstrates a simple authentication flow using the BASIC dialog language.
|
||||
|
||||
```basic
|
||||
REM Simple authentication flow
|
||||
SET attempts = 0
|
||||
LABEL auth_loop
|
||||
HEAR password
|
||||
IF password = "secret123" THEN
|
||||
TALK "Authentication successful."
|
||||
ELSE
|
||||
SET attempts = attempts + 1
|
||||
IF attempts >= 3 THEN
|
||||
TALK "Too many attempts. Goodbye."
|
||||
EXIT
|
||||
ENDIF
|
||||
TALK "Incorrect password. Try again."
|
||||
GOTO auth_loop
|
||||
ENDIF
|
||||
```
|
||||
|
||||
**Purpose**
|
||||
|
||||
- Shows how to collect a password with `HEAR`.
|
||||
- Limits the number of attempts to three.
|
||||
- Uses `TALK` to give feedback and `EXIT` to end the dialog after too many failures.
|
||||
|
||||
**Keywords used:** `SET`, `HEAR`, `IF`, `ELSE`, `GOTO`, `EXIT`, `TALK`.
|
||||
|
||||
---
|
||||
74
docs/src/chapter-05/templates/enrollment.md
Normal file
74
docs/src/chapter-05/templates/enrollment.md
Normal file
|
|
@ -0,0 +1,74 @@
|
|||
# enrollment.bas (Template)
|
||||
|
||||
A comprehensive enrollment dialog that gathers user information, confirms it, and saves it to a CSV file.
|
||||
|
||||
```basic
|
||||
REM Enrollment Tool Example
|
||||
|
||||
## Complete Enrollment Script
|
||||
|
||||
PARAM name AS string LIKE "Abreu Silva"
|
||||
DESCRIPTION "Required full name of the individual."
|
||||
|
||||
PARAM birthday AS date LIKE "23/09/2001"
|
||||
DESCRIPTION "Required birth date of the individual in DD/MM/YYYY format."
|
||||
|
||||
PARAM email AS string LIKE "abreu.silva@example.com"
|
||||
DESCRIPTION "Required email address for contact purposes."
|
||||
|
||||
PARAM personalid AS integer LIKE "12345678900"
|
||||
DESCRIPTION "Required Personal ID number of the individual (only numbers)."
|
||||
|
||||
PARAM address AS string LIKE "Rua das Flores, 123 - SP"
|
||||
DESCRIPTION "Required full address of the individual."
|
||||
|
||||
DESCRIPTION "This is the enrollment process, called when the user wants to enrol. Once all information is collected, confirm the details and inform them that their enrollment request has been successfully submitted. Provide a polite and professional tone throughout the interaction."
|
||||
|
||||
REM Enrollment Process
|
||||
TALK "Welcome to the enrollment process! Let's get you registered."
|
||||
|
||||
TALK "First, what is your full name?"
|
||||
HEAR name
|
||||
|
||||
TALK "Thank you. What is your birth date? (DD/MM/YYYY)"
|
||||
HEAR birthday
|
||||
|
||||
TALK "What is your email address?"
|
||||
HEAR email
|
||||
|
||||
TALK "Please provide your Personal ID number (numbers only):"
|
||||
HEAR personalid
|
||||
|
||||
TALK "Finally, what is your full address?"
|
||||
HEAR address
|
||||
|
||||
REM Validate and confirm
|
||||
TALK "Please confirm your details:"
|
||||
TALK "Name: " + name
|
||||
TALK "Birth Date: " + birthday
|
||||
TALK "Email: " + email
|
||||
TALK "Personal ID: " + personalid
|
||||
TALK "Address: " + address
|
||||
|
||||
TALK "Are these details correct? (yes/no)"
|
||||
HEAR confirmation
|
||||
|
||||
IF confirmation = "yes" THEN
|
||||
REM Save to CSV file
|
||||
SAVE "enrollments.csv", name, birthday, email, personalid, address
|
||||
TALK "Thank you! Your enrollment has been successfully submitted. You will receive a confirmation email shortly."
|
||||
ELSE
|
||||
TALK "Let's start over with the correct information."
|
||||
REM In a real implementation, you might loop back or use a different approach
|
||||
END IF
|
||||
```
|
||||
|
||||
**Purpose**
|
||||
|
||||
- Shows how to define parameters with `PARAM` and `DESCRIPTION`.
|
||||
- Demonstrates a multi‑step data collection flow using `HEAR` and `TALK`.
|
||||
- Confirms data before persisting it via `SAVE`.
|
||||
|
||||
**Keywords used:** `PARAM`, `DESCRIPTION`, `HEAR`, `TALK`, `IF`, `ELSE`, `SAVE`.
|
||||
|
||||
---
|
||||
25
docs/src/chapter-05/templates/start.md
Normal file
25
docs/src/chapter-05/templates/start.md
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
# start.bas (Template)
|
||||
|
||||
A minimal greeting and help flow to get users started.
|
||||
|
||||
```basic
|
||||
REM Basic greeting and help flow
|
||||
SET user_name = "Guest"
|
||||
TALK "Hello, " + user_name + "! How can I help you today?"
|
||||
HEAR user_input
|
||||
IF user_input = "help" THEN
|
||||
TALK "Sure, I can assist with account info, orders, or support."
|
||||
ELSE
|
||||
TALK "Sorry, I didn't understand."
|
||||
ENDIF
|
||||
```
|
||||
|
||||
**Purpose**
|
||||
|
||||
- Shows how to set a variable with `SET`.
|
||||
- Uses `TALK` to send a message and `HEAR` to receive user input.
|
||||
- Demonstrates simple branching with `IF/ELSE`.
|
||||
|
||||
**Keywords used:** `SET`, `TALK`, `HEAR`, `IF`, `ELSE`.
|
||||
|
||||
---
|
||||
|
|
@ -1,166 +1,48 @@
|
|||
# Prompt for Generating GeneralBots mdBook Documentation
|
||||
**Task:** Generate comprehensive mdBook documentation for the GeneralBots application by analyzing the actual source code and filling all documentation files with accurate, complete information.
|
||||
|
||||
**Goal**
|
||||
Generate a complete **mdBook** that documents the GeneralBots application for a user with basic knowledge of large‑language models (LLM).
|
||||
**Objective:** Create complete, professional documentation for BASIC enthusiasts that accurately reflects the GeneralBots codebase.
|
||||
|
||||
**Rules**
|
||||
- Use **only real keywords** and features that exist in the source code (no invented commands).
|
||||
- Include Rust code **exclusively** in the **gbapp** chapter.
|
||||
- Keep the tone simple, beginner‑friendly, and instructional.
|
||||
- Base all information on the actual code base:
|
||||
- Keywords in `src/basic/keywords/`
|
||||
- Database models in `src/shared/models.rs`
|
||||
- Example scripts in `templates/`
|
||||
**Source Analysis Requirements:**
|
||||
- Analyze all files in `@/src` directory structure
|
||||
- Extract real keywords from `src/basic/keywords/`
|
||||
- Document actual database models from `src/shared/models.rs`
|
||||
- Reference real example scripts from `templates/`
|
||||
- Use only verified features that exist in the codebase
|
||||
|
||||
**Required Markdown Structure (headings)**
|
||||
**Documentation Standards:**
|
||||
- Maintain beginner-friendly, instructional tone
|
||||
- Include Rust code examples ONLY in the gbapp chapter
|
||||
- Use real keywords and commands from the source code
|
||||
- Structure content according to the required markdown headings
|
||||
- Ensure all documentation can be built with `mdbook build docs/src`
|
||||
|
||||
1. **Run and Talk** – How to start the server and interact using `TALK` / `HEAR`.
|
||||
2. **About Packages** – Overview of the four package types (`.gbdialog`, `.gbkb`, `.gbtheme`, `.gbot`).
|
||||
3. **gbkb Reference** – Explain `ADD_KB`, `SET_KB`, `ADD_WEBSITE`.
|
||||
4. **gbtheme Reference** – Describe UI theming via CSS/HTML.
|
||||
5. **gbdialog Reference** – List the three example scripts (`start.bas`, `auth.bas`, `update-summary.bas`) and the core keywords (`TALK`, `HEAR`, `LLM`, etc.).
|
||||
6. **gbapp Reference** – Show a minimal Rust snippet that registers a keyword (e.g., `ADD_TOOL`).
|
||||
7. **gbot Reference** – Explain the `config.csv` format and editable parameters.
|
||||
8. **Tooling** – Table of all built‑in keywords with one‑line descriptions.
|
||||
9. **Feature‑Matrix** – Table mapping features to the chapters/keywords that implement them.
|
||||
10. **Contributing** – Steps for contributors (fork, branch, tests, formatting).
|
||||
11. **Appendix I – Database Model** – Summarise the main tables from `src/shared/models.rs`.
|
||||
12. **Glossary** – Definitions of extensions and key concepts.
|
||||
**Required Sections to Complete:**
|
||||
1. **Run and Talk** - Server startup and TALK/HEAR interaction
|
||||
2. **About Packages** - Four package types explanation
|
||||
3. **gbkb Reference** - ADD_KB, SET_KB, ADD_WEBSITE documentation
|
||||
4. **gbtheme Reference** - UI theming with CSS/HTML
|
||||
5. **gbdialog Reference** - Example scripts and core keywords
|
||||
6. **gbapp Reference** - Rust keyword registration examples
|
||||
7. **gbot Reference** - config.csv format and parameters
|
||||
8. **Tooling** - Complete keyword reference table
|
||||
9. **Feature-Matrix** - Features to implementation mapping
|
||||
10. **Contributing** - Development workflow guidelines
|
||||
11. **Appendix I - Database Model** - models.rs table summaries
|
||||
12. **Glossary** - Key terms and extension definitions
|
||||
|
||||
**Output Requirements**
|
||||
**Output Specifications:**
|
||||
- Generate only the markdown content (no external commentary)
|
||||
- Include proper fenced code blocks with language tags
|
||||
- Provide a complete table of contents with markdown links
|
||||
- Ensure all sections are fully populated with real information
|
||||
- Skip files that already contain substantial content
|
||||
- Base all examples on actual code from the repository
|
||||
|
||||
- Produce **only** the markdown content (no surrounding explanations).
|
||||
- Use fenced code blocks with appropriate language tags (`bas` for BASIC scripts, `rust` for Rust snippets).
|
||||
- Include a **Table of Contents** with markdown links to each chapter.
|
||||
- Ensure the document can be built directly with `mdbook build docs/src`.
|
||||
**Quality Requirements:**
|
||||
- Accuracy: All information must match the source code
|
||||
- Completeness: Every required section must be fully developed
|
||||
- Clarity: Explanations should be accessible to BASIC enthusiasts
|
||||
- Consistency: Maintain uniform formatting and style throughout
|
||||
- Practicality: Include working examples and practical usage tips
|
||||
|
||||
**Example Skeleton (to be expanded by the generator)**
|
||||
|
||||
```markdown
|
||||
# GeneralBots User Documentation (mdBook)
|
||||
|
||||
## Table of Contents
|
||||
- [Run and Talk](#run-and-talk)
|
||||
- [About Packages](#about-packages)
|
||||
- [gbkb Reference](#gbkb-reference)
|
||||
- [gbtheme Reference](#gbtheme-reference)
|
||||
- [gbdialog Reference](#gbdialog-reference)
|
||||
- [gbapp Reference](#gbapp-reference)
|
||||
- [gbot Reference](#gbot-reference)
|
||||
- [Tooling](#tooling)
|
||||
- [Feature‑Matrix](#feature-matrix)
|
||||
- [Contributing](#contributing)
|
||||
- [Appendix I – Database Model](#appendix‑i---database-model)
|
||||
- [Glossary](#glossary)
|
||||
|
||||
## Run and Talk
|
||||
```bas
|
||||
TALK "Welcome! How can I help you today?"
|
||||
HEAR user_input
|
||||
```
|
||||
*Start the server:* `cargo run --release`
|
||||
|
||||
## About Packages
|
||||
| Component | Extension | Role |
|
||||
|-----------|-----------|------|
|
||||
| Dialog scripts | `.gbdialog` | BASIC‑style conversational logic |
|
||||
| Knowledge bases | `.gbkb` | Vector‑DB collections |
|
||||
| UI themes | `.gbtheme` | CSS/HTML assets |
|
||||
| Bot config | `.gbot` | CSV mapping to `UserSession` |
|
||||
|
||||
## gbkb Reference
|
||||
...
|
||||
|
||||
## gbapp Reference
|
||||
```rust
|
||||
pub fn add_tool_keyword(state: Arc<AppState>, user: UserSession, engine: &mut Engine) {
|
||||
// registration logic …
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
When you are ready, output the full markdown document that satisfies the specifications above.
|
||||
*Do not include any commentary outside the markdown itself.*
|
||||
|
||||
# FORMAT Keyword
|
||||
|
||||
The **FORMAT** keyword formats numbers, dates, and text for display. Use it when you need a quick, readable representation without writing custom code.
|
||||
|
||||
## Syntax
|
||||
```basic
|
||||
RESULT = FORMAT(VALUE, PATTERN)
|
||||
```
|
||||
|
||||
## BASIC EXAMPLE
|
||||
```basic
|
||||
NUMBER = 1234.56
|
||||
TEXT = "John"
|
||||
DATE = "2024-03-15 14:30:00"
|
||||
TALK FORMAT(NUMBER, "n") ' 1234.56
|
||||
TALK FORMAT(TEXT, "Hello @!") ' Hello John!
|
||||
TALK FORMAT(DATE, "dd/MM/yyyy") ' 15/03/2024
|
||||
```
|
||||
- **VALUE** – any number, date string (`YYYY‑MM‑DD HH:MM:SS`), or text.
|
||||
- **PATTERN** – a short format string (see tables below).
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Numeric Patterns
|
||||
| Pattern | Example | Output |
|
||||
|---------|---------|--------|
|
||||
| `n` | `FORMAT(1234.5, "n")` | `1234.50` |
|
||||
| `F` | `FORMAT(1234.5, "F")` | `1234.50` |
|
||||
| `f` | `FORMAT(1234.5, "f")` | `1234` |
|
||||
| `0%` | `FORMAT(0.85, "0%")` | `85%` |
|
||||
| `C2[en]` | `FORMAT(1234.5, "C2[en]")` | `$1,234.50` |
|
||||
| `C2[pt]` | `FORMAT(1234.5, "C2[pt]")` | `R$ 1.234,50` |
|
||||
|
||||
### Date Patterns
|
||||
| Code | Meaning | Example |
|
||||
|------|---------|---------|
|
||||
| `yyyy` | 4‑digit year | `2024` |
|
||||
| `yy` | 2‑digit year | `24` |
|
||||
| `MM` | month (01‑12) | `03` |
|
||||
| `M` | month (1‑12) | `3` |
|
||||
| `dd` | day (01‑31) | `05` |
|
||||
| `d` | day (1‑31) | `5` |
|
||||
| `HH` | 24‑hour (00‑23) | `14` |
|
||||
| `hh` | 12‑hour (01‑12) | `02` |
|
||||
| `mm` | minutes (00‑59) | `05` |
|
||||
| `ss` | seconds (00‑59) | `09` |
|
||||
| `tt` | AM/PM | `PM` |
|
||||
|
||||
**Example**
|
||||
```basic
|
||||
DATE = "2024-03-15 14:30:25"
|
||||
TALK FORMAT(DATE, "dd/MM/yyyy HH:mm") ' 15/03/2024 14:30
|
||||
```
|
||||
|
||||
### Text Patterns
|
||||
| Placeholder | Effect |
|
||||
|-------------|--------|
|
||||
| `@` | Insert original text |
|
||||
| `!` | Upper‑case |
|
||||
| `&` | Lower‑case |
|
||||
|
||||
**Example**
|
||||
```basic
|
||||
NAME = "Maria"
|
||||
TALK FORMAT(NAME, "Hello, !") ' Hello, MARIA
|
||||
```
|
||||
|
||||
## Practical Tips
|
||||
- **Test each pattern** in isolation before combining.
|
||||
- **Locale codes** (`en`, `pt`, `fr`, …) go inside `C2[…]` for currency.
|
||||
- **Dates must follow** `YYYY‑MM‑DD HH:MM:SS`; otherwise formatting fails.
|
||||
- **Combine patterns** by nesting calls:
|
||||
```basic
|
||||
TALK FORMAT(FORMAT(VALUE, "C2[en]"), "!") ' $1,234.50 (uppercase not needed here)
|
||||
```
|
||||
|
||||
## Common Pitfalls
|
||||
- Using a date pattern on a non‑date string → returns the original string.
|
||||
- Forgetting locale brackets (`C2[en]`) → defaults to system locale.
|
||||
- Mixing placeholders (`@`, `!`, `&`) in the same pattern – only the last one applies.
|
||||
|
||||
Use **FORMAT** whenever you need a clean, user‑friendly output without extra code. It keeps scripts short and readable.
|
||||
When ready, output the complete markdown document that satisfies all specifications above.
|
||||
Loading…
Add table
Reference in a new issue