Zsnout Ithkuil

https://github.com/zsakowitz/ithkuil
Admin
Zsnout Ithkuil is a utility package that provides tools for generating, parsing, and glossing New...
Tokens:11,820
Snippets:77
Trust Score:8.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Start Development Server

Source: https://github.com/zsakowitz/ithkuil/blob/main/DEVELOPING.md

Starts the development server for experimentation. Requires Node.js and NPM. Creates a `playground.ts` file for user edits and runs it.

```sh
npm start
```

--------------------------------

### serve Command Line Tool

Source: https://github.com/zsakowitz/ithkuil/blob/main/DEVELOPING.md

Utility command for bundling a file and starting a local web server to run it. Requires esbuild. Takes options and a file path.

```sh
serve [options] <file>
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/zsakowitz/ithkuil/blob/main/DEVELOPING.md

Installs all necessary project packages using NPM. Requires Node.js and NPM to be installed. Modifies the `node_modules` directory.

```sh
npm install
```

--------------------------------

### Check Git Installation

Source: https://github.com/zsakowitz/ithkuil/blob/main/DEVELOPING.md

Verifies if Git is installed on the system. Requires a terminal. Outputs version number if installed, otherwise an error.

```sh
git version
```

--------------------------------

### Check Node.js and NPM Installation

Source: https://github.com/zsakowitz/ithkuil/blob/main/DEVELOPING.md

Checks for installed versions of Node.js and NPM. Requires a terminal. Outputs version numbers if installed, otherwise an error.

```sh
node -v
npm -v
```

--------------------------------

### Convert Simple Formative to Ithkuil

Source: https://github.com/zsakowitz/ithkuil/blob/main/README.md

This TypeScript example shows how to convert a simple formative into Ithkuil using the `formativeToIthkuil` function from '@zsnout/ithkuil/generate'. It demonstrates the function's ability to infer default values for most arguments.

```typescript
import { formativeToIthkuil } from "@zsnout/ithkuil/generate"

const result = formativeToIthkuil({
  root: "kš",
  type: "UNF/C",
})

console.log(result)
// kšala
```

--------------------------------

### Enable Ithkuil JSX in TypeScript Files

Source: https://github.com/zsakowitz/ithkuil/blob/main/README.md

This example demonstrates how to enable the Ithkuil JSX runtime in individual TypeScript files by adding specific comments at the top. These comments configure the JSX pragma, runtime, and import source.

```typescript
/* @jsx react-jsx */
/* @jsxRuntime automatic */
/* @jsxImportSource @zsnout/ithkuil/script */
```

--------------------------------

### Experiment with ithkuil Functions (TypeScript)

Source: https://github.com/zsakowitz/ithkuil/blob/main/DEVELOPING.md

Example code demonstrating the usage of `parseWord` and `wordToIthkuil` functions from the ithkuil project. Uses TypeScript syntax. Designed for the `playground.ts` file.

```typescript
import { parseWord, wordToIthkuil } from "./index.js"

/**
 * This file allows for quick experimentation with this project's functions. To
 * do so, import anything you need in the statement above and play around with
 * the imports below.
 */

// Be a tribe that works together towards a common goal.
const result1 = wordToIthkuil({
  type: "UNF/K",
  shortcut: true,
  root: "l",
  ca: { configuration: "MFS", affiliation: "COA" },
  context: "RPS",
  illocutionValidation: "DIR",
})

console.log(result1)

// me (beneficial, ergative) and you (detrimental, absolutive)
const result2 = parseWord("royež")

console.log(result2)
```

--------------------------------

### Convert Formative with Multiple Options to Ithkuil

Source: https://github.com/zsakowitz/ithkuil/blob/main/README.md

This advanced TypeScript example illustrates the conversion of a formative with numerous options to Ithkuil using `formativeToIthkuil`. It highlights the function's capability to automatically infer categories and missing complex components when provided with specific parameters.

```typescript
import { formativeToIthkuil } from "@zsnout/ithkuil/generate"

const result = formativeToIthkuil({
  type: "UNF/C",

  // Type-2 concatenation
  concatenationType: 2,

  // Completive Version
  version: "CPT",

  // Stem II
  stem: 2,

  // "kš" root
  root: "kš",

  // Dynamic Function
  function: "DYN",

  // Objective Specification
  specification: "OBJ",

  // Amalgamative Context
  context: "AMG",

  slotVAffixes: [
    // Referential Affix
    {
      // 1m:BEN Referent
      referents: ["1m:BEN"],

      // Ergative Case
      case: "ERG",
    },
  ],

  ca: {
    // Multiplex/Fuzzy/Connected Configuration
    configuration: "MFC",

    // Coalescent Affiliation
    affiliation: "COA",

    // Graduative Extension
    extension: "GRA",
  },

  // Repetitive Phase
  vn: "REP",
})

