Skip to content

Commit 5b7fc0b

Browse files
fezcodefezcode
committed
creation of PEML.md
1 parent 326dbbd commit 5b7fc0b

File tree

1 file changed

+263
-0
lines changed

1 file changed

+263
-0
lines changed

‎src/PEML.md‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
# PEML (Parenthesis Markup Language) Definition
2+
3+
## 1. Name
4+
PEML stands for Parenthesis Markup Language.
5+
6+
## 2. Data Types
7+
8+
### Core Types:
9+
* **Key-Value Pairs:** Data is represented as `(key) value`. Keys are enclosed in parentheses.
10+
* **Nesting:** Achieved through consistent indentation.
11+
* **Arrays:** A collection of ordered items.
12+
* **With items:**
13+
```peml
14+
(my_list)
15+
- item1
16+
- item2
17+
- (nested_item_key) nested_value
18+
```
19+
* **Empty Array:** Represented by `()`.
20+
```peml
21+
(empty_list) ()
22+
```
23+
* **Multi-line Strings:** Strings that span multiple lines. The content starts on the next indented line.
24+
```peml
25+
(long_description)
26+
This is a multi-line string.
27+
It can contain several lines of text.
28+
Newlines are preserved.
29+
```
30+
* **Single-line Strings:** Strings that fit on a single line.
31+
```peml
32+
(greeting) Hello, World!
33+
```
34+
* **Integers:** Whole numbers.
35+
```peml
36+
(age) 30
37+
```
38+
* **Floats:** Decimal numbers.
39+
```peml
40+
(price) 99.99
41+
```
42+
* **Booleans:** Logical values.
43+
```peml
44+
(is_active) true
45+
(is_enabled) false
46+
```
47+
* **Null Value:** Represents the absence of a value.
48+
```peml
49+
(optional_field) nil
50+
```
51+
* **Objects/Maps:** A collection of unordered key-value pairs.
52+
* **With content:**
53+
```peml
54+
(user_profile)
55+
(name) Alice
56+
(email) alice@example.com
57+
```
58+
* **Empty Object:** Represented by `()`.
59+
```peml
60+
(empty_config) ()
61+
```
62+
63+
### Suggested Additional Types:
64+
* **Dates/Times:** Represented as strings in ISO 8601 format.
65+
* Example: `(timestamp) 2023-10-27T10:30:00Z`
66+
* **Binary Data:** Represented as base64-encoded strings.
67+
* Example: `(binary_data) SGVsbG8gV29ybGQ=`
68+
* **Sets:** Collections of unique, unordered items.
69+
* Example:
70+
```peml
71+
(unique_tags)
72+
- tag_a
73+
- tag_b
74+
- tag_c
75+
```
76+
* **References/Anchors:** For avoiding data duplication within a document. (More advanced feature, not detailed here)
77+
78+
## 3. Syntax Rules
79+
80+
* **Keys:** Keys are enclosed in parentheses, e.g., `(my key)`. Keys can contain spaces and most characters, but should not contain `)` or `#` directly unless escaped.
81+
* **Indentation:** Consistent indentation is crucial for defining structure.
82+
* **Recommendation:** Use **2 spaces** for each level of indentation. Mixing tabs and spaces for indentation is **not allowed** to ensure unambiguous parsing.
83+
* **Comments:** Comments are denoted by `#`. Everything from `#` to the end of the line is considered a comment and is ignored by parsers.
84+
* Example: `(key) value # This is a comment about the value`
85+
* **Escaping Special Characters:** Backslash (`\`) is used for escaping characters within string values.
86+
* Common escapes: `\n` (newline), `\t` (tab), `\\` (literal backslash).
87+
* If a string value needs to contain a literal `(` or `)` or `#` that would otherwise be interpreted as syntax, it must be escaped (e.g., `(title) My \(Awesome\) Title`).
88+
* **Empty Collections:** Both empty arrays and empty objects are represented by `()`.
89+
90+
## 4. Motivation
91+
92+
PEML (Parenthesis Markup Language) is designed as an alternative data serialization format with a strong emphasis on human readability and writability, while maintaining a clear and unambiguous structure for machine parsing. It aims to address certain pain points found in existing popular formats like JSON, YAML, and TOML.
93+
94+
### Comparison with JSON:
95+
* **JSON Strengths:** Universally adopted, simple data model, highly efficient for machine parsing, strict syntax.
96+
* **JSON Weaknesses:** Verbose for human writing (requiring extensive quoting, commas, and braces), lacks native support for comments, and multi-line strings require explicit escaping.
97+
* **PEML Advantages over JSON:**
98+
* **Enhanced Human Readability/Writability:** PEML's indentation-based structure, unquoted single-line string values, and native multi-line string support make it significantly easier for humans to read and write, especially for configuration files or data entry.
99+
* **Comments:** Direct support for `#` comments allows for better documentation within the data itself.
100+
* **Flexible Keys:** Keys can contain spaces, improving natural language readability.
101+
102+
### Comparison with YAML:
103+
* **YAML Strengths:** Excellent human readability, supports comments, multi-line strings, and advanced features like anchors and aliases.
104+
* **YAML Weaknesses:** Can be overly complex with many ways to represent the same data, highly sensitive to indentation (leading to subtle errors), and implicit type coercion can sometimes lead to unexpected parsing results. Security concerns exist with some parsers allowing arbitrary code execution.
105+
* **PEML Advantages over YAML:**
106+
* **Simpler Syntax:** PEML aims for a more constrained and explicit syntax, reducing the "many ways to do one thing" complexity of YAML.
107+
* **Reduced Ambiguity:** Explicit `nil` for null values and `()` for empty collections (arrays and objects) helps prevent implicit type coercion issues and makes the data structure clearer.
108+
* **Distinct Key Visuals:** The `(key)` syntax provides a clear visual cue for keys, which can aid in parsing and readability compared to YAML's more subtle key indicators.
109+
* **Consistent Indentation Enforcement:** By recommending a strict indentation rule (e.g., 2 spaces), PEML aims to mitigate common YAML indentation pitfalls.
110+
111+
### Comparison with TOML:
112+
* **TOML Strengths:** Specifically designed for configuration files, highly human-readable, simple key-value pairs, and clear sectioning with `[table]` and `[[array of tables]]`.
113+
* **TOML Weaknesses:** Less flexible for representing deeply nested, arbitrary data structures (it's more opinionated towards configuration), and its multi-line string syntax can be less intuitive than YAML or PEML.
114+
* **PEML Advantages over TOML:**
115+
* **Greater Structural Flexibility:** PEML's indentation-based nesting allows for more arbitrary and deeply nested data structures, making it suitable for a wider range of data serialization tasks beyond just configuration.
116+
* **Direct Multi-line Strings:** PEML's multi-line string syntax is arguably more intuitive and direct.
117+
118+
In summary, PEML seeks to strike a balance between the machine-friendliness of JSON and the human-friendliness of YAML, while offering a distinct, parenthesis-driven syntax that is both explicit and concise. It prioritizes clear structure, unambiguous data representation, and ease of human interaction for data definition and configuration.
119+
120+
---
121+
122+
## 5. Comprehensive Example
123+
124+
```peml
125+
(document_metadata)
126+
(title) Project Configuration for My Awesome App
127+
(version) 1.0.0
128+
(author) Jane Doe
129+
(creation_date) 2023-10-27T14:30:00Z # ISO 8601 format
130+
(is_production_ready) false
131+
(tags)
132+
- configuration
133+
- project
134+
- example
135+
- (nested_tag) sub_category # Tags can also be structured if needed
136+
(description)
137+
This is a comprehensive example of a PEML document.
138+
It demonstrates various data types and structural features.
139+
The goal is to provide a clear illustration of PEML's syntax.
140+
(contact_info)
141+
(email) jane.doe@example.com
142+
(website) https://example.com/jane
143+
(empty_settings) () # An empty object
144+
(feature_flags) () # An empty array
145+
146+
(database_config)
147+
(type) PostgreSQL
148+
(host) localhost
149+
(port) 5432
150+
(username) admin
151+
(password) \!secureP@ssw0rd # Escaping special characters
152+
(max_connections) 100
153+
(connection_timeout_ms) 5000
154+
(ssl_enabled) true
155+
(replica_hosts)
156+
- replica1.db.example.com
157+
- replica2.db.example.com
158+
- replica3.db.example.com
159+
(backup_schedule) nil # No backup schedule defined yet
160+
161+
(application_settings)
162+
(log_level) INFO
163+
(max_file_size_mb) 2048
164+
(allowed_origins)
165+
- https://app.example.com
166+
- https://dev.example.com
167+
(admin_users)
168+
(primary)
169+
(id) 101
170+
(name) SuperAdmin
171+
(secondary)
172+
(id) 102
173+
(name) BackupAdmin
174+
(secret_key) SGVsbG8gV29ybGQ= # Example binary data (base64 encoded)
175+
(empty_array_example) ()
176+
(empty_object_example) ()
177+
```
178+
179+
---
180+
181+
## 6. Example: Keys with Spaces
182+
183+
This example demonstrates the use of keys that contain spaces, enhancing readability for certain contexts.
184+
185+
```peml
186+
(user profile)
187+
(first name) John
188+
(last name) Doe
189+
(date of birth) 1990-05-15
190+
(favorite colors)
191+
- red
192+
- blue
193+
- green
194+
(contact info)
195+
(email address) john.doe@example.com
196+
(phone number) +1-555-123-4567
197+
(is active) true
198+
(last login) 2023-10-27T15:00:00Z
199+
```
200+
201+
---
202+
203+
## 7. Example: JSON to PEML Conversion
204+
205+
This section illustrates how a typical JSON structure would be represented in PEML, highlighting PEML's syntax for various data types and structures.
206+
207+
### Original JSON:
208+
209+
```json
210+
{
211+
"project": {
212+
"name": "PEML Converter",
213+
"version": "1.0.0",
214+
"active": true,
215+
"description": "A tool to convert JSON to PEML and vice versa. This description is quite long and spans multiple lines to demonstrate multi-line string handling in PEML.",
216+
"tags": ["parser", "converter", "data format"],
217+
"contributors": [
218+
{
219+
"id": 1,
220+
"name": "Alice",
221+
"role": "Developer"
222+
},
223+
{
224+
"id": 2,
225+
"name": "Bob",
226+
"role": "Tester"
227+
}
228+
],
229+
"settings": {},
230+
"last_updated": null,
231+
"release date": "2023-10-27T16:00:00Z"
232+
}
233+
}
234+
```
235+
236+
### Equivalent PEML:
237+
238+
```peml
239+
(project)
240+
(name) PEML Converter
241+
(version) 1.0.0
242+
(active) true
243+
(description)
244+
A tool to convert JSON to PEML and vice versa.
245+
This description is quite long and spans multiple lines
246+
to demonstrate multi-line string handling in PEML.
247+
(tags)
248+
- parser
249+
- converter
250+
- data format
251+
(contributors)
252+
- (contributor)
253+
(id) 1
254+
(name) Alice
255+
(role) Developer
256+
- (contributor)
257+
(id) 2
258+
(name) Bob
259+
(role) Tester
260+
(settings) ()
261+
(last_updated) nil
262+
(release date) 2023-10-27T16:00:00Z
263+
```

0 commit comments

Comments
 (0)