Skip to content

Commit 4ff1aef

Browse files
FolydFolyd
committed
More std library docs
1 parent d39faa4 commit 4ff1aef

File tree

4 files changed

+270
-32
lines changed

4 files changed

+270
-32
lines changed

‎docs/std/http.mdx

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,258 @@
11
# std.http
2+
3+
The `std.http` module provides functions for making HTTP requests to external services and APIs.
4+
5+
## get(url: string, headers?: object)
6+
7+
Makes an HTTP GET request to the specified URL.
8+
9+
**Parameters**:
10+
- `url`: The URL to send the request to
11+
- `headers` (optional): An object containing HTTP headers
12+
13+
**Return Type**: `object` with the following properties:
14+
- `status`: HTTP status code (number)
15+
- `statusText`: HTTP status message (string)
16+
- `ok`: Whether the request was successful (boolean)
17+
- `headers`: Response headers (object)
18+
- `text`: Response body as text (string)
19+
- `json`: Response body parsed as JSON (if applicable)
20+
21+
**Example**:
22+
```rust
23+
use std.http;
24+
25+
// Simple GET request
26+
let response = http.get("https://api.example.com/users");
27+
if (response.ok) {
28+
println(response.json);
29+
} else {
30+
println(`Error: ${response.status} ${response.statusText}`);
31+
}
32+
33+
// GET request with headers
34+
let response = http.get("https://api.example.com/users", {
35+
"Authorization": "Bearer token123",
36+
"Accept": "application/json"
37+
});
38+
```
39+
40+
## post(url: string, body: string, headers?: object)
41+
42+
Makes an HTTP POST request to the specified URL with the given body.
43+
44+
**Parameters**:
45+
- `url`: The URL to send the request to
46+
- `body`: The request body as a string
47+
- `headers` (optional): An object containing HTTP headers
48+
49+
**Return Type**: `object` (same as get)
50+
51+
**Example**:
52+
```rust
53+
use std.http;
54+
55+
// POST request with JSON body
56+
let response = http.post(
57+
"https://api.example.com/users",
58+
'{"name": "John", "email": "john@example.com"}',
59+
{
60+
"Content-Type": "application/json",
61+
"Authorization": "Bearer token123"
62+
}
63+
);
64+
65+
if (response.ok) {
66+
println(`User created with ID: ${response.json.id}`);
67+
} else {
68+
println(`Error: ${response.status} ${response.statusText}`);
69+
}
70+
```
71+
72+
## put(url: string, body: string, headers?: object)
73+
74+
Makes an HTTP PUT request to the specified URL with the given body.
75+
76+
**Parameters**:
77+
- `url`: The URL to send the request to
78+
- `body`: The request body as a string
79+
- `headers` (optional): An object containing HTTP headers
80+
81+
**Return Type**: `object` (same as get)
82+
83+
**Example**:
84+
```rust
85+
use std.http;
86+
87+
// PUT request to update a resource
88+
let response = http.put(
89+
"https://api.example.com/users/123",
90+
'{"name": "John Updated", "email": "john.updated@example.com"}',
91+
{
92+
"Content-Type": "application/json",
93+
"Authorization": "Bearer token123"
94+
}
95+
);
96+
97+
if (response.ok) {
98+
println("User updated successfully");
99+
} else {
100+
println(`Error: ${response.status} ${response.statusText}`);
101+
}
102+
```
103+
104+
## delete(url: string, headers?: object)
105+
106+
Makes an HTTP DELETE request to the specified URL.
107+
108+
**Parameters**:
109+
- `url`: The URL to send the request to
110+
- `headers` (optional): An object containing HTTP headers
111+
112+
**Return Type**: `object` (same as get)
113+
114+
**Example**:
115+
```rust
116+
use std.http;
117+
118+
// DELETE request to remove a resource
119+
let response = http.delete(
120+
"https://api.example.com/users/123",
121+
{
122+
"Authorization": "Bearer token123"
123+
}
124+
);
125+
126+
if (response.ok) {
127+
println("User deleted successfully");
128+
} else {
129+
println(`Error: ${response.status} ${response.statusText}`);
130+
}
131+
```
132+
133+
## patch(url: string, body: string, headers?: object)
134+
135+
Makes an HTTP PATCH request to the specified URL with the given body.
136+
137+
**Parameters**:
138+
- `url`: The URL to send the request to
139+
- `body`: The request body as a string
140+
- `headers` (optional): An object containing HTTP headers
141+
142+
**Return Type**: `object` (same as get)
143+
144+
**Example**:
145+
```rust
146+
use std.http;
147+
148+
// PATCH request to partially update a resource
149+
let response = http.patch(
150+
"https://api.example.com/users/123",
151+
'{"email": "new.email@example.com"}',
152+
{
153+
"Content-Type": "application/json",
154+
"Authorization": "Bearer token123"
155+
}
156+
);
157+
158+
if (response.ok) {
159+
println("User partially updated successfully");
160+
} else {
161+
println(`Error: ${response.status} ${response.statusText}`);
162+
}
163+
```
164+
165+
## head(url: string, headers?: object)
166+
167+
Makes an HTTP HEAD request to the specified URL.
168+
169+
**Parameters**:
170+
- `url`: The URL to send the request to
171+
- `headers` (optional): An object containing HTTP headers
172+
173+
**Return Type**: `object` (same as get, but typically without body content)
174+
175+
**Example**:
176+
```rust
177+
use std.http;
178+
179+
// HEAD request to check if a resource exists
180+
let response = http.head("https://api.example.com/users/123");
181+
182+
if (response.ok) {
183+
println("Resource exists");
184+
println(`Last-Modified: ${response.headers["last-modified"]}`);
185+
} else {
186+
println("Resource not found");
187+
}
188+
```
189+
190+
## Usage Examples
191+
192+
## Fetching JSON Data
193+
```rust
194+
use std.http;
195+
196+
// Get JSON data from an API
197+
let response = http.get("https://api.example.com/data");
198+
if (response.ok) {
199+
// Access parsed JSON directly
200+
let items = response.json.items;
201+
for (item in items) {
202+
println(`${item.id}: ${item.name}`);
203+
}
204+
} else {
205+
println(`Failed to fetch data: ${response.status}`);
206+
}
207+
```
208+
209+
## Handling Authentication
210+
```rust
211+
use std.http;
212+
213+
// Function to make authenticated requests
214+
fn authenticated_request(url, method, body = nil) {
215+
let token = "your-auth-token";
216+
let headers = {
217+
"Authorization": `Bearer ${token}`,
218+
"Content-Type": "application/json"
219+
};
220+
221+
if (method == "GET") {
222+
return http.get(url, headers);
223+
} else if (method == "POST") {
224+
return http.post(url, body, headers);
225+
} else if (method == "PUT") {
226+
return http.put(url, body, headers);
227+
} else if (method == "DELETE") {
228+
return http.delete(url, headers);
229+
}
230+
231+
return nil;
232+
}
233+
234+
// Use the function
235+
let user_data = authenticated_request("https://api.example.com/me", "GET");
236+
println(user_data.json);
237+
```
238+
239+
## Submitting Form Data
240+
```rust
241+
use std.http;
242+
243+
// Submit form data
244+
let form_data = 'name=John&email=john@example.com&message=Hello';
245+
let response = http.post(
246+
"https://example.com/contact",
247+
form_data,
248+
{
249+
"Content-Type": "application/x-www-form-urlencoded"
250+
}
251+
);
252+
253+
if (response.ok) {
254+
println("Form submitted successfully");
255+
} else {
256+
println(`Form submission failed: ${response.text}`);
257+
}
258+
```

