greek-name-correction 2.1.2 → 2.2.0

package/README.md

@@ -22,7 +22,8 @@ A powerful, zero-dependency Node.js library for correcting, formatting, and vali
 💾 **Database-Safe** - SQL-ready output  
 🔤 **Sort Keys** - Accent-free sorting support  
 ✅ **Validation** - Greek name pattern validation  
-🔧 **Flexible I/O** - Supports strings, arrays, and objects
+🔧 **Flexible I/O** - Supports strings, arrays, and objects  
+✨ **Accent Addition** - Automatically adds accents to unaccented Greek names (one accent per word)
 
 ## Installation
 ```bash
@@ -55,6 +56,94 @@ console.log(result);
 // }
 ```
 
+## Command-Line Interface (CLI)
+
+The library includes a CLI tool for use from the command line.
+
+### Installation
+
+To use the CLI globally:
+```bash
+npm install -g greek-name-correction
+```
+
+Or use it directly with `npx`:
+```bash
+npx greek-name-correction -name "NAME" [OPTIONS]
+```
+
+### Usage
+
+```bash
+# Basic usage
+greek-name-correction -name "γιώργος παπαδόπουλος"
+# → "Γιώργος Παπαδόπουλος"
+
+# Positional argument (name without -name flag)
+greek-name-correction "Ραυτόπουλος Σταύρος" -convertToCase vocative
+# → "Ραυτόπουλε Σταύρο"
+
+# With options
+greek-name-correction -name "Γιώργος Παπαδόπουλος" -convertToCase vocative
+# → "Γιώργο Παπαδόπουλο"
+
+# JSON output with preserveOriginal
+greek-name-correction -name "Μαρία Κωνσταντίνου" -detectGender -addGeneralTitle -preserveOriginal -json
+# → JSON object with all details
+```
+
+### Available Options
+
+| Option | Description |
+|--------|-------------|
+| `-name, --name <name>` | Name to correct (required if not provided as positional argument) |
+| `-convertToCase <case>` | Convert to case: `vocative` or `accusative` |
+| `-transliterate <type>` | Transliteration: `greeklish-to-greek`, `greek-to-latin`, `greek-to-greeklish` |
+| `-convertToGenitive` | Convert to genitive case |
+| `-preserveOriginal` | Return object with original and corrected name |
+| `-detectGender` | Detect gender from name |
+| `-detectDiminutive` | Detect diminutive forms |
+| `-suggestCorrections` | Suggest corrections for common misspellings |
+| `-recognizeKatharevousa` | Recognize and convert Katharevousa forms |
+| `-databaseSafe` | Make output database-safe |
+| `-generateSortKey` | Generate sort key (accent-free) |
+| `-statistics` | Generate name statistics |
+| `-addGeneralTitle` | Add general title (κ./κα) based on gender |
+| `-addAccents` | Add accents to firstname and lastname (one accent per word) |
+| `-handleTitles` | Handle titles (default: true) |
+| `-handleParticles` | Handle Greek particles (default: true) |
+| `-strictMode` | Enable strict mode |
+| `-json` | Output result as JSON |
+| `-help, -h` | Show help message |
+| `-version, -v` | Show version |
+
+### Examples
+
+```bash
+# Vocative case conversion
+greek-name-correction -name "Γιώργος Παπαδόπουλος" -convertToCase vocative
+
+# Accusative case conversion
+greek-name-correction -name "Δημήτρης Νικολάου" -convertToCase accusative
+
+# Transliteration
+greek-name-correction -name "giorgos papadopoulos" -transliterate greeklish-to-greek
+
+# Multiple options with JSON output
+greek-name-correction -name "Μαρία Κωνσταντίνου" -detectGender -addGeneralTitle -preserveOriginal -json
+
+# Add accents to unaccented names
+greek-name-correction -name "γιωργος παπαδοπουλος" -addAccents
+# → "Γιώργος Παπαδόπουλος"
+
+# Get help
+greek-name-correction -help
+```
+
+**Note for Windows/PowerShell users:** If you encounter issues with Greek characters in quotes, try:
+- Using single quotes: `greek-name-correction -name 'Γιώργος Παπαδόπουλος'`
+- Or use a file input: `echo "Γιώργος Παπαδόπουλος" | greek-name-correction`
+
 ## Usage Examples
 
 ### Basic String Correction
