@jondotsoy/don 0.0.2 → 0.0.4

package/README.md

@@ -1,32 +1,39 @@
 # DON: Directive Object Notation
 
-DON es un formato de serialización de datos legible por humanos, diseñado alrededor del concepto de directivas y subdirectivas. Combina la simplicidad de una sintaxis declarativa con la flexibilidad de estructuras anidadas, permitiendo definir configuraciones jerárquicas usando bloques de directivas intuitivos. Cada directiva puede aceptar argumentos y contener subdirectivas anidadas, haciéndolo ideal para archivos de configuración, definiciones de infraestructura y representación de datos estructurados donde la legibilidad y expresividad son prioridades.
+DON is a human-readable data serialization format designed around the concept of directives and subdirectives. It combines the simplicity of declarative syntax with the flexibility of nested structures, allowing you to define hierarchical configurations using intuitive directive blocks. Each directive can accept arguments and contain nested subdirectives, making it ideal for configuration files, infrastructure definitions, and structured data representation where readability and expressiveness are priorities.
 
-## Características Principales
+## Features
 
-- **Sintaxis Minimalista**: Menos caracteres especiales, más legibilidad
-- **Procesamiento Secuencial**: Las directivas se procesan como un pipeline, permitiendo sobrescritura y composición incremental
-- **Anidación Flexible**: Soporta jerarquías de cualquier profundidad
-- **Múltiples Tipos de Datos**: Keywords, strings, numbers, booleans y null
-- **Comentarios**: Soporta comentarios de línea (`//`, `#`) y multilínea (`/* */`)
-- **Sin Ambigüedades**: Reglas claras de parsing y delimitación
+- **Minimal Syntax**: Fewer special characters, more readability
+- **Sequential Processing**: Directives are processed as a pipeline, allowing overwriting and incremental composition
+- **Flexible Nesting**: Supports hierarchies of any depth
+- **Multiple Data Types**: Keywords, strings, numbers, booleans, and null
+- **Heredoc Support**: Multi-line content blocks for embedded scripts and text
+- **Comments**: Supports line comments (`//`, `#`) and multi-line comments (`/* */`)
+- **Unambiguous**: Clear parsing rules and delimitation
 
-## Instalación
+## Installation
+
+### Using npm
 
 ```bash
 npm install @jondotsoy/don
 ```
 
+### Using Bun
+
 ```bash
 bun add @jondotsoy/don
 ```
 
-## Uso Básico
+## Usage
+
+### Basic Example
 
 ```typescript
 import { DocumentEncoder, LexerEncoder } from "@jondotsoy/don";
 
-// Parsear un documento DON
+// Parse a DON document
 const source = `
 name "my-app"
 version 1.0.0
@@ -36,381 +43,44 @@ container {
 }
 `;
 
-const lexer = new LexerEncoder();
-const tokens = lexer.encode(source);
-
 const document = new DocumentEncoder();
-const directives = document.encode(tokens);
+const directives = document.encode(source);
 
 console.log(directives);
 ```
 
-## Sintaxis Básica
-
-### Estructura de una Directiva
-
-Una directiva tiene la siguiente estructura:
-
-```
-<nombre> [argumentos...] [{ subdirectivas }]
-```
-
-**Componentes:**
-
-- **Nombre**: Identificador de la directiva (keyword, string, number o boolean)
-- **Argumentos**: Cero o más valores separados por espacios
-- **Bloque**: Opcional, contiene subdirectivas entre llaves `{ }`
-
-### Ejemplos
-
-**Directivas simples:**
-
-```don
-name "my-app"
-version 1.0.0
-enabled true
-port 8080
-```
-
-**Directivas con bloques:**
+### Using the Inspect Utility
 