console.log(result)
// hwikšöeroeržžgeiha
```

--------------------------------

### Generate SVG Script with JSX

Source: https://context7.com/zsakowitz/ithkuil/llms.txt

Demonstrates how to render Ithkuil text as SVG using the JSX runtime. It includes examples for standard rendering and handwritten styling using the textToScript utility.

```tsx
/* @jsxImportSource @zsnout/ithkuil/script */
import {
  Anchor,
  CharacterRow,
  HandleResult,
  fitViewBox,
  textToScript,
} from "@zsnout/ithkuil/script"

function displayText(text: string) {
  const svg = (
    <svg>
      <HandleResult
        ok={(value) => (
          <Anchor at="cc">
            <CharacterRow compact>{value}</CharacterRow>
          </Anchor>
        )}
        error={(reason) => <text>{reason}</text>}
      >
        {textToScript(text)}
      </HandleResult>
    </svg>
  ) as SVGSVGElement

  document.body.append(svg)
  fitViewBox(svg)
}

displayText("Wattunkí ruyün")

// With handwritten style
function displayHandwritten(text: string) {
  const result = textToScript(text, true)
  const svg = (
    <svg>
      {result.ok ? (
        <Anchor at="cc">
          <CharacterRow compact>{result.value}</CharacterRow>
        </Anchor>
      ) : (
        <text>{result.reason}</text>
      )}
    </svg>
  ) as SVGSVGElement

  document.body.append(svg)
  fitViewBox(svg)
}
```

--------------------------------

### Generate Ithkuil Script using JSX

Source: https://github.com/zsakowitz/ithkuil/blob/main/README.md

This example showcases the use of the mini JSX library for generating Ithkuil scripts, simplifying the code compared to the standard TypeScript approach. It leverages JSX syntax to define SVG elements and handle the result of text-to-script conversion.

```tsx
import {
  Anchor,
  CharacterRow,
  HandleResult,
  fitViewBox,
  textToScript,
} from "@zsnout/ithkuil/script"

function displayText(text: string) {
  const svg = (
    <svg>
      <HandleResult
        ok={(value) => (
          <Anchor at="cc">
            <CharacterRow compact>{value}</CharacterRow>
          </Anchor>
        )}
        error={(reason) => <text>{reason}</text>}
      >
        {textToScript(text)}
      </HandleResult>
    </svg>
  ) as SVGSVGElement

  document.body.append(svg)

  fitViewBox(svg)
}

displayText("Wattunkí ruyün")
```

--------------------------------

### Generate Ithkuil Script using Standard TypeScript

Source: https://github.com/zsakowitz/ithkuil/blob/main/README.md

This example demonstrates how to generate Ithkuil script using standard TypeScript without JSX. It imports necessary functions from '@zsnout/ithkuil/script' to convert text into a script representation and append it to the DOM as an SVG element.

```typescript
import {
  Anchor,
  CharacterRow,
  fitViewBox,
  textToScript,
} from "@zsnout/ithkuil/script"

function displayText(text: string) {
  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg")

  const result = textToScript(text)

  if (result.ok) {
    const row = CharacterRow({
      children: result.value,
      compact: true,
    })

    const anchored = Anchor({
      at: "cc",
      children: row,
    })

    svg.appendChild(anchored)
  } else {
    const text = document.createElementNS("http://www.w3.org/2000/svg", "text")

    text.textContent = result.reason

    svg.appendChild(text)
  }

  document.body.append(svg)

  fitViewBox(svg)
}

