Technical API Reference

1. What lipimala does

Converts between scholarly Latin (IAST / extended Indic / ISO-style tables), Devanagari, Gujarati, and plain-English / Hunterian views. Visible Brahmic rendering is many-to-one—case, aliases, and normalization collapse—so exact recovery uses an envelope or an invisible metadata trailer.

2. Installation & imports

3. Core concepts

3.1 Two API layers

3.2 Smart vs exact vs canonical reverse

Same pattern for Gujarati→IAST and Deva↔Gujr with typed markers ISC:D: / ISC:G:.

3.3 Unicode normalization

Enum UnicodeNormalizationForm: preserve nfc nfd

Envelope defaults: input nfd, output nfc. Reverse APIs use ScriptToIastOptions.

4. Cross-language naming map

The table below maps all primary public functions, envelope APIs, reverse converters, script-to-script transformers, and metadata helpers across Dart, JavaScript, Python, and PHP environments.

5. Envelope APIs

Return TransliterationResult. Always set renderingIsInjective = false for script/plain views.

Minimal multi-language example

import 'package:lipimala/lipimala.dart';

final r = 'Kṛṣṇa ā́tman'.toDevanagari();
print(r.rendered);          // कृष्ण आ॑त्मन्
print(r.restoreOriginal()); // Kṛṣṇa ā́tman

import { toDevanagari } from 'lipimala';

const r = toDevanagari('Kṛṣṇa ā́tman');
console.log(r.rendered);
console.log(r.restoreOriginal());

from lipimala import to_devanagari

r = to_devanagari('Kṛṣṇa ā́tman')
print(r.rendered)
print(r.restore_original())

use function Lipimala\toDevanagari;

$r = toDevanagari('Kṛṣṇa ā́tman');
echo $r->rendered, PHP_EOL;
echo $r->restoreOriginal(), PHP_EOL;

6. IAST → Devanagari (string API)

7. IAST → Gujarati (string API)

8. IAST → plain English / Hunterian

8b. Bulk Array / List Transliteration API

// Dart List Extension
final devaList = ['Kṛṣṇa', 'Rāma', 'jñāna'].toDevanagariFromIast();
// -> ['कृष्ण', 'राम', 'ज्ञान']

// JavaScript / Node.js
import { toDevanagariFromIastList, toCanonicalGujaratiFromDevanagariList } from 'lipimala';
const deva = toDevanagariFromIastList(['Kṛṣṇa', 'Rāma', 'jñāna']);
const gujr = toCanonicalGujaratiFromDevanagariList(deva);

# Python
from lipimala import to_devanagari_from_iast_list, to_canonical_iast_from_devanagari_list
deva = to_devanagari_from_iast_list(['Kṛṣṇa', 'Rāma', 'jñāna'])
iast = to_canonical_iast_from_devanagari_list(deva)

// PHP
use function Lipimala\toDevanagariFromIastList;
$deva = toDevanagariFromIastList(['Kṛṣṇa', 'Rāma', 'jñāna']);

9. Brahmic → IAST reverse

Lipimala provides three distinct reverse conversion strategies for translating Devanagari or Gujarati text back into Latin IAST. Choose between smart metadata-aware recovery, pure canonical visible reverse, or strict metadata verification.

ScriptToIastOptions

Options object controlling reverse transliteration behavior. Parameter fields, default values, and effects are detailed in §15 Reverse options.

10. Direct Devanagari ↔ Gujarati

Direct script conversion maps characters natively between Devanagari and Gujarati. Because the two scripts have unequal Unicode repertoires, Lipimala supports direct-script metadata trailers (using markers DEV1 and GUJ1) for 100% exact round-trip source script recovery.

11. Metadata & Unicode helpers

Low-level functions for manually manipulating embedded Unicode tag trailers, decoding checksummed metadata payloads, and performing Unicode 17.0.0 normalization and mark classification.

12. Result structures

TransliterationResult

JSON envelope shape