‎docs/std/random.mdx

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,8 @@
22

33
The `std.random` module provides a comprehensive set of functions for random number generation, including basic random numbers, range-based selections, and various probability distributions.
44

5-
## Functions
65

7-
### seed(value: int) -> void
6+
## seed(value: int) -> void
87

98
Sets the seed for the random number generator to produce reproducible sequences of random numbers.
109

@@ -19,7 +18,7 @@ random.seed(42);
1918
// Now all subsequent random operations will produce the same sequence
2019
```
2120

22-
### random() -> float
21+
## random() -> float
2322

2423
Generates a random floating-point number between 0.0 (inclusive) and 1.0 (exclusive).
2524

@@ -34,7 +33,7 @@ let value = random.random();
3433
print(value); // Outputs: 0.7123889...
3534
```
3635

37-
### randint(min: int, max: int) -> int
36+
## randint(min: int, max: int) -> int
3837

3938
Generates a random integer between min and max (inclusive).
4039

@@ -53,7 +52,7 @@ let dice_roll = random.randint(1, 6);
5352
print(dice_roll); // Outputs a number between 1 and 6
5453
```
5554

56-
### uniform(min: float, max: float) -> float
55+
## uniform(min: float, max: float) -> float
5756

5857
Generates a random floating-point number from a uniform distribution between min and max.
5958

@@ -72,7 +71,7 @@ let temperature = random.uniform(20.0, 30.0);
7271
print(temperature); // Outputs: 25.7392...
7372
```
7473