displayText("Wattunkí ruyün")
```

--------------------------------

### use Command Line Tool

Source: https://github.com/zsakowitz/ithkuil/blob/main/DEVELOPING.md

Utility command for bundling a file, opening an interactive Node.js window, running the file, and exporting its contents globally. Requires esbuild. Takes options and a file path.

```sh
use [options] <file>
```

--------------------------------

### bundle Command Line Tool

Source: https://github.com/zsakowitz/ithkuil/blob/main/DEVELOPING.md

Utility command for bundling files and dependencies, outputting to disk, and echoing the output location. Requires esbuild. Takes options and a file path.

```sh
bundle [options] <file>
```

--------------------------------

### minify Command Line Tool

Source: https://github.com/zsakowitz/ithkuil/blob/main/DEVELOPING.md

Utility command for bundling and minifying files, outputting to disk, and echoing the output location. Requires esbuild. Takes options and a file path.

```sh
minify [options] <file>
```

--------------------------------

### run Command Line Tool

Source: https://github.com/zsakowitz/ithkuil/blob/main/DEVELOPING.md

Utility command for running a file locally using Node.js. Requires esbuild. Takes options and a file path.

```sh
run [options] <file>
```

--------------------------------

### copy Command Line Tool

Source: https://github.com/zsakowitz/ithkuil/blob/main/DEVELOPING.md

Utility command for bundling files and copying the result to the clipboard. Requires esbuild. Takes options and a file path.

```sh
copy [options] <file>
```

--------------------------------

### esbuild Command Line Tool

Source: https://github.com/zsakowitz/ithkuil/blob/main/DEVELOPING.md

Utility command for stripping TypeScript typings, outputting to disk, and echoing the output location. Requires esbuild. Takes options and a file path.

```sh
esbuild [options] <file>
```

--------------------------------

### Parse Ithkuil Formatives with @zsnout/ithkuil

Source: https://github.com/zsakowitz/ithkuil/blob/main/README.md

Demonstrates how to use the `parseFormative` function from the @zsnout/ithkuil library to convert Ithkuil formative strings into analyzable objects. It also shows how to handle concatenated formatives by parsing them separately.

```typescript
import { parseFormative } from "@zsnout/ithkuil/parse"

const result = parseFormative("malëuţřait")

console.log(result)

// { 
//   type: "UNF/C", 
//   concatenationType: undefined, 
//   shortcut: false, 
//   stem: 1, 
//   version: "PRC", 
//   root: "m", 
//   context: "EXS", 
//   specification: "BSC", 
//   function: "STA", 
//   slotVAffixes: [], 
//   ca: {}, 
//   slotVIIAffixes: [
//     { type: 2, degree: 5, cs: "ţř" },
//     { type: 2, degree: 1, cs: "t" },
//   ],
//   mood: undefined,
//   caseScope: undefined,
//   vn: undefined,
//   case: undefined,
//   illocutionValidation: undefined,
// }

```

```typescript
import { parseFormative } from "@zsnout/ithkuil/parse"

// Correct:

const result1 = parseFormative("hlarrau")
const result2 = parseFormative("laza")

console.log(result1, result2) // { type: "UNF/C", ... }, { type: "UNF/C", ... }

// Incorrect:

const result = parseFormative("hlarrau-laza")

console.log(result) // undefined

```

--------------------------------

### Compile Project

Source: https://github.com/zsakowitz/ithkuil/blob/main/DEVELOPING.md

Compiles the project using NPM scripts. Requires Node.js and NPM. Generates build artifacts, typically in a `dist` or `build` directory.

```sh
npm run build
```

--------------------------------

### Correct Import Statement for @zsnout/ithkuil

Source: https://github.com/zsakowitz/ithkuil/blob/main/README.md

Shows the correct method for importing functions by specifying the relevant sub-package, such as '@zsnout/ithkuil/parse'. This ensures proper module resolution.

```typescript
// CORRECT:
import { parseWord } from "@zsnout/ithkuil/parse"
```

--------------------------------

### Gloss Ithkuil Words with @zsnout/ithkuil

Source: https://github.com/zsakowitz/ithkuil/blob/main/README.md

Illustrates how to use the `@zsnout/ithkuil` library to generate both short and full glosses for Ithkuil words. It involves parsing the word first using `parseWord` and then generating glosses with `glossWord`.

```typescript
import { glossWord } from "@zsnout/ithkuil/gloss/index.js"
import { parseWord } from "@zsnout/ithkuil/parse/index.js"

const result2 = parseWord("wetace")

if (result2) {
  const { short, full } = glossWord(result2)

  // S2-‘that one’-‘female’₁-ABS
  console.log(short)

  // stem_two-‘that one’-‘female’₁-absolutive
  console.log(full)
}

```

--------------------------------

### Clone and Navigate Repository

Source: https://github.com/zsakowitz/ithkuil/blob/main/DEVELOPING.md

Clones the ithkuil repository and changes the current directory to it. Requires Git and terminal access. No specific inputs or outputs beyond file system changes.

```sh
git clone https://github.com/zsakowitz/ithkuil
cd ithkuil
```

--------------------------------

### Compile with esbuild after tsc

Source: https://github.com/zsakowitz/ithkuil/blob/main/DEVELOPING.md

Prefixes esbuild commands with `tsc ` to first compile with TypeScript before handing off to esbuild. Options then apply to `tsc`.

```sh
tsc run index.js
```

--------------------------------

### Retrieve Linguistic Data

Source: https://context7.com/zsakowitz/ithkuil/llms.txt

Methods for fetching Ithkuil roots and affixes from remote data sources using an API key. Includes functionality to save retrieved data into static files for offline access.

```typescript
import { getAffixes } from "@zsnout/ithkuil/data/affixes"
import { getRoots } from "@zsnout/ithkuil/data/roots"