-```don
-container {
-  image "nginx"
-  port 8080
-}
-```
-
-**Directivas con argumentos y bloques:**
+```typescript
+import { DocumentEncoder, LexerEncoder } from "@jondotsoy/don";
+import { inspect } from "@jondotsoy/don/utils";
 
-```don
+const source = `
 service "web" replicas 3 {
   container "nginx" {
     port 80
     image "nginx:latest"
   }
 }
-```
-
-**Directivas repetidas:**
-
-```don
-container {
-  image "nginx"
-  port 80
-}
-
-container {
-  image "redis"
-  port 6379
-}
-```
-
-## Tipos de Datos
-
-DON reconoce los siguientes tipos de tokens:
-
-- **Keywords**: Identificadores que comienzan con letra o guion bajo (`name`, `version`, `container`)
-- **Strings**: Cadenas de texto entre comillas dobles o simples (`"texto"`, `'texto'`)
-  - Soportan caracteres escapados: `\"`, `\'`, `\\`
-- **Numbers**: Enteros o decimales (`123`, `45.67`)
-  - Pueden incluir guiones bajos como separadores: `1_000_000`
-- **Booleans**: Valores `true` o `false`
-- **Null**: Valor nulo `null`
-- **Punctuators**: Símbolos delimitadores: `{`, `}`, `[`, `]`, `,`, `+`, `-`, `/`, `*`, `<`, `>`
-- **Comments**:
-  - Línea: `// comentario` o `# comentario`
-  - Multilínea: `/* comentario */`
-
-## Reglas de Sintaxis
-
-1. **Nombre de directiva**: Puede ser un keyword, string, number o boolean
-2. **Argumentos**: Cero o más tokens separados por espacios
-3. **Bloque de subdirectivas**: Opcional, delimitado por llaves `{ }`
-4. **Delimitación**: Las directivas se separan por saltos de línea
-5. **Anidación**: Las subdirectivas siguen las mismas reglas
-6. **Restricción**: No puede haber tokens después de un bloque en la misma línea
-
-**Sintaxis válida:**
-
-```don
-// Directiva simple
-name "my-app"
-version 1.0.0
-
-// Directiva con bloque
-container {
-  image "nginx"
-  port 8080
-}
-
-// Comentarios
-# Comentario de línea
-/* Comentario multilínea */
-```
-
-**Sintaxis inválida:**
-
-```don
-// ❌ Tokens después del bloque
-container { image "nginx" } extra
-
-// ❌ String sin cerrar
-name "unclosed
-```
-
-## Casos de Uso
-
-### Archivos de Configuración
-
-```don
-app "my-service" {
-  version 2.1.0
-  environment "production"
-
-  database {
-    host "localhost"
-    port 5432
-    name "mydb"
-  }
-
-  cache {
-    enabled true
-    ttl 3600
-  }
-}
-```
-
-### Definiciones de Infraestructura (Kubernetes)
-
-```yaml
-apiVersion: v1
-kind: Pod
-metadata:
-  name: command-demo
-  labels:
-    purpose: demonstrate-command
-spec:
-  containers:
-    - name: command-demo-container
-      image: debian
-      command: ["printenv"]
-      args: ["HOSTNAME", "KUBERNETES_PORT"]
-  restartPolicy: OnFailure
-```
-
-```don
-apiVersion v1 {
-  pod {
-    metadata {
-      name "command-demo"
-      labels {
-        purpose "demonstrate-command"
-      }
-    }
-    spec {
-      restartPolicy "OnFailure"
-      container debian "command-demo-container" {
-        command printenv HOSTNAME KUBERNETES_PORT
-      }
-    }
-  }
-}
-```
-
-### Schemas de Datos
-
-```don
-schema "user" {
-  id integer primaryKey autoIncrement
-  email string unique required
-  name string required
-  createdAt timestamp default now
-}
-```
-
-### Reglas de Seguridad (Firebase)
-
-```don
-service "firebase.storage" {
-  match "/b/{bucket}/o" {
-    match "/someFolder/{fileName}" {
-      allow read write {
-        if "request.auth" "!=" null
-      }
-    }
-  }
-}
-```
-
-### Servicios con Múltiples Contenedores
-
-```don
-service "my-service" {
-  replicas 2
-  container {
-    image "my-image"
-    port 8080
-  }
-  container {
-    image "my-other-image"
-    port 8081
-  }
-}
-```
-
-## Equivalencias con JSON
-
-DON ofrece una sintaxis más limpia y legible para representar estructuras de datos comunes en JSON:
-
-**Propiedades simples:**
-
-- `{"name":"foo"}` → `name "foo"`
-- `{"version":1}` → `version 1`
-- `{"private": true}` → `private true`
-
-**Objetos anidados:**
-
-```json
-{ "name": "foo", "meta": { "format": "json", "version": 1 } }
-```
-
-```don
-name "foo"
-meta {
-  format "json"
-  version 1
-}
-```
-
-**Arrays o Listas:**
-
-```json
-{ "icons": ["foo", "taz"] }
-```
-
-```don
-icons {
-  icon "foo"
-  icon "taz"
-}
-```
-
-## Equivalencias con YAML
-
-DON puede representar estructuras YAML de manera más concisa. Los tags de YAML (como `!!date`, `!!str`, `!!int`) se convierten en nombres de directivas en DON:
-
-**Tags de tipo:**
-
-```yaml
----
-createdAt: !!date 2002-04-28
-count: !!int 42
-description: !!str "Hello World"
-enabled: !!bool true
-```
-
-```don
-createdAt date "2002-04-28"
-count int 42
-description str "Hello World"
-enabled bool true
-```
-
-**Objetos anidados con tags:**
-
-```yaml
----
-metadata:
-  createdAt: !!date 2002-04-28
-  version: !!int 1
-```
-
-```don
-metadata {
-  createdAt date "2002-04-28"
-  version int 1
-}
-```
-
-## Inspiración
-
-DON toma inspiración de la sintaxis de Python para el paso de argumentos, permitiendo tanto argumentos posicionales como argumentos con nombre:
-
-```python
-# Python - Argumentos posicionales
-print("foo")
-
-# Python - Argumentos con nombre
-dict(name="foo")
-
-# Python - Combinación
-Container("nginx", replicas=3, port=80)
-```
-
-```don
-# DON - Argumentos posicionales
-print "foo"
-
-# DON - Argumentos con nombre (mediante subdirectivas)
-dict {
-  name "foo"
-}
-
-# DON - Combinación
-Container "nginx" {
-  replicas 3
-  port 80
-}
-```
-
-## Desarrollo
-
-### Scripts Disponibles
-
-```bash
-# Compilar el proyecto
-npm run build
-
-# Limpiar archivos compilados
-npm run clean
-
-# Formatear código
-npm run fmt
-
-# Verificar formato
-npm run lint
-```
+`;
 
-### Estructura del Proyecto
+const doc = new DocumentEncoder().encode(source);
 
+// Pretty-print the parsed document structure
+console.log(inspect(doc));
 ```