@@ -222,6 +311,43 @@ GreekNameCorrection('Ελένη Γεωργίου', {
 //   }
 ```
 
+### Accent Addition
+```javascript
+// Add accents to unaccented Greek names (one accent per word)
+GreekNameCorrection('γιωργος παπαδοπουλος', {
+  addAccents: true
+});
+// → "Γιώργος Παπαδόπουλος"
+
+GreekNameCorrection('μαρια κωνσταντινου', {
+  addAccents: true
+});
+// → "Μαρία Κωνσταντίνου"
+
+// Words that already have accents are preserved
+GreekNameCorrection('Γιώργος Παπαδόπουλος', {
+  addAccents: true
+});
+// → "Γιώργος Παπαδόπουλος" (unchanged)
+
+// Works with preserveOriginal option
+GreekNameCorrection('νικος αλεξιου', {
+  addAccents: true,
+  preserveOriginal: true
+});
+// → {
+//     corrected: "Νίκος Αλεξίου",
+//     original: "νικος αλεξιου",
+//     isValid: true
+//   }
+
+// Each word gets exactly one accent
+GreekNameCorrection('δημήτρης νικολάου', {
+  addAccents: true
+});
+// → "Δημήτρης Νικολάου"
+```
+
 ### Name Corrections
 ```javascript
 GreekNameCorrection('γιοργος παπαδοπουλος', {
@@ -347,6 +473,7 @@ GreekNameCorrection(input, options)
 | `detectDiminutive` | `boolean` | `false` | Detect diminutive/nickname forms |
 | `handleTitles` | `boolean` | `true` | Extract and format titles |
 | `addGeneralTitle` | `boolean` | `false` | Automatically add general title (κ. for men, κα for women) if no title exists (always lowercase) |
+| `addAccents` | `boolean` | `false` | Add accents to firstname and lastname (one accent per word) |
 | `suggestCorrections` | `boolean` | `false` | Suggest corrections for misspellings |
 | `recognizeKatharevousa` | `boolean` | `false` | Convert archaic Greek forms |
 | `databaseSafe` | `boolean` | `false` | Remove problematic characters |
@@ -444,6 +571,7 @@ const result = GreekNameCorrection('dr giorgos tou papa', {
   preserveOriginal: true,
   handleTitles: true,
   addGeneralTitle: true,
+  addAccents: true,
   handleParticles: true,
   suggestCorrections: true,
   detectGender: true,
@@ -585,19 +713,61 @@ While designed for Node.js, the library can be bundled for browser use with tool
 
 ## TypeScript
 
-TypeScript definitions can be added. Example:
+Full TypeScript support is included! The library comes with comprehensive type definitions for all features.
+
+### Installation
+
+TypeScript definitions are automatically included when you install the package:
+
+```bash
+npm install greek-name-correction
+```
+
+### Usage
+
 ```typescript
-declare function GreekNameCorrection(
-  input: string | string[] | object | object[],
-  options?: {
-    jsonKey?: string;
-    outputKey?: string;
-    preserveOriginal?: boolean;
-    // ... other options
-  }
-): string | string[] | object | object[];
+import GreekNameCorrection = require('greek-name-correction');
+// or
+import GreekNameCorrection from 'greek-name-correction';
+
+// TypeScript will provide full type checking and IntelliSense
+const result = GreekNameCorrection('γιάννης παπαδόπουλος', {
+  preserveOriginal: true,
+  detectGender: true,
+  convertToGenitive: true
+});
+
+// result is typed as GreekNameCorrectionResult
+console.log(result.corrected); // string
+console.log(result.gender);     // 'male' | 'female' | 'unknown' | undefined
+console.log(result.genitive);   // string | undefined
 ```
 
+### Type Definitions
+
+All types are exported for use in your TypeScript projects:
+
+```typescript
+import {
+  GreekNameCorrectionOptions,
+  GreekNameCorrectionResult,
+  Gender,
+  NameParts,
+  DiminutiveInfo,
+  NameStatistics,
+  TransliterationMode,
+  CaseConversion
+} from 'greek-name-correction';
+```
+
+### Features
+
+- ✅ **Full type safety** - All function signatures are typed
+- ✅ **IntelliSense support** - Autocomplete for all options
+- ✅ **Type inference** - Return types are automatically inferred
+- ✅ **Overloads** - Separate overloads for string, array, and object inputs
+- ✅ **JSDoc comments** - Inline documentation in your IDE
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
@@ -627,6 +797,7 @@ The test suite covers:
 - Case conversions (genitive, vocative, accusative)
 - Title handling
 - Automatic general title addition
+- Accent addition
 - Diminutive detection
 - Gender detection
 - Statistics generation
@@ -634,7 +805,11 @@ The test suite covers:
 
 ## Changelog
 
-### Version 2.1.2 (Current)
+### Version 2.2.0 (Current)
+- ✨ **Accent Addition Feature** - Added `addAccents` option to automatically add accents to unaccented Greek names (one accent per word). Intelligently places accents based on Greek accentuation rules and word endings.
+- ✨ **TypeScript Support** - Added comprehensive TypeScript definitions (`index.d.ts`) with full type safety, IntelliSense support, and exported types
+
+### Version 2.1.2
 - 🐛 **Bug Fix** - Fixed `splitNameParts` to correctly filter out general titles (κ. and κα) from name parts
 
 ### Version 2.1.1

package/bin/greek-name-correction.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// bin/greek-name-correction.js - CLI for GreekNameCorrection
+"use strict";
+
+const GreekNameCorrection = require("../src/index");
+
+/**
+ * Parse command-line arguments
+ */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const options = {};
+  let name = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const nextArg = args[i + 1];
+
+    // Parse -name or --name
+    if ((arg === "-name" || arg === "--name") && nextArg) {
+      name = nextArg;
+      i++; // Skip next argument
+    }
+    // Parse -convertToCase or --convertToCase
+    else if ((arg === "-convertToCase" || arg === "--convertToCase") && nextArg) {
+      options.convertToCase = nextArg.toLowerCase();
+      i++;
+    }
+    // Parse -transliterate or --transliterate
+    else if ((arg === "-transliterate" || arg === "--transliterate") && nextArg) {
+      options.transliterate = nextArg.toLowerCase();
+      i++;
+    }
+    // Parse boolean flags
+    else if (arg === "-preserveOriginal" || arg === "--preserveOriginal") {
+      options.preserveOriginal = true;
+    }
+    else if (arg === "-convertToGenitive" || arg === "--convertToGenitive") {
+      options.convertToGenitive = true;
+    }
+    else if (arg === "-detectGender" || arg === "--detectGender") {
+      options.detectGender = true;
+    }
+    else if (arg === "-detectDiminutive" || arg === "--detectDiminutive") {
+      options.detectDiminutive = true;
+    }
+    else if (arg === "-suggestCorrections" || arg === "--suggestCorrections") {
+      options.suggestCorrections = true;
+    }
+    else if (arg === "-recognizeKatharevousa" || arg === "--recognizeKatharevousa") {
+      options.recognizeKatharevousa = true;
+    }
+    else if (arg === "-databaseSafe" || arg === "--databaseSafe") {
+      options.databaseSafe = true;
+    }
+    else if (arg === "-generateSortKey" || arg === "--generateSortKey") {
+      options.generateSortKey = true;
+    }
+    else if (arg === "-statistics" || arg === "--statistics") {
+      options.statistics = true;
+    }
+    else if (arg === "-addGeneralTitle" || arg === "--addGeneralTitle") {
+      options.addGeneralTitle = true;
+    }
+    else if (arg === "-addAccents" || arg === "--addAccents") {
+      options.addAccents = true;
+    }
+    else if (arg === "-handleTitles" || arg === "--handleTitles") {
+      options.handleTitles = true;
+    }
+    else if (arg === "-handleParticles" || arg === "--handleParticles") {
+      options.handleParticles = true;
+    }
+    else if (arg === "-strictMode" || arg === "--strictMode") {
+      options.strictMode = true;
+    }
+    else if (arg === "-json" || arg === "--json") {
+      options.json = true;
+    }
+    else if (arg === "-help" || arg === "--help" || arg === "-h" || arg === "--h") {
+      printHelp();
+      process.exit(0);
+    }
+    else if (arg === "-version" || arg === "--version" || arg === "-v" || arg === "--v") {
+      const pkg = require("../package.json");
+      console.log(pkg.version);
+      process.exit(0);
+    }
+    // If no flag, treat as name (for convenience)
+    else if (!name && !arg.startsWith("-")) {
+      name = arg;
+    }
+  }
+
+  return { name, options };
+}
+
+/**
+ * Print help message
+ */
+function printHelp() {
+  console.log(`
+Greek Name Correction CLI
+
+Usage:
+  greek-name-correction -name "NAME" [OPTIONS]
+  greek-name-correction "NAME" [OPTIONS]
+
+Options:
+  -name, --name <name>              Name to correct (required if not provided as positional argument)
+  -convertToCase <case>             Convert to case: 'vocative' or 'accusative'
+  -transliterate <type>             Transliteration type: 'greeklish-to-greek', 'greek-to-latin', 'greek-to-greeklish'
+  -convertToGenitive                 Convert to genitive case
+  -preserveOriginal                  Return object with original and corrected name
+  -detectGender                      Detect gender from name
+  -detectDiminutive                  Detect diminutive forms
+  -suggestCorrections               Suggest corrections for common misspellings
+  -recognizeKatharevousa            Recognize and convert Katharevousa forms
+  -databaseSafe                     Make output database-safe
+  -generateSortKey                  Generate sort key (accent-free)
+  -statistics                       Generate name statistics
+  -addGeneralTitle                  Add general title (κ./κα) based on gender
+  -addAccents                       Add accents to firstname and lastname (one accent per word)
+  -handleTitles                     Handle titles (default: true)
+  -handleParticles                  Handle Greek particles (default: true)
+  -strictMode                       Enable strict mode
+  -json                             Output result as JSON
+  -help, -h                         Show this help message
+  -version, -v                      Show version
+
+Examples:
+  greek-name-correction -name "γιώργος παπαδόπουλος"
+  greek-name-correction "Ραυτόπουλος Σταύρος" -convertToCase vocative
+  greek-name-correction -name "giorgos papadopoulos" -transliterate greeklish-to-greek
+  greek-name-correction -name "Γιώργος Παπαδόπουλος" -convertToGenitive -preserveOriginal -json
+  greek-name-correction -name "Μαρία Κωνσταντίνου" -detectGender -addGeneralTitle
+  greek-name-correction -name "γιωργος παπαδοπουλος" -addAccents
+`);
+}
+
+/**
+ * Format output based on options
+ */
+function formatOutput(result, options) {
+  if (options.json || options.preserveOriginal) {
+    // If JSON output requested or preserveOriginal is true, return JSON
+    return JSON.stringify(result, null, 2);
+  }
+  
+  if (typeof result === "object" && result !== null && !Array.isArray(result)) {
+    // If it's an object result, check for case-specific fields first
+    if (options.convertToCase && result[options.convertToCase]) {
+      return result[options.convertToCase];
+    }
+    if (options.convertToGenitive && result.genitive) {
+      return result.genitive;
+    }
+    // Otherwise return corrected field
+    if (result.corrected !== undefined) {
+      return result.corrected;
+    }
+    // Fallback to JSON if object structure is unexpected
+    return JSON.stringify(result, null, 2);
+  }
+  
+  return result;
+}
+
+/**
+ * Main CLI function
+ */
+function main() {
+  const { name, options } = parseArgs();
+
+  if (!name) {
+    console.error("Error: Name is required. Use -name or provide as argument.");
+    console.error("Run with -help for usage information.");
+    process.exit(1);
+  }
+
+  try {
+    const result = GreekNameCorrection(name, options);
+    const output = formatOutput(result, options);
+    console.log(output);
+  } catch (error) {
+    console.error("Error:", error.message);
+    process.exit(1);
+  }
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+module.exports = { parseArgs, formatOutput };