// Fetch affixes data (requires API key)
async function loadAffixes() {
  const apiKey = process.env.ITHKUIL_DATA_API_KEY

  try {
    const affixes = await getAffixes(apiKey)

    // Process affix data
    affixes.forEach(affix => {
      console.log(`${affix.cs} - ${affix.abbreviation}`)
      console.log(`Description: ${affix.description}`)
      console.log(`Degrees:`, affix.degrees)
    })

    return affixes
  } catch (error) {
    console.error("Failed to fetch affixes:", error)
    throw error
  }
}

// Fetch roots data
async function loadRoots() {
  const apiKey = process.env.ITHKUIL_DATA_API_KEY

  try {
    const roots = await getRoots(apiKey)

    // Search for specific root
    const root = roots.find(r => r.root === "kš")
    if (root) {
      console.log(`Root: ${root.root}`)
      console.log(`Stems:`, root.stems)
    }

    return roots
  } catch (error) {
    console.error("Failed to fetch roots:", error)
    throw error
  }
}

// Build offline data
async function buildStaticData() {
  const affixes = await loadAffixes()
  const roots = await loadRoots()

  // Save to files for offline use
  await fs.writeFile(
    './data/affixes-latest.ts',
    `export const affixes = ${JSON.stringify(affixes)}`
  )
  await fs.writeFile(
    './data/roots-latest.ts',
    `export const roots = ${JSON.stringify(roots)}`
  )
}
```

--------------------------------

### Generate Ithkuil Affixual Adjunct with @zsnout/ithkuil

Source: https://github.com/zsakowitz/ithkuil/blob/main/README.md

Shows how to generate an affixual adjunct in Ithkuil using the `affixualAdjunctToIthkuil` function from the @zsnout/ithkuil library. This is useful for moving affixes out of formatives.

```typescript
import { affixualAdjunctToIthkuil } from "@zsnout/ithkuil/generate"

const result = affixualAdjunctToIthkuil({
  affixes: [
    {
      type: 1,
      degree: 2,
      cs: "c",
    },
  ],
  scope: "VII:DOM",
})

console.log(result)
// äce

```

--------------------------------

### Generate Ithkuil Referential with @zsnout/ithkuil

Source: https://github.com/zsakowitz/ithkuil/blob/main/README.md

Demonstrates the creation of a referential word in Ithkuil using the `referentialToIthkuil` function. This function takes referents, specification, and affixes as input to generate the Ithkuil string.

```typescript
import { referentialToIthkuil } from "@zsnout/ithkuil/generate"

const result = referentialToIthkuil({
  referents: ["1m:BEN"],
  specification: "CTE",
  affixes: [
    {
      type: 1,
      degree: 3,
      cs: "c",
    },
  ],
})

console.log(result)
// raxtec

```

--------------------------------

### Generate Affixual Adjunct

Source: https://context7.com/zsakowitz/ithkuil/llms.txt

Creates an affixual adjunct to move affixes out of formatives for structural flexibility. It supports single or multiple affixes and can be applied to concatenated stems only. Dependencies include the `affixualAdjunctToIthkuil` function from `@zsnout/ithkuil/generate`.

```typescript
import { affixualAdjunctToIthkuil } from "@zsnout/ithkuil/generate"

// Single affix with scope
const adjunct = affixualAdjunctToIthkuil({
  affixes: [
    {
      type: 1,
      degree: 2,
      cs: "c",
    },
  ],
  scope: "VII:DOM",
})
console.log(adjunct) // Output: "äce"

// Multiple affixes
const multiple = affixualAdjunctToIthkuil({
  affixes: [
    { type: 1, degree: 3, cs: "t" },
    { type: 2, degree: 5, cs: "kš" },
  ],
  scope: "V:DOM",
})
console.log(multiple) // Output with all affixes encoded

// Concatenated stem scope
const concatenated = affixualAdjunctToIthkuil({
  affixes: [{ type: 1, degree: 1, cs: "l" }],
  appliesToConcatenatedStemOnly: true,
})
console.log(concatenated)
```

--------------------------------

### Validate Ithkuil Adjuncts with Zod and @zsnout/ithkuil

Source: https://github.com/zsakowitz/ithkuil/blob/main/README.md

Demonstrates how to validate Ithkuil adjunct data structures using Zod parsers provided by the `@zsnout/ithkuil` library. This is crucial for integrating the library with external data sources and ensuring data integrity.

```typescript
import { adjunctToIthkuil } from "@zsnout/ithkuil/generate"
import { adjunct } from "@zsnout/ithkuil/zod"

const myAdjunct = getAdjunctFromSomeInternetSource()