{
  "schema": "indic-script-converter/1" | "exact round-trip-indic-transliteration/1",
  "original": "Kṛṣṇa",
  "originalCodePoints": [75, 7771, 7779, 7751, 97],
  "normalizedInput": "...",
  "rendered": "कृष्ण",
  "profile": "extendedIndic",
  "inputNormalization": "nfd",
  "outputNormalization": "nfc",
  "renderingIsInjective": false,
  "issues": [
    { "code": "...", "message": "...", "severity": "info", "sourceRuneOffset": null }
  ]
}

TransliterationIssue

EmbeddedExactSource

Fields: visibleText, originalSource.

13. Forward options (IAST → Deva / Gujr)

IastToDevanagariOptions / IastToGujaratiOptions

Gujarati types mirror the same fields with Gujarati-prefixed enum type names.

14. Plain-English options

IastPlainEnglishOptions

15. Reverse options

ScriptToIastOptions

Options class controlling Brahmic → IAST reverse transliteration (Devanagari → IAST and Gujarati → IAST).

16. Direct-script options

IndicScriptConversionOptions

17. Dart-specific notes

The Dart implementation (package:lipimala) targets Dart 3.0+ and Flutter. It exposes both functional APIs and natural extensions on String.

• Primary Barrel Import: import 'package:lipimala/lipimala.dart'; (exports all converters, options, enums, and result models).
• String Extension APIs: Call 'Kṛṣṇa'.toDevanagari(), 'Kṛṣṇa'.toGujarati(), 'Kṛṣṇa'.toPlainEnglish() directly on String instances.
• String Subclass Returns: Forward string converters return IastToDevanagariString, IastToGujaratiString, and IastToPlainEnglish subclasses which provide .toExactIast() and .restoreOriginal() helper methods.
• Option Constructors: Options use named parameters with defaults: IastToDevanagariOptions(profile: DevanagariRomanizationProfile.extendedIndic, embedExactSourceMetadata: true).
• Error Handling: Throws ArgumentError on invalid options or corrupted metadata trailers.

Complete Runnable Dart Example

import 'package:lipimala/lipimala.dart';

void main() {
  const input = 'Kṛṣṇa / Kr̥ṣṇa / ḫāna';

  // 1. Extension method envelope conversion
  final result = input.toDevanagari(
    options: const IastToDevanagariOptions(embedExactSourceMetadata: true),
  );
  print('Rendered: ${result.rendered}');
  print('Restored: ${result.restoreOriginal()}');

  // 2. Direct script conversion
  final gujarati = toGujaratiFromDevanagari(
    result.rendered,
    options: const IndicScriptConversionOptions(embedExactSourceMetadata: true),
  );
  print('Gujarati: $gujarati');

  // 3. Exact recovery from Gujarati
  final exactDeva = toExactDevanagariFromGujarati(gujarati);
  assert(exactDeva == result.rendered);
}

18. JavaScript-specific notes

The JavaScript implementation supports Node.js ≥ 20 and modern browsers via ES Modules (ESM) and CommonJS (CJS).

• Module Imports: ESM: import { toDevanagari, toDevanagariFromIast } from 'lipimala';
  CommonJS: const { toDevanagari, toDevanagariFromIast } = require('lipimala');
• Dual Export Naming: Exports both camelCase (toDevanagariFromIast) and snake_case (to_devanagari_from_iast) aliases for all functions.
• Flexible Options: Option parameters accept instantiated class objects (new IastToDevanagariOptions({...})) or plain JS objects ({ embedExactSourceMetadata: true }). Both camelCase and snake_case keys are supported.
• String Subclasses: String converters return instances of IastToDevanagariString, IastToGujaratiString, or IastToPlainEnglish extending native String, offering .toExactIast().
• Error Handling: Throws standard TypeError or Error on bad arguments or metadata decoding failures.

Complete Runnable JavaScript Example

import {
  toDevanagari,
  toGujaratiFromDevanagari,
  toExactDevanagariFromGujarati,
  IastToDevanagariOptions
} from 'lipimala';

const input = 'Kṛṣṇa / Kr̥ṣṇa / ḫāna';

// 1. Envelope conversion
const result = toDevanagari(input, { embedExactSourceMetadata: true });
console.log('Rendered:', result.rendered);
console.log('Restored:', result.restoreOriginal());