-.
-├── src/              # Código fuente TypeScript
-│   ├── lexer.ts      # Analizador léxico
-│   ├── document.ts   # Parser de documentos
-│   ├── chunk.ts      # Manejo de chunks
-│   └── utils/        # Utilidades
-├── lib/              # Código compilado
-│   └── esm/          # Módulos ES
-├── docs/             # Documentación
-└── index.ts          # Punto de entrada
-```
-
-## Documentación
-
-Para más información sobre DON, consulta la [documentación completa](./docs/index.md):
 
-- [Formato .DON](./docs/don-file.md): Especificación completa del formato
-- [Directivas](./docs/concepts/directive.md): Anatomía y uso de directivas
-- [Heredocs](./docs/concepts/heredoc.md): Contenido multilínea
-- [Tipos de Datos](./docs/concepts/types/): Especificación de tipos soportados
-- [Inspiración](./docs/inspiration.md): Objetivos y visión del proyecto
+## Documentation
 
-## Licencia
+For more information about DON, check out the [complete documentation](./docs/index.md):
 
-MIT
+- [DON File Format](./docs/don-file.md): Complete format specification
+- [Formal Specification v0](./docs/specs/v0/spec.md): Draft specification (v0)
+- [Directives](./docs/concepts/directive.md): Anatomy and usage of directives
+- [Heredocs](./docs/concepts/heredoc.md): Multi-line content blocks
+- [Data Types](./docs/concepts/types/): Specification of supported types
+- [Inspiration](./docs/inspiration.md): Project goals and vision
 
-## Autor
+## License
 
-[@jondotsoy](https://github.com/jondotsoy)
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jondotsoy/don",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "DON (Directive Object Notation) - A human-readable data serialization format based on directives and subdirectives for configuration files, infrastructure definitions, and structured data",
   "keywords": [
     "don",
@@ -26,6 +26,10 @@
     ".": {
       "types": "./lib/esm/index.d.ts",
       "import": "./lib/esm/index.js"
+    },
+    "./utils": {
+      "types": "./lib/esm/utils/inspect.d.ts",
+      "import": "./lib/esm/utils/inspect.js"
     }
   },
   "files": [