try {
  const realAdjunct = adjunct.parse(myAdjunct)

  const result = adjunctToIthkuil(realAdjunct)

  console.log(result)
} catch (error) {
  console.error("The adjunct was malformed.", { cause: error })
}

```

--------------------------------

### Configure JSX Transform in tsconfig.json

Source: https://github.com/zsakowitz/ithkuil/blob/main/README.md

This JSON snippet shows the necessary additions to a tsconfig.json file to enable JSX processing with the '@zsnout/ithkuil/script' JSX runtime. It specifies the 'jsx' compiler option and the 'jsxImportSource'.

```json
{
  "compilerOptions": {
    ...
    "jsx": "react-jsx",
    "jsxImportSource": "@zsnout/ithkuil/script"
    ...
  }
}
```

--------------------------------

### Gloss Ithkuil Words

Source: https://context7.com/zsakowitz/ithkuil/llms.txt

Generates linguistic glosses for Ithkuil words in both short and full formats. It can gloss parsed word objects or directly from word definition objects. Dependencies include `glossWord` from `@zsnout/ithkuil/gloss` and `parseWord` from `@zsnout/ithkuil/parse`.

```typescript
import { glossWord } from "@zsnout/ithkuil/gloss"
import { parseWord } from "@zsnout/ithkuil/parse"

// Parse and gloss a word
const parsed = parseWord("wetace")
if (parsed) {
  const { short, full } = glossWord(parsed)
  console.log(short) // Output: "S2-'that one'-'female'₁-ABS"
  console.log(full) // Output: "stem_two-'that one'-'female'₁-absolutive"
}

// Gloss a formative
const formative = parseWord("kšala")
if (formative) {
  const gloss = glossWord(formative)
  console.log(gloss.short) // Abbreviated morpheme gloss
  console.log(gloss.full) // Full descriptive gloss
}

// Gloss directly from object without parsing
import { formativeToIthkuil } from "@zsnout/ithkuil/generate"
const word = {
  type: "UNF/C" as const,
  root: "m",
  stem: 2,
  version: "CPT",
}
const glossed = glossWord(word)
console.log(glossed.short)
console.log(glossed.full)
```

--------------------------------

### Generate Formative from JSON

Source: https://context7.com/zsakowitz/ithkuil/llms.txt

Converts a formative JSON object into romanized Ithkuil text with intelligent defaults for most parameters.

```APIDOC
## Generate Formative from JSON

### Description
Converts a formative JSON object into romanized Ithkuil text with intelligent defaults for most parameters.

### Method
POST

### Endpoint
/api/ithkuil/generate/formative

### Parameters
#### Request Body
- **type** (string) - Required - The type of formative (e.g., 'UNF/C').
- **concatenationType** (number) - Optional - The concatenation type.
- **version** (string) - Optional - The version of the formative.
- **stem** (number) - Optional - The stem of the formative.
- **root** (string) - Required - The root of the formative.
- **function** (string) - Optional - The function of the formative.
- **specification** (string) - Optional - The specification of the formative.
- **context** (string) - Optional - The context of the formative.
- **slotVAffixes** (array) - Optional - An array of V affixes.
  - **referents** (array) - Required - Referents for the affix.
  - **case** (string) - Required - The case of the affix.
- **ca** (object) - Optional - The ca object.
  - **configuration** (string) - Optional.
  - **affiliation** (string) - Optional.
  - **extension** (string) - Optional.
- **vn** (string) - Optional - The vn value.
- **slotVIIAffixes** (array) - Optional - An array of VII affixes.
  - **type** (number) - Required.
  - **degree** (number) - Required.
  - **cs** (string) - Required.

### Request Example
```json
{
  "type": "UNF/C",
  "concatenationType": 2,
  "version": "CPT",
  "stem": 2,
  "root": "kš",
  "function": "DYN",
  "specification": "OBJ",
  "context": "AMG",
  "slotVAffixes": [
    {
      "referents": ["1m:BEN"],
      "case": "ERG"
    }
  ],
  "ca": {
    "configuration": "MFC",
    "affiliation": "COA",
    "extension": "GRA"
  },
  "vn": "REP"
}
```

### Response
#### Success Response (200)
- **romanizedIthkuil** (string) - The generated romanized Ithkuil text.
```

--------------------------------

### Incorrect Import Statement for @zsnout/ithkuil

Source: https://github.com/zsakowitz/ithkuil/blob/main/README.md

Demonstrates the incorrect way to import functions from the @zsnout/ithkuil package. Direct top-level imports will fail.

```typescript
// INCORRECT:
import { parseWord } from "@zsnout/ithkuil"
```

--------------------------------

### Parse Formative from Text

Source: https://context7.com/zsakowitz/ithkuil/llms.txt

Parses romanized Ithkuil formative text into a structured JavaScript object.

```APIDOC
## Parse Formative from Text