// 2. Direct script conversion Devanagari -> Gujarati
const guj = toGujaratiFromDevanagari(result.rendered, { embedExactSourceMetadata: true });
console.log('Gujarati:', guj);

// 3. Exact source recovery
const exactDeva = toExactDevanagariFromGujarati(guj);
console.assert(exactDeva === result.rendered);

19. Python-specific notes

The Python package (pip install lipimala) requires Python ≥ 3.12, utilizing modern type hints and dataclasses.

• Imports: Main & direct script converters: from lipimala import to_devanagari, to_devanagari_from_iast, to_devanagari_from_gujarati
• Function & Enum Aliases: Supports standard Python PEP 8 snake_case functions and camelCase aliases for cross-language parity. Enums inherit (str, Enum) and support both EXTENDED_INDIC and extendedIndic member access.
• Dataclass Options: Options are Python @dataclass objects instantiated with keyword arguments: IastToDevanagariOptions(embed_exact_source_metadata=True).
• String Subclass Returns: Returns IastToDevanagariString, IastToGujaratiString, IastToPlainEnglish subclasses of str with .to_exact_iast() / .restore_original().
• Error Handling: Raises ValueError on invalid option configurations or corrupted metadata.

Complete Runnable Python Example

from lipimala import (
    to_devanagari,
    IastToDevanagariOptions,
    to_gujarati_from_devanagari,
    to_exact_devanagari_from_gujarati,
    IndicScriptConversionOptions
)

input_text = "Kṛṣṇa / Kr̥ṣṇa / ḫāna"

# 1. Envelope conversion
result = to_devanagari(input_text, options=IastToDevanagariOptions(embed_exact_source_metadata=True))
print("Rendered:", result.rendered)
print("Restored:", result.restore_original())

# 2. Direct script conversion
gujarati = to_gujarati_from_devanagari(
    result.rendered,
    options=IndicScriptConversionOptions(embed_exact_source_metadata=True)
)
print("Gujarati:", gujarati)

# 3. Exact recovery
exact_deva = to_exact_devanagari_from_gujarati(gujarati)
assert exact_deva == result.rendered

20. PHP-specific notes

The PHP port (composer require jayeshmepani/lipimala) requires PHP ≥ 8.3 with strict typing throughout.

• Namespace & Autoload: Namespace Lipimala. Import functions with use function Lipimala\toDevanagariFromIast;.
• Dual Function Aliases: Supports both toDevanagariFromIast() and to_devanagari_from_iast() namespaced functions.
• Final Readonly Options: Options are final readonly class instances with promoted constructor properties and default values. Options parameters are nullable (pass null for defaults).
• Zero Runtime Dependencies: Pure PHP code with bundled Unicode 17.0.0 data tables; does not require mbstring or intl extensions.
• Error Handling: Throws InvalidArgumentException on invalid parameters or failed metadata verification.

Complete Runnable PHP Example

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use IndicScriptConverter\IastToDevanagariOptions;
use IndicScriptConverter\IndicScriptConversionOptions;
use function IndicScriptConverter\toDevanagari;
use function IndicScriptConverter\toGujaratiFromDevanagari;
use function IndicScriptConverter\toExactDevanagariFromGujarati;

$input = 'Kṛṣṇa / Kr̥ṣṇa / ḫāna';

// 1. Envelope conversion
$result = toDevanagari($input, new IastToDevanagariOptions(embedExactSourceMetadata: true));
echo "Rendered: {$result->rendered}
";
echo "Restored: " . $result->restoreOriginal() . "
";

// 2. Direct script conversion
$gujarati = toGujaratiFromDevanagari(
    $result->rendered,
    new IndicScriptConversionOptions(embedExactSourceMetadata: true)
);
echo "Gujarati: {$gujarati}
";

// 3. Exact recovery
$exactDeva = toExactDevanagariFromGujarati($gujarati);
assert($exactDeva === $result->rendered);

21. Example files

Each runtime has a comprehensive example that exercises public APIs with option permutations.

22. Errors & recovery matrix