75-
### range(start: int, end: int, step?: int) -> int
74+
## range(start: int, end: int, step?: int) -> int
7675

7776
Generates a random integer from a range with optional step size.
7877

@@ -93,7 +92,7 @@ let even = random.range(0, 10, 2);
9392
print(even); // Outputs: 0, 2, 4, 6, or 8
9493
```
9594

96-
### choice(list: array) -> any
95+
## choice(list: array) -> any
9796

9897
Randomly selects an element from a list.
9998

@@ -112,7 +111,7 @@ let color = random.choice(colors);
112111
print(color); // Outputs: one of the colors
113112
```
114113

115-
### normal(mean: float, std_dev: float) -> float
114+
## normal(mean: float, std_dev: float) -> float
116115

117116
Generates a random floating-point number from a normal (Gaussian) distribution.
118117

@@ -132,7 +131,7 @@ let iq = random.normal(100.0, 15.0);
132131
print(iq); // Outputs: 97.234...
133132
```
134133

135-
### exponential(lambda: float) -> float
134+
## exponential(lambda: float) -> float
136135

137136
Generates a random floating-point number from an exponential distribution.
138137

@@ -151,7 +150,7 @@ let wait_time = random.exponential(0.5);
151150
print(wait_time); // Outputs: 1.386...
152151
```
153152

154-
### bool() -> boolean
153+
## bool() -> boolean
155154

156155
Generates a random boolean value.
157156

‎docs/std/serde.mdx

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,7 @@
22

33
The `std.serde` module provides functionality for JSON serialization and deserialization. It allows you to convert between AIScript values and JSON format, with support for both string and file operations.
44

5-
## Functions
6-
7-
### from_str(json_str: string) -> any
5+
## from_str(json_str: string) -> any
86

97
Parses a JSON string and converts it into an AIScript value.
108

@@ -27,7 +25,7 @@ let data = serde.from_str(json);
2725
print(data.name); // Outputs: John
2826
```
2927

30-
### to_str(value: any, pretty?: boolean) -> string
28+
## to_str(value: any, pretty?: boolean) -> string
3129

3230
Converts an AIScript value to a JSON string.
3331

@@ -70,7 +68,7 @@ print(str2);
7068
// }
7169
```
7270

73-
### from_file(path: string) -> any
71+
## from_file(path: string) -> any
7472

7573
Reads and parses a JSON file into an AIScript value.
7674

@@ -94,7 +92,7 @@ let config = serde.from_file("config.json");
9492
print(config.port); // Outputs: 8080
9593
```
9694

97-
### to_file(path: string, value: any, pretty?: boolean) -> boolean
95+
## to_file(path: string, value: any, pretty?: boolean) -> boolean
9896

9997
Writes an AIScript value to a file in JSON format.
10098

0 commit comments

Comments
 (0)