yini-cli 1.0.0-alpha.3 → 1.0.1-beta.1

package/README.md

@@ -1,5 +1,7 @@
 # YINI-CLI
-Command-line tool for working with YINI configuration files. A human-friendly config format — like INI, but with type-safe values, nested sections, comments, minimal syntax noise, and optional strict mode.
+**Command-line tool for working with YINI configuration files. Validate, inspect, and convert to JSON with pretty output.**
+
+*YINI aims to be a human-friendly config format: like INI, but with type-safe values, nested sections, comments, minimal syntax noise, and optional strict mode.*
 
 [![npm version](https://img.shields.io/npm/v/yini-parser.svg)](https://www.npmjs.com/package/yini-parser) [![All Tests](https://github.com/YINI-lang/yini-cli/actions/workflows/run-all-tests.yml/badge.svg)](https://github.com/YINI-lang/yini-cli/actions/workflows/run-all-tests.yml)
 
@@ -7,27 +9,33 @@ Command-line tool for working with YINI configuration files. A human-friendly co
 
 ## 🙋‍♀️ Why YINI?
 - **YINI is an alternative** to other great config formats like INI, JSON, YAML, XML, and TOML — designed for clarity, simplicity, and straightforward section nesting.
-- **Started as a personal project and a research challenge:** Aiming for something more readable than JSON, more structured than INI, and less surprising than YAML.
+- **Started as a personal project and a research challenge:** Provides structure similar to INI, with features inspired by JSON and YAML.
 - **Built for clarity:**
-    * Easy to read and write for humans, especially for nested sections.
-    * Not too much syntax noise.
-    * Just enough structure for real-world configs.
-- **A little bit of fun and joy:**
-    * Created to scratch our own itch — if you like it too, that's a bonus!
+    * Uses minimal syntax for humans, especially for nested sections.
+    * Uses a concise syntax, aims to not have too much syntax noise.
+    * Supports commonly used configuration structures.
+- *Originated from practical needs **for configuration clarity, simplicity, minimalism, and flexibility**.
 
 ---
 
 ## 💡 What is YINI?
-- **Simple like INI** — but with strong typing, comments, and nested sections.
-- **Easy to read and write** — minimal syntax noise, maximum clarity.
-- **Clear, minimal section nesting** — no painful indentation or long dot-delimited keys.
+- **INI-inspired** — with added support for typing, comments, and nested sections.
+- **Uses minimal syntax** — minimal syntax noise, maximum clarity.
+- Section nesting **without requiring indentation or dot-delimited keys**.
 - **Supports strict and lenient modes**, and all major data types.
-- Both **human-friendly** and **machine-friendly**.
+- Designed for compatibility with both **manual editing** and **automation**.
 - 👉 See [how YINI compares to JSON, YAML, INI, and TOML](https://github.com/YINI-lang/yini-parser-typescript/tree/main/examples/compare-formats.md).
 - Want the full syntax reference? See the [YINI Specification](https://github.com/YINI-lang/YINI-spec).
 
 ---
 
+## Intro to YINI Config Format
+**YINI** is a simple and readable configuration format. Sections are defined with `^ SectionName`, and values are assigned using `key = value`. The format supports common data types (same as those found in JSON), including strings, numbers, booleans, nulls, and lists. 
+
+To learn more, see the [Getting Started: Intro to YINI Config Format](https://github.com/YINI-lang/YINI-spec/blob/develop/Docs/Intro-to-YINI-Config-Format.md) tutorial.
+
+---
+
 ## Usage
 
 ### Installation
@@ -40,18 +48,47 @@ Command-line tool for working with YINI configuration files. A human-friendly co
 
 2. **Verify installation**  
     Run this in your terminal:
-    ```
+    ```bash
     yini --version
     ```
     Should print the version (e.g., 1.0.0).
 
     Then you may try:
-    ```
+    ```bash
     yini --help
     ```
     Should show you the CLI help for YINI.
 
-### 📤 Output Modes for `yini parse`
+3. **Test functionality**  
+    Create a simple test file, for example: `config.yini`:
+    ```yini
+    ^ App
+    name = "My App Title"
+    version = "1.2.3"
+    pageSize = 25
+    darkTheme = off
+    ```
+
+    Then run:
+    ```bash
+    yini parse config.yini
+    ```
+
+    Expected result, your CLI should output a parsed version of the config and output something similar to:
+    ```js
+    {
+        App: {
+            name: 'My App Title',
+            version: '1.2.3',
+            pageSize: 25,
+            darkTheme: false
+        }
+    }    
+    ```
+
+---
+
+## 📤 Output Modes for `yini parse`
 
 The `parse` command supports multiple output styles:
 
@@ -59,7 +96,6 @@ The `parse` command supports multiple output styles:
 |----------------------------------------------------|----------------------|------------------------------------------------------------------------------|
 | `yini parse config.yini`                           | JS-style object       | Uses Node’s `util.inspect` — human-readable, shows types, nesting, etc.     |
 | `yini parse config.yini --pretty`                  | Pretty JSON           | Formatted and indented with `JSON.stringify(obj, null, 4)`.                  |
-| `yini parse config.yini --log`                     | Console log           | Uses `console.log` — quick output but may truncate deep structures.          |
 | `yini parse config.yini --json`                    | Compact JSON          | Compact and machine-friendly `JSON.stringify(obj)`.                          |
 | `yini parse config.yini --output out.txt`          | File (JS-style)       | Default style, written to specified file.                                    |
 | `yini parse config.yini --pretty --output out.json`| File (Pretty JSON)    | Formatted JSON written to file.                                              |
@@ -69,13 +105,26 @@ The `parse` command supports multiple output styles:
 ---
 
 ## Links
-- ➡️ [Why YINI? Why another format!?](https://github.com/YINI-lang/YINI-spec/blob/develop/RATIONALE.md) (rationale)
-- ➡️ [Intro to YINI Config Format](https://github.com/YINI-lang/yini-parser-typescript?tab=readme-ov-file#intro-to-yini-config-format) (learn YINI)
-- ➡️ [Read the YINI Specification](https://github.com/YINI-lang/YINI-spec/blob/develop/YINI-Specification.md#table-of-contents) (spec)
-- ➡️ [Official YINI Parser on npm](https://www.npmjs.com/package/yini-parser) (npm)
-- ➡️ [YINI Parser GitHub Repo](https://github.com/YINI-lang/yini-parser-typescript) (GitHub)
-- ➡️ [YINI vs Other Formats](https://github.com/YINI-lang/YINI-spec/blob/develop/Docs/Examples%20of%20YINI%20vs%20Other%20Formats.md)
-- ➡️ [YINI Project](https://github.com/YINI-lang) (home)
+- ➡️ [Getting Started: Intro to YINI Config Format](https://github.com/YINI-lang/YINI-spec/blob/develop/Docs/Intro-to-YINI-Config-Format.md)  
+  *Beginner-friendly walkthrough and basic usage examples.*
+
+- ➡️ [YINI Parser on npm](https://www.npmjs.com/package/yini-parser)  
+  *Install and view package details.*
+
+- ➡️ [Read the YINI Specification](https://github.com/YINI-lang/YINI-spec/blob/release/YINI-Specification.md#table-of-contents)  
+  *Full formal spec for the YINI format, including syntax and features.*
+
+- ➡️ [YINI Parser on GitHub](https://github.com/YINI-lang/yini-parser-typescript)  
+  *TypeScript source code, issue tracker, and contributing guide.*
+
+- ➡️ [YINI vs Other Formats](https://github.com/YINI-lang/YINI-spec/tree/release#-summary-difference-with-other-formats)  
+  *How does YINI differ: comparison with INI, YAML, and JSON.*
+  
+- ➡️ [Why YINI? (Project Rationale)](https://github.com/YINI-lang/YINI-spec/blob/release/RATIONALE.md)  
+  *Learn about the motivations and design decisions behind YINI.*
+
+- ➡️ [YINI Project](https://github.com/YINI-lang)  
+  *YINI home.*
 
 ---
 

package/dist/commands/info.js

@@ -1,8 +1,6 @@
-// import pkg from '../../package.json'
 import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
 const pkg = require('../../package.json');
-// import pkg from '../../package.json' assert { type: 'json' }
 export const printInfo = () => {
     console.log(`** YINI CLI **`);
     console.log(`yini-cli:    ${pkg.version}`);

package/dist/commands/parse.js

@@ -2,14 +2,14 @@ import fs from 'node:fs';
 import path from 'node:path';
 import util from 'util';
 import YINI from 'yini-parser';
-import { printObject, toPrettyJSON } from '../utils/print.js';
+import { debugPrint, printObject, toPrettyJSON } from '../utils/print.js';
 export const parseFile = (file, options) => {
     const outputFile = options.output || '';
     const isStrictMode = !!options.strict;
     let outputStyle = 'JS-style';
-    console.log('file = ' + file);
-    console.log('output = ' + options.output);
-    console.log('options:');
+    debugPrint('file = ' + file);
+    debugPrint('output = ' + options.output);
+    debugPrint('options:');
     printObject(options);
     if (options.pretty) {
         outputStyle = 'Pretty-JSON';
@@ -29,42 +29,43 @@ const doParseFile = (file, outputStyle, isStrictMode = false, outputFile = '') =
     // let strictMode = !!options.strict
     let bailSensitivity = 'auto';
     let includeMetaData = false;
-    console.log('File = ' + file);
-    console.log('outputStyle = ' + outputStyle);
-    // try {
-    // const raw = fs.readFileSync(file, 'utf-8')
-    // const parsed = YINI.parseFile(
-    //const parsed = YINI.parseFile(file)
-    const parsed = YINI.parseFile(file, isStrictMode, bailSensitivity, includeMetaData);
-    // const parsed = YINI.parse(raw)
-    // const output = options.pretty
-    //     ? // ? JSON.stringify(parsed, null, 2)
-    //       toPrettyJSON(parsed)
-    //     : JSON.stringify(parsed)
-    let output = '';
-    switch (outputStyle) {
-        case 'Pretty-JSON':
-            output = toPrettyJSON(parsed);
-            break;
-        case 'Console.log':
-            output = '<todo>';
-            break;
-        case 'JSON-compact':
-            output = JSON.stringify(parsed);
-            break;
-        default:
-            output = util.inspect(parsed, { depth: null, colors: false });
+    debugPrint('File = ' + file);
+    debugPrint('outputStyle = ' + outputStyle);
+    try {
+        // const raw = fs.readFileSync(file, 'utf-8')
+        // const parsed = YINI.parseFile(
+        //const parsed = YINI.parseFile(file)
+        const parsed = YINI.parseFile(file, isStrictMode, bailSensitivity, includeMetaData);
+        // const parsed = YINI.parse(raw)
+        // const output = options.pretty
+        //     ? // ? JSON.stringify(parsed, null, 2)
+        //       toPrettyJSON(parsed)
+        //     : JSON.stringify(parsed)
+        let output = '';
+        switch (outputStyle) {
+            case 'Pretty-JSON':
+                output = toPrettyJSON(parsed);
+                break;
+            case 'Console.log':
+                output = '<todo>';
+                break;
+            case 'JSON-compact':
+                output = JSON.stringify(parsed);
+                break;
+            default:
+                output = util.inspect(parsed, { depth: null, colors: false });
+        }
+        if (outputFile) {
+            // Write JSON output to file instead of stdout.
+            fs.writeFileSync(path.resolve(outputFile), output, 'utf-8');
+            console.log(`Output written to file: "${outputFile}"`);
+        }
+        else {
+            console.log(output);
+        }
     }
-    if (outputFile) {
-        // Write JSON output to file instead of stdout.
-        fs.writeFileSync(path.resolve(outputFile), output, 'utf-8');
-        console.log(`Output written to ${outputFile}`);
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
     }
-    else {
-        console.log(output);
-    }
-    // } catch (err: any) {
-    //     console.error(`Error: ${err.message}`)
-    //     process.exit(1)
-    // }
 };

package/dist/commands/validate.js

@@ -8,7 +8,7 @@ export const validateFile = (file, options = {}) => {
         const isMeta = true;
         const parsed = YINI.parse(content, options.strict ?? false, 'auto', isMeta);
         if (!options.silent) {
-            console.log(`✔ File is valid${options.strict ? ' (strict mode)' : ''}.`);
+            console.log(`✔  File is valid${options.strict ? ' (strict mode)' : ''}.`);
             if (options.details) {
                 //@todo format parsed.meta to details as
                 /*

package/dist/descriptions.d.ts

@@ -1,6 +1,6 @@
 export declare const descriptions: {
     yini: string;
-    'For-command-info': string;
     'For-command-parse': string;
     'For-command-validate': string;
+    'For-command-info': string;
 };

package/dist/descriptions.js

@@ -1,6 +1,6 @@
 export const descriptions = {
-    yini: 'CLI for parsing and validating YINI config files',
-    'For-command-info': 'Show extended information (details, links, etc.)',
-    'For-command-parse': 'Parse a YINI file and print the result',
-    'For-command-validate': 'Checks if the file can be parsed as valid YINI',
+    yini: 'CLI for parsing and validating YINI config files.',
+    'For-command-parse': 'Parse a YINI file (*.yini) and print the result.',
+    'For-command-validate': 'Checks if the file can be parsed as valid YINI.',
+    'For-command-info': 'Show extended information (details, links, etc.).',
 };

package/dist/index.js

@@ -6,8 +6,8 @@ import { Command } from 'commander';
 import { printInfo } from './commands/info.js';
 import { parseFile } from './commands/parse.js';
 import { validateFile } from './commands/validate.js';
-import { isDebug } from './config/env.js';
-import { descriptions as descripts } from './descriptions.js';
+import { isDebug, isDev } from './config/env.js';
+import { descriptions as descr } from './descriptions.js';
 import { debugPrint, toPrettyJSON } from './utils/print.js';
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
@@ -54,37 +54,48 @@ Current suggestion:
 
 */
 // Display help for command
-program.name('yini').description(descripts.yini).version(pkg.version);
+program
+    .name('yini')
+    .description(descr.yini)
+    // Below will replace all auto-registered items (especially the descriptions starting with a capital and ending with a period).
+    .version(pkg.version, '-v, --version', 'Output the version number.')
+    .helpOption('-h, --help', 'Display help for command.')
+    .helpCommand('help [command]', 'Display help for command.');
 program.addHelpText('before', `YINI CLI (Yet another INI)
 
 For parsing and validating YINI configuration files.
-A human-friendly config format - like INI, but with type-safe values,
-nested sections, comments, minimal syntax noise, and optional strict mode.
+A config format, inspired by INI, with type-safe values, nested
+sections, comments, minimal syntax noise, and optional strict mode.
 
-Crafted for clarity, consistency, and the simple joy of it. :)`);
+Designed for clarity and consistency. :)\n`);
 program.addHelpText('after', `
 Examples:
   $ yini parse config.yini
   $ yini validate config.yini --strict
   $ yini parse config.yini --pretty --output out.json
 
-More info: https://github.com/YINI-lang/yini-parser
-`);
+Example of "config.yini":
+    ^ App
+    title = 'My App'
+    items = 10
+    debug = ON
+
+    ^ Server
+    host = 'localhost'
+    port = 8080
+    useTLS = OFF
+
+        // Sub-section of Server.
+        ^^ Login
+        username = 'user'
+        password = 'secret'
+
+More info:
+https://github.com/YINI-lang/yini-cli
+
+Into to YINI Config:
+https://github.com/YINI-lang/YINI-spec/blob/develop/Docs/Intro-to-YINI-Config-Format.md`);
 //program.command('help [command]').description('Display help for command')
-// Command info
-program
-    .command('info')
-    // .command('')
-    .description(descripts['For-command-info'])
-    // .option('info')
-    .action((options) => {
-    debugPrint('Run command "info"');
-    if (isDebug()) {
-        console.log('options:');
-        console.log(toPrettyJSON(options));
-    }
-    printInfo();
-});
 /**
  *
  * Maybe later, to as default command: parse <parse>
@@ -106,14 +117,16 @@ program
 // Explicit "parse" command
 program
     .command('parse <file>')
-    .description(descripts['For-command-parse'])
-    .option('--strict', 'Parse YINI in strict-mode')
-    .option('--pretty', 'Pretty-print output as JSON')
+    .description(descr['For-command-parse'])
+    .option('--strict', 'Parse YINI in strict-mode.')
+    .option('--pretty', 'Pretty-print output as JSON.')
     // .option('--log', 'Use console.log output format (compact, quick view)')
-    .option('--json', 'Compact JSON output using JSON.stringify')
-    .option('--output <file>', 'Write output to a specified file')
+    .option('--json', 'Compact JSON output using JSON.stringify.')
+    .option('--output <file>', 'Write output to a specified file.')
     .action((file, options) => {
     debugPrint('Run command "parse"');
+    debugPrint('isDebug(): ' + isDebug());
+    debugPrint('isDev()  : ' + isDev());
     debugPrint(`<file> = ${file}`);
     if (isDebug()) {
         console.log('options:');
@@ -144,9 +157,9 @@ program
  */
 program
     .command('validate <file>')
-    .description(descripts['For-command-validate'])
+    .description(descr['For-command-validate'])
     .option('--strict', 'Enable parsing in strict-mode')
-    .option('--details', 'Print detailed meta-data info (e.g., key count, nesting, etc.)')
+    .option('--details', 'Print detailed meta-data info (e.g., key count, nesting, etc.).')
     .option('--silent', 'Suppress output')
     .action((file, options) => {
     //@todo add debugPrint
@@ -157,6 +170,20 @@ program
         program.help();
     }
 });
+// Command info
+program
+    .command('info')
+    // .command('')
+    .description(descr['For-command-info'])
+    // .option('info')
+    .action((options) => {
+    debugPrint('Run command "info"');
+    if (isDebug()) {
+        console.log('options:');
+        console.log(toPrettyJSON(options));
+    }
+    printInfo();
+});
 // NOTE: Converting YINI files to other formats than json and js.
 // Other format should go into a new CLI-command called 'yini-convert'.
 program.parseAsync();

package/dist/utils/print.d.ts

@@ -2,7 +2,8 @@ export declare const debugPrint: (str?: any) => void;
 export declare const devPrint: (str?: any) => void;
 export declare const toJSON: (obj: any) => string;
 export declare const toPrettyJSON: (obj: any) => string;
-/** Pretty-prints a JavaScript object as formatted JSON to the console.
+/**
+ * Pretty-prints a JavaScript object as formatted JSON to the console.
  * Strict JSON, all keys are enclosed in ", etc.
  */
 export declare const printJSON: (obj: any) => void;

package/dist/utils/print.js

@@ -4,14 +4,11 @@
  */
 import util from 'util';
 import { isDebug, isDev, isProdEnv, isTestEnv } from '../config/env.js';
-// import { isDebug, isDev, isProdEnv, isTestEnv } from '../config/env'
 export const debugPrint = (str = '') => {
     isDebug() && console.debug('DEBUG: ' + str);
-    console.debug('DEBUG: ' + str);
 };
 export const devPrint = (str = '') => {
     isDev() && !isTestEnv() && console.log('DEV: ' + str);
-    console.log('DEV: ' + str);
 };
 export const toJSON = (obj) => {
     const str = JSON.stringify(obj);
@@ -21,7 +18,8 @@ export const toPrettyJSON = (obj) => {
     const str = JSON.stringify(obj, null, 4);
     return str;
 };
-/** Pretty-prints a JavaScript object as formatted JSON to the console.
+/**
+ * Pretty-prints a JavaScript object as formatted JSON to the console.
  * Strict JSON, all keys are enclosed in ", etc.
  */
 export const printJSON = (obj) => {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "yini-cli",
-    "version": "1.0.0-alpha.3",
+    "version": "1.0.1-beta.1",
     "description": "CLI for parsing and validating YINI config files: type-safe values, nested sections, comments, minimal syntax noise, and optional strict mode.",
     "keywords": [
         "yini",
@@ -67,7 +67,7 @@
     },
     "author": "Marko K. Seppänen",
     "dependencies": {
-        "commander": "^11.0.0",
+        "commander": "^14.0.0",
         "yini-parser": "^1.0.1-beta"
     },
     "devDependencies": {

package/sample.yini

@@ -1,10 +1,10 @@
-@YINI
+@yini
 
 /*
     Example of a YINI document.
 */
 
-^ Service               // Defines a section named Server.
+^ Service               // Defines a section named Service.
 Enabled = true
 
     ^^ Cache