### Description
Parses romanized Ithkuil formative text into a structured JavaScript object.

### Method
POST

### Endpoint
/api/ithkuil/parse/formative

### Parameters
#### Request Body
- **text** (string) - Required - The romanized Ithkuil formative text to parse.

### Request Example
```json
{
  "text": "malëuţřait"
}
```

### Response
#### Success Response (200)
- **parsedFormative** (object) - The structured JavaScript object representing the parsed formative. Returns `undefined` if the structure is invalid.

#### Error Response (400)
- **error** (string) - A message indicating the parsing error.

### Response Example (Success)
```json
{
  "parsedFormative": {
    "type": "UNF/C",
    "concatenationType": undefined,
    "shortcut": false,
    "stem": 1,
    "version": "PRC",
    "root": "m",
    "context": "EXS",
    "specification": "BSC",
    "function": "STA",
    "slotVAffixes": [],
    "ca": {},
    "slotVIIAffixes": [
      { "type": 2, "degree": 5, "cs": "ţř" },
      { "type": 2, "degree": 1, "cs": "t" }
    ],
    "mood": undefined,
    "caseScope": undefined,
    "vn": undefined,
    "case": undefined,
    "illocutionValidation": undefined
  }
}
```
```

--------------------------------

### Transform and Analyze Ithkuil Word Structures

Source: https://context7.com/zsakowitz/ithkuil/llms.txt

Functions from the parse module allow for word transformation, stress application, and detailed inspection of vowel forms. It supports parsing raw strings into structured VowelForm objects to retrieve linguistic properties like degree and sequence.

```typescript
import { transformWord, applyStress, VowelForm } from "@zsnout/ithkuil/parse";

// Transform and apply stress
const stressed = applyStress("maleit", -1);

// Parse vowel forms
const vowel = VowelForm.of("ëi");
if (vowel) {
  console.log(vowel.hasGlottalStop);
  console.log(vowel.degree);
}
```

--------------------------------

### Generate Ithkuil Word from Object

Source: https://context7.com/zsakowitz/ithkuil/llms.txt

Converts Ithkuil word types (formative, referential, or adjunct) represented as JavaScript objects into romanized text. The `wordToIthkuil` function from `@zsnout/ithkuil/generate` handles various configurations, including essences and numeric adjuncts. Input is a JavaScript object or a number, and the output is a romanized string.

```typescript
import { wordToIthkuil } from "@zsnout/ithkuil/generate"

// Generate formative
const formative = wordToIthkuil({
  type: "UNF/C",
  root: "l",
  ca: { configuration: "MFS", affiliation: "COA" },
})
console.log(formative)

// Generate referential
const referential = wordToIthkuil({
  referents: ["1m:BEN"],
  case: "ERG",
})
console.log(referential)

// Generate suppletive adjunct
const suppletive = wordToIthkuil({
  type: "NAM",
  case: "STM",
})
console.log(suppletive) // Output: "hnëi"

// Generate with essence for referential form
const withEssence = wordToIthkuil({
  type: "NAM",
  case: "STM",
  essence: "RPV",
})
console.log(withEssence) // Output: "üohnêi"

// Numeric adjunct
const number = wordToIthkuil(42)
console.log(number)
```

--------------------------------

### Generate Referential

Source: https://context7.com/zsakowitz/ithkuil/llms.txt

Creates a referential word showing reference to speech act participants with specified grammatical properties.

```APIDOC
## Generate Referential

### Description
Creates a referential word showing reference to speech act participants with specified grammatical properties.

### Method
POST

### Endpoint
/api/ithkuil/generate/referential

### Parameters
#### Request Body
- **referents** (array) - Required - An array of referents (e.g., ['1m:BEN']).
- **specification** (string) - Optional - The specification of the referential.
- **affixes** (array) - Optional - An array of affixes.
  - **type** (number) - Required.
  - **degree** (number) - Required.
  - **cs** (string) - Required.
- **case** (string) - Optional - The case of the referential.
- **referents2** (array) - Optional - A second array of referents for dual referentials.
- **case2** (string) - Optional - The case for the second set of referents.
- **perspective** (string) - Optional - The perspective of the referential.
- **essence** (string) - Optional - The essence of the referential.

### Request Example
```json
{
  "referents": ["1m:BEN"],
  "specification": "CTE",
  "affixes": [
    {
      "type": 1,
      "degree": 3,
      "cs": "c"
    }
  ],
  "case": "ERG",
  "referents2": ["2m:NEU"],
  "case2": "ABS",
  "perspective": "G",
  "essence": "RPV"
}
```

### Response
#### Success Response (200)
- **romanizedIthkuil** (string) - The generated romanized Ithkuil referential text.
```

--------------------------------

### Generate Ithkuil Formative from JSON (TypeScript)

Source: https://context7.com/zsakowitz/ithkuil/llms.txt

Converts a formative JSON object into romanized Ithkuil text. It supports simple and complex formatives with various morphological categories and affixes, using intelligent defaults where possible.

```typescript
import { formativeToIthkuil } from "@zsnout/ithkuil/generate"

// Simple formative with minimal specification
const simple = formativeToIthkuil({
  root: "kš",
  type: "UNF/C",
})
console.log(simple) // Output: "kšala"

// Complex formative with multiple morphological categories
const complex = formativeToIthkuil({
  type: "UNF/C",
  concatenationType: 2,
  version: "CPT",
  stem: 2,
  root: "kš",
  function: "DYN",
  specification: "OBJ",
  context: "AMG",
  slotVAffixes: [
    {
      referents: ["1m:BEN"],
      case: "ERG",
    },
  ],
  ca: {
    configuration: "MFC",
    affiliation: "COA",
    extension: "GRA",
  },
  vn: "REP",
})
console.log(complex) // Output: "hwikšöeroeržžgeiha"

// With multiple affixes
const withAffixes = formativeToIthkuil({
  type: "UNF/C",
  root: "m",
  slotVIIAffixes: [
    { type: 2, degree: 5, cs: "ţř" },
    { type: 2, degree: 1, cs: "t" },
  ],
  version: "PRC",
})
console.log(withAffixes) // Output: "malëuţřait"
```

--------------------------------

### Validate and Generate Ithkuil Phonemes and Ca Forms

Source: https://context7.com/zsakowitz/ithkuil/llms.txt

Utilizes the generate module to perform phonotactic validation of consonant clusters, manage glottal stops, and construct complex Ca forms. These functions ensure that generated Ithkuil structures adhere to phonological constraints.

```typescript
import { isPhonematicallyValid, insertGlottalStop, ALL_DIPTHONGS, STANDARD_VOWEL_TABLE, caToIthkuil } from "@zsnout/ithkuil/generate";

// Validate consonant cluster
console.log(isPhonematicallyValid("kš")); // true

// Insert glottal stops between vowels
const withGlottalStop = insertGlottalStop("aeiou");

// Generate Ca forms
const ca = caToIthkuil({ configuration: "MFS", affiliation: "COA", extension: "GRA" });
```

--------------------------------

### Generate Ithkuil Referential from JSON (TypeScript)

Source: https://context7.com/zsakowitz/ithkuil/llms.txt

Creates a referential word in Ithkuil from a JSON object, specifying speech act participants and grammatical properties. It supports simple and dual referentials, and can include perspective and essence.

```typescript
import { referentialToIthkuil } from "@zsnout/ithkuil/generate"

// Simple referential
const simple = referentialToIthkuil({
  referents: ["1m:BEN"],
  specification: "CTE",
  affixes: [
    {
      type: 1,
      degree: 3,
      cs: "c",
    },
  ],
})
console.log(simple) // Output: "raxtec"

// Dual referential with two participants
const dual = referentialToIthkuil({
  referents: ["1m:BEN"],
  case: "ERG",
  referents2: ["2m:NEU"],
  case2: "ABS",
})
console.log(dual) // Output shows both referents

// With perspective and essence
const complex = referentialToIthkuil({
  referents: ["3:BEN"],
  perspective: "G",
  essence: "RPV",
  case: "THM",
})
console.log(complex) // Output with perspective marking
```

--------------------------------

### Validate Ithkuil Structures with Zod

Source: https://context7.com/zsakowitz/ithkuil/llms.txt

Utilizes Zod schemas to perform runtime validation on adjuncts, formatives, and referentials. This ensures type safety when processing external linguistic data or API responses.

```typescript
import { adjunct, formative, referential } from "@zsnout/ithkuil/zod"
import { adjunctToIthkuil, formativeToIthkuil } from "@zsnout/ithkuil/generate"

// Validate adjunct from external source
function processAdjunct(data: unknown) {
  try {
    const validated = adjunct.parse(data)
    const result = adjunctToIthkuil(validated)
    console.log("Valid adjunct:", result)
    return result
  } catch (error) {
    console.error("Invalid adjunct data:", error)
    return null
  }
}

// Validate formative with detailed error handling
function processFormative(data: unknown) {
  const result = formative.safeParse(data)

  if (result.success) {
    return formativeToIthkuil(result.data)
  } else {
    console.error("Validation errors:", result.error.issues)
    return null
  }
}

