312 lines
No EOL
6.6 KiB
Markdown
312 lines
No EOL
6.6 KiB
Markdown
# READ
|
|
|
|
The `READ` keyword loads content from files stored in the bot's drive storage, enabling bots to access documents, data files, and other stored resources.
|
|
|
|
---
|
|
|
|
## Syntax
|
|
|
|
```basic
|
|
content = READ "filename"
|
|
content = READ "path/to/filename"
|
|
data = READ "filename.csv" AS TABLE
|
|
lines = READ "filename.txt" AS LINES
|
|
```
|
|
|
|
---
|
|
|
|
## Parameters
|
|
|
|
| Parameter | Type | Description |
|
|
|-----------|------|-------------|
|
|
| `filename` | String | Path to the file in the bot's storage |
|
|
| `AS TABLE` | Flag | Parse CSV/Excel files as structured data |
|
|
| `AS LINES` | Flag | Return content as array of lines |
|
|
|
|
---
|
|
|
|
## Description
|
|
|
|
`READ` retrieves file content from the bot's configured storage (drive bucket). It supports:
|
|
|
|
- Text files (`.txt`, `.md`, `.json`, `.xml`, `.csv`)
|
|
- Documents (`.pdf`, `.docx`) — automatically extracts text
|
|
- Spreadsheets (`.xlsx`, `.csv`) — can parse as structured data
|
|
- Binary files — returned as base64 encoded string
|
|
|
|
The file path is relative to the bot's storage root. Use forward slashes for subdirectories.
|
|
|
|
---
|
|
|
|
## Examples
|
|
|
|
### Basic File Read
|
|
|
|
```basic
|
|
' Read a text file
|
|
content = READ "welcome-message.txt"
|
|
TALK content
|
|
```
|
|
|
|
### Read from Subdirectory
|
|
|
|
```basic
|
|
' Read file from nested folder
|
|
template = READ "templates/email/welcome.html"
|
|
```
|
|
|
|
### Read JSON Data
|
|
|
|
```basic
|
|
' Read and parse JSON configuration
|
|
config_text = READ "config.json"
|
|
config = JSON_PARSE(config_text)
|
|
|
|
TALK "Current theme: " + config.theme
|
|
```
|
|
|
|
### Read CSV as Table
|
|
|
|
```basic
|
|
' Load CSV data as structured table
|
|
products = READ "inventory/products.csv" AS TABLE
|
|
|
|
FOR EACH product IN products
|
|
TALK product.name + ": $" + product.price
|
|
NEXT
|
|
```
|
|
|
|
### Read as Lines
|
|
|
|
```basic
|
|
' Read file as array of lines
|
|
faq_lines = READ "faq.txt" AS LINES
|
|
|
|
TALK "We have " + LEN(faq_lines) + " FAQ entries"
|
|
|
|
FOR EACH line IN faq_lines
|
|
IF INSTR(line, user_question) > 0 THEN
|
|
TALK "Found relevant FAQ: " + line
|
|
END IF
|
|
NEXT
|
|
```
|
|
|
|
### Read PDF Document
|
|
|
|
```basic
|
|
' Extract text from PDF
|
|
contract_text = READ "documents/contract.pdf"
|
|
TALK "Contract length: " + LEN(contract_text) + " characters"
|
|
|
|
' Use LLM to analyze
|
|
summary = LLM "Summarize the key points of this contract:\n\n" + contract_text
|
|
TALK summary
|
|
```
|
|
|
|
### Read Excel Spreadsheet
|
|
|
|
```basic
|
|
' Load Excel data
|
|
sales_data = READ "reports/sales-q1.xlsx" AS TABLE
|
|
|
|
total = 0
|
|
FOR EACH row IN sales_data
|
|
total = total + row.amount
|
|
NEXT
|
|
|
|
TALK "Total Q1 sales: $" + FORMAT(total, "#,##0.00")
|
|
```
|
|
|
|
---
|
|
|
|
## Working with Different File Types
|
|
|
|
### Text Files
|
|
|
|
```basic
|
|
' Plain text - returned as string
|
|
notes = READ "notes.txt"
|
|
readme = READ "README.md"
|
|
```
|
|
|
|
### JSON Files
|
|
|
|
```basic
|
|
' JSON - returned as string, use JSON_PARSE for object
|
|
json_text = READ "data.json"
|
|
data = JSON_PARSE(json_text)
|
|
```
|
|
|
|
### CSV Files
|
|
|
|
```basic
|
|
' CSV as string
|
|
csv_raw = READ "data.csv"
|
|
|
|
' CSV as structured table (recommended)
|
|
csv_data = READ "data.csv" AS TABLE
|
|
first_row = csv_data[0]
|
|
```
|
|
|
|
### Documents
|
|
|
|
```basic
|
|
' PDF - text extracted automatically
|
|
pdf_content = READ "report.pdf"
|
|
|
|
' Word documents - text extracted automatically
|
|
doc_content = READ "proposal.docx"
|
|
```
|
|
|
|
---
|
|
|
|
## Error Handling
|
|
|
|
```basic
|
|
ON ERROR RESUME NEXT
|
|
|
|
content = READ "optional-file.txt"
|
|
|
|
IF ERROR THEN
|
|
PRINT "File not found, using default"
|
|
content = "Default content"
|
|
END IF
|
|
```
|
|
|
|
### Check File Exists
|
|
|
|
```basic
|
|
' List directory to check if file exists
|
|
files = LIST "documents/"
|
|
|
|
found = false
|
|
FOR EACH file IN files
|
|
IF file.name = "report.pdf" THEN
|
|
found = true
|
|
EXIT FOR
|
|
END IF
|
|
NEXT
|
|
|
|
IF found THEN
|
|
content = READ "documents/report.pdf"
|
|
ELSE
|
|
TALK "Report not found. Would you like me to generate one?"
|
|
END IF
|
|
```
|
|
|
|
---
|
|
|
|
## Common Use Cases
|
|
|
|
### Load Email Template
|
|
|
|
```basic
|
|
' Read HTML template and fill variables
|
|
template = READ "templates/order-confirmation.html"
|
|
|
|
' Replace placeholders
|
|
email_body = REPLACE(template, "{{customer_name}}", customer.name)
|
|
email_body = REPLACE(email_body, "{{order_id}}", order.id)
|
|
email_body = REPLACE(email_body, "{{total}}", FORMAT(order.total, "$#,##0.00"))
|
|
|
|
SEND MAIL customer.email, "Order Confirmation", email_body
|
|
```
|
|
|
|
### Process Data File
|
|
|
|
```basic
|
|
' Read customer list and send personalized messages
|
|
customers = READ "campaigns/target-customers.csv" AS TABLE
|
|
|
|
FOR EACH customer IN customers
|
|
IF customer.opted_in = "yes" THEN
|
|
message = "Hi " + customer.first_name + ", check out our new products!"
|
|
SEND SMS customer.phone, message
|
|
END IF
|
|
NEXT
|
|
|
|
TALK "Campaign sent to " + LEN(customers) + " customers"
|
|
```
|
|
|
|
### Load Bot Configuration
|
|
|
|
```basic
|
|
' Read bot settings from file
|
|
settings_text = READ "bot-settings.json"
|
|
settings = JSON_PARSE(settings_text)
|
|
|
|
' Apply settings
|
|
SET BOT MEMORY "greeting", settings.greeting
|
|
SET BOT MEMORY "language", settings.language
|
|
SET BOT MEMORY "max_retries", settings.max_retries
|
|
```
|
|
|
|
### Knowledge Base Lookup
|
|
|
|
```basic
|
|
' Read FAQ document for quick lookups
|
|
faq_content = READ "knowledge/faq.md"
|
|
|
|
' Search for relevant section
|
|
IF INSTR(user_question, "return") > 0 THEN
|
|
' Extract return policy section
|
|
start_pos = INSTR(faq_content, "## Return Policy")
|
|
end_pos = INSTR(faq_content, "##", start_pos + 1)
|
|
policy = MID(faq_content, start_pos, end_pos - start_pos)
|
|
TALK policy
|
|
END IF
|
|
```
|
|
|
|
---
|
|
|
|
## File Path Rules
|
|
|
|
| Path | Description |
|
|
|------|-------------|
|
|
| `file.txt` | Root of bot's storage |
|
|
| `folder/file.txt` | Subdirectory |
|
|
| `folder/sub/file.txt` | Nested subdirectory |
|
|
| `../file.txt` | **Not allowed** — no parent traversal |
|
|
| `/absolute/path` | **Not allowed** — paths are always relative |
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Configure storage settings in `config.csv`:
|
|
|
|
```csv
|
|
name,value
|
|
drive-provider,seaweedfs
|
|
drive-url,http://localhost:8333
|
|
drive-bucket,my-bot
|
|
drive-read-timeout,30
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Notes
|
|
|
|
- Implemented in Rust under `src/file/mod.rs`
|
|
- Automatically detects file encoding (UTF-8, UTF-16, etc.)
|
|
- PDF extraction uses `pdf-extract` crate
|
|
- DOCX extraction parses XML content
|
|
- Maximum file size: 50MB (configurable)
|
|
- Files are cached in memory for repeated reads
|
|
|
|
---
|
|
|
|
## Related Keywords
|
|
|
|
- [WRITE](keyword-write.md) — Save content to files
|
|
- [LIST](keyword-list.md) — List files in a directory
|
|
- [DOWNLOAD](keyword-download.md) — Download files from URLs
|
|
- [UPLOAD](keyword-upload.md) — Upload files to storage
|
|
- [DELETE FILE](keyword-delete-file.md) — Remove files
|
|
- [GET](keyword-get.md) — Read from URLs or files
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
`READ` is the primary keyword for accessing stored files. It handles text extraction from various document formats, supports structured data parsing for CSV/Excel files, and integrates seamlessly with the bot's storage system. Use it to load templates, process data files, access configuration, and work with uploaded documents. |