// Validate referential
function processReferential(data: unknown) {
  try {
    const validated = referential.parse(data)
    console.log("Valid referential:", validated)
    return validated
  } catch (error) {
    console.error("Malformed referential:", error)
    return null
  }
}

// Use in API integration
async function fetchAndValidateWord(url: string) {
  const response = await fetch(url)
  const data = await response.json()

  // Try each word type
  const wordResult = adjunct.safeParse(data)
    .or(formative.safeParse(data))
    .or(referential.safeParse(data))

  if (wordResult.success) {
    return wordResult.data
  }
  throw new Error("Invalid word structure")
}
```

--------------------------------

### Parse Ithkuil Words

Source: https://context7.com/zsakowitz/ithkuil/llms.txt

Parses Ithkuil formatives, referentials, or adjuncts automatically from romanized text. The `parseWord` function from `@zsnout/ithkuil/parse` handles different word types and returns `undefined` for unknown words. Input is a romanized string, and output is a structured object or `undefined`.

```typescript
import { parseWord } from "@zsnout/ithkuil/parse"

// Parse a referential
const referential = parseWord("wetace")
console.log(referential)
/* Output: referential object with properties */

// Parse a formative
const formative = parseWord("kšala")
console.log(formative)
/* Output: formative object */

// Parse an adjunct
const adjunct = parseWord("äce")
console.log(adjunct)
/* Output: adjunct object */

// Unknown word returns undefined
const unknown = parseWord("xyz123")
console.log(unknown) // Output: undefined
```

--------------------------------

### Convert Text to Script SVG

Source: https://context7.com/zsakowitz/ithkuil/llms.txt

Converts romanized Ithkuil text into native script characters rendered as SVG elements. The `textToScript` function from `@zsnout/ithkuil/script` handles text conversion and offers options for handwritten style and diacritics. It returns a result object with either the SVG content or an error reason.

```typescript
import {
  textToScript,
  Anchor,
  CharacterRow,
  fitViewBox,
} from "@zsnout/ithkuil/script"

// Convert text to script characters
const result = textToScript("Wattunkí ruyün")

if (result.ok) {
  // Create SVG in browser
  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg")

  const row = CharacterRow({
    children: result.value,
    compact: true,
  })

  const anchored = Anchor({
    at: "cc",
    children: row,
  })

  svg.appendChild(anchored)
  document.body.appendChild(svg)
  fitViewBox(svg)
} else {
  console.error(result.reason)
}

// With options
const handwritten = textToScript("kšala", { handwritten: true })
const withDiacritics = textToScript("malëuţřait", {
  useCaseIllValDiacritics: true,
  handwritten: false,
})

// Multiple sentences with breaks
const text = textToScript("hlarrau. laza")
```

--------------------------------

### Parse Ithkuil Formative from Text (TypeScript)

Source: https://context7.com/zsakowitz/ithkuil/llms.txt

Parses romanized Ithkuil formative text into a structured JavaScript object. It handles individual formatives and can identify invalid structures or slots, returning undefined or throwing errors respectively.

```typescript
import { parseFormative } from "@zsnout/ithkuil/parse"

// Parse a formative
const parsed = parseFormative("malëuţřait")
console.log(parsed)
/* Output:
{
  type: "UNF/C",
  concatenationType: undefined,
  shortcut: false,
  stem: 1,
  version: "PRC",
  root: "m",
  context: "EXS",
  specification: "BSC",
  function: "STA",
  slotVAffixes: [],
  ca: {},
  slotVIIAffixes: [
    { type: 2, degree: 5, cs: "ţř" },
    { type: 2, degree: 1, cs: "t" },
  ],
  mood: undefined,
  caseScope: undefined,
  vn: undefined,
  case: undefined,
  illocutionValidation: undefined,
}
*/

// Concatenated formatives must be parsed separately
const parent = parseFormative("hlarrau")
const child = parseFormative("laza")
console.log(parent, child) // Both return parsed formative objects

// Invalid structure returns undefined
const invalid = parseFormative("hlarrau-laza")
console.log(invalid) // Output: undefined

// Invalid slots throw an error
try {
  parseFormative("invalidstructure")
} catch (error) {
  console.error("Parse error:", error.message)
}
```

--------------------------------

### Custom JSX Runtime for SVG Elements

Source: https://github.com/zsakowitz/ithkuil/blob/main/script/README.md

A custom JSX runtime designed to simplify working with SVG elements in the Ithkuil script generator. It provides a concise syntax for HTML tags, attributes, and children, acting as a direct replacement for verbose DOM manipulation methods.

```tsx
<g>
  <path d="..." />

  <path
    d="..."
    fill="red"
  />
</g>
```
Tokens:
Raw