Hyphenatorx

https://github.com/xerik/hyphenatorx
Admin
Hyphenatorx is a Dart package implementing hyphenation algorithms for multiple languages based on...
Tokens:11,263
Snippets:64
Trust Score:6.2
Update:6 months ago
Show doc for...
Tokens:
Raw
### Quickstart: Hyphenator Functions

Source: https://github.com/xerik/hyphenatorx/blob/master/README.md

Illustrates the core functions of the Hyphenator class for hyphenating text and extracting syllables.

```APIDOC
## Quickstart: Hyphenator Functions

### Description
This snippet demonstrates how to initialize the `Hyphenator` class and use its functions to hyphenate text and get word syllables.

### Method
N/A (Function Usage)

### Endpoint
N/A (Function Usage)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```dart
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/language_en_us.dart';

final hyphenator = Hyphenator(Language_en_us(), symbol: '_');

// 'sub_di_vi_sion_ _sub_di_vi_sion'
print(
  hyphenator.hyphenateText('subdivision subdivision', 
    hyphenAtBoundaries: true));

// sub_di_vi_sion sub_di_vi_sion
print(hyphenator.hyphenateText('subdivision subdivision'));

// sub_di_vi_sion
print(hyphenator.hyphenateWord('subdivision'));

// ['sub', 'di', 'vi', 'sion']
print(hyphenator.syllablesWord('subdivision'));
```

### Response
N/A (Function Usage)
```

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

### Quickstart: TextHyphenated Widget

Source: https://github.com/xerik/hyphenatorx/blob/master/README.md

Demonstrates the basic usage of the TextHyphenated widget for displaying hyphenated text.

```APIDOC
## Quickstart: TextHyphenated Widget

### Description
This snippet shows how to use the `TextHyphenated` widget to display a hyphenated string.

### Method
N/A (Widget Usage)

### Endpoint
N/A (Widget Usage)

### Request Example
```dart
import 'package:hyphenatorx/widget/texthyphenated.dart';

// sub-
// di-
// vi-
// sion
TextHyphenated('subdivision', 
  'en_us',
  style: TextStyle(fontSize: 56))
```

### Response
N/A (Widget Usage)
```

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

### Quickstart: Basic Text Hyphenation in Dart

Source: https://github.com/xerik/hyphenatorx/blob/master/README.md

Demonstrates the basic usage of the Hyphenator class to hyphenate text and extract syllables. It initializes the hyphenator with a specific language configuration and a custom hyphen symbol.

```dart
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/language_en_us.dart';

final hyphenator = Hyphenator(Language_en_us(), symbol: '_');

// 'sub_di_vi_sion_ _sub_di_vi_sion'
print(
  hyphenator.hyphenateText('subdivision subdivision', 
    hyphenAtBoundaries: true));

// sub_di_vi_sion sub_di_vi_sion
print(hyphenator.hyphenateText('subdivision subdivision'));

// sub_di_vi_sion
print(hyphenator.hyphenateWord('subdivision'));

// ['sub', 'di', 'vi', 'sion']
print(hyphenator.syllablesWord('subdivision'));      
```

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

### TextHyphenated Widget Example

Source: https://github.com/xerik/hyphenatorx/blob/master/README.md

A simple example demonstrating the TextHyphenated widget for displaying hyphenated text. This widget handles the hyphenation and rendering of text, suitable for UI components.

```dart
import 'package:hyphenatorx/widget/texthyphenated.dart';

// sub-
// di-
// vi-
// sion
TextHyphenated('subdivision', 
  'en_us',
  style: TextStyle(fontSize: 56))
```

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

### Get Available Languages and Load Hyphenators (Dart)

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Illustrates how to retrieve a list of all supported language abbreviations using `Hyphenator.languageAbbr()`. It also demonstrates asynchronously loading `Hyphenator` instances for multiple languages using `loadAsyncByAbbr()` and then using these instances to hyphenate words. This is useful for supporting multilingual text.

```dart
import 'package:hyphenatorx/hyphenatorx.dart';

// Get all available language codes
List<String> languages = Hyphenator.languageAbbr();

print(languages);
// Output: [af, as, bg, bn, ca, cop, cs, cy, da, de_1901, de_1996, de_ch_1901,
// el_monoton, el_polyton, en_gb, en_us, eo, es, et, eu, fi, fr, fur, ga, gl,
// grc, gu, hi, hr, hsb, hu, hy, ia, id, is, it, ka, kmr, kn, la_x_classic,
// la, lt, lv, ml, mn_cyrl_x_lmc, mn_cyrl, mr, mul_ethi, nb, nl, nn, or, pa,
// pl, pms, pt, rm, ro, ru, sa, sh_cyrl, sk, sl, sv, ta, te, th, tk, tr, uk,
// zh_latn_pinyin]

// Example: Create hyphenators for multiple languages
Future<void> multiLanguageExample() async {
  final Map<String, Hyphenator> hyphenators = {};

  for (final lang in ['en_us', 'de_1996', 'fr', 'es', 'it']) {
    hyphenators[lang] = await Hyphenator.loadAsyncByAbbr(lang);
  }

  // Use appropriate hyphenator based on text language
  print(hyphenators['en_us']!.hyphenateWord('subdivision'));
  print(hyphenators['de_1996']!.hyphenateWord('Geschwindigkeit'));
  print(hyphenators['fr']!.hyphenateWord('internationale'));
}
```

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

### Function Call: Wrapping Text with Hyphenation in Dart

Source: https://github.com/xerik/hyphenatorx/blob/master/README.md

Provides an example of using the `wrap` function to hyphenate and wrap text within a specified maximum width. It also shows how to check if the text fits within the constraints.

```dart
final hyphenator = Hyphenator(Language_en_us());

WrapResult wrap = hyphenator.wrap(
  final Text text, final TextStyle style, final maxWidth);

// The hyphenated text with hyphens and newlines:
// 
// sub-
// di-
// vi-
// sion- 
print( wrap.textStr ); 

// Whether the returned text is equal to 
// or smaller than maxWidth. 
//
// If FALSE, try a different font size.

print( wrap.isSizeMatching );  
```

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

### Synchronous Hyphenator Instantiation in Dart

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Demonstrates creating a Hyphenator instance with pre-compiled language data for immediate use. This method loads all language data into memory, offering faster runtime operations at the cost of higher memory consumption. It includes examples for hyphenating single words, entire texts, and extracting syllables.

```dart
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/language_en_us.dart';

// Create hyphenator with English US language configuration
final hyphenator = Hyphenator(
  Language_en_us(),
  symbol: '_',        // Custom hyphen symbol (default: soft-wrap '\u{00AD}')
  hyphen: '-',        // Hyphen character for line breaks
  minWordLength: 5,   // Minimum word length to hyphenate
  minLetterCount: 3,  // Minimum letters before/after hyphen
);

// Hyphenate a single word
String result = hyphenator.hyphenateWord('subdivision');
// Output: 'sub_di_vi_sion'

// Hyphenate entire text (preserves whitespace)
String textResult = hyphenator.hyphenateText('subdivision subdivision');
// Output: 'sub_di_vi_sion sub_di_vi_sion'

// Get syllables as a list
List<String> syllables = hyphenator.syllablesWord('subdivision');
// Output: ['sub', 'di', 'vi', 'sion']
```

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

### Wrap Text to Pixel Width

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Provides an example of wrapping text within a specific pixel width using the wrap method in a Flutter context. Returns a WrapResult containing the formatted text and layout metadata.

```dart
import 'package:flutter/material.dart';
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/language_en_us.dart';
import 'package:hyphenatorx/token/wrapresult.dart';

final hyphenator = Hyphenator(Language_en_us());

void wrapExample(BuildContext context) {
  final text = Text('A vast subdivision of culture');
  final style = TextStyle(fontSize: 24);
  final maxWidth = 150.0;

  WrapResult result = hyphenator.wrap(text, style, maxWidth);

  print(result.textStr);
  print(result.isSizeMatching);
  print(result.size);
  Text wrappedText = result.text;
}
```

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

### Asynchronous Hyphenator Loading in Dart

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Illustrates loading hyphenation patterns from JSON assets asynchronously, which is memory-efficient for mobile applications. This approach loads language data on demand. Examples show loading using a Language enum and by language abbreviation string.

```dart
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/languageconfig.dart';

// Load using Language enum
Future<void> loadWithEnum() async {
  final hyphenator = await Hyphenator.loadAsync(
    Language.language_en_us,
    symbol: '_',
    hyphen: '-',
    minWordLength: 5,
    minLetterCount: 3,
  );

  print(hyphenator.hyphenateText('extraordinary accomplishments'));
  // Output: 'ex_traor_di_nary ac_com_plish_ments'
}

// Load using language abbreviation string
Future<void> loadWithAbbreviation() async {
  final hyphenator = await Hyphenator.loadAsyncByAbbr(
    'de_1996',  // German, 1996 spelling reform
    symbol: '-',
  );

  print(hyphenator.hyphenateText('Geschwindigkeitsbegrenzung'));
  // Output: 'Ge-schwin-dig-keits-be-gren-zung'
}
```

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

### Asynchronous Instantiation

Source: https://github.com/xerik/hyphenatorx/blob/master/README.md

Shows how to asynchronously load language data for the Hyphenator.

```APIDOC
## Asynchronous Instantiation

### Description
This section details how to instantiate the `Hyphenator` class asynchronously, loading language data as needed.

### Method
N/A (Instantiation)

### Endpoint
N/A (Instantiation)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```dart
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/language_en_us.dart';

// Using Language enum
final hyphernator = await Hyphenator.loadAsync(
    Language.language_en_us, 
    symbol: '_');

// Using language abbreviation
final hyphernator = await Hyphenator.loadAsyncByAbbr(
    'en_us', 
    symbol: '_');
```

### Response
N/A (Instantiation)
```

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

### Initialize Flutter Web Engine

Source: https://github.com/xerik/hyphenatorx/blob/master/example/flutter_example/web/index.html

This script handles the loading of the main.dart.js entrypoint for a Flutter web application. It registers a load event listener to initialize the Flutter engine and run the application once the entrypoint is loaded.

```javascript
var serviceWorkerVersion = null;
window.addEventListener('load', function(ev) {
  _flutter.loader.loadEntrypoint({
    serviceWorker: {
      serviceWorkerVersion: serviceWorkerVersion,
    },
    onEntrypointLoaded: function(engineInitializer) {
      engineInitializer.initializeEngine().then(function(appRunner) {
        appRunner.runApp();
      });
    }
  });
});
```

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

### Generate Language Assets

Source: https://github.com/xerik/hyphenatorx/blob/master/README.md

Runs the build tool to process TeX files and generate the necessary Dart language files.

```shell
dart run ./tool/tex2dart.dart
```

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

### Synchronous Instantiation

Source: https://github.com/xerik/hyphenatorx/blob/master/README.md

Demonstrates synchronous instantiation of the Hyphenator with pre-compiled language data.

```APIDOC
## Synchronous Instantiation

### Description
This section explains how to synchronously instantiate the `Hyphenator` class by directly providing a language configuration object.

### Method
N/A (Instantiation)

### Endpoint
N/A (Instantiation)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```dart
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/language_en_us.dart';

final config = Language_en_us();

final hyphenator = Hyphenator(
  config,
  symbol: '_',
);
```

### Response
N/A (Instantiation)
```

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

### Asynchronous Hyphenator Instantiation in Dart

Source: https://github.com/xerik/hyphenatorx/blob/master/README.md

Shows how to asynchronously load language configurations for the Hyphenator. This method is useful for reducing initial memory load by loading language data as needed from assets.

```dart
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/language_en_us.dart';

final hyphernator = await Hyphenator.loadAsync(
    Language.language_en_us, 
    symbol: '_');

// OR THIS:

final hyphernator = await Hyphenator.loadAsyncByAbbr(
    'en_us', 
    symbol: '_');
```

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

### Synchronous Hyphenator Instantiation in Dart

Source: https://github.com/xerik/hyphenatorx/blob/master/README.md

Demonstrates synchronous instantiation of the Hyphenator with a specific language configuration. This approach compiles language data directly into the project, making it readily available.

```dart
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/language_en_us.dart';

final config = Language_en_us();

final hyphenator = Hyphenator(
  config,
  symbol: '_',
);
```

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

### Initialize Hyphenator with Language Enum

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Demonstrates how to use the Language enum for type-safe loading of hyphenation patterns. It also shows how to convert string identifiers to enum values and handle invalid language inputs.

```dart
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/languageconfig.dart';

Future<void> enumExample() async {
  final enUs = await Hyphenator.loadAsync(Language.language_en_us);
  final de = await Hyphenator.loadAsync(Language.language_de_1996);
  final fr = await Hyphenator.loadAsync(Language.language_fr);
  final es = await Hyphenator.loadAsync(Language.language_es);

  Language lang = Hyphenator.getLanguageEnum('en_us');

  try {
    Hyphenator.getLanguageEnum('invalid');
  } catch (e) {
    print(e);
  }
}
```

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

### Synchronous Hyphenator Instantiation

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Creates a Hyphenator instance using pre-compiled language configurations for immediate, memory-resident hyphenation.

```APIDOC
## Synchronous Hyphenator Instantiation

### Description
Initializes the Hyphenator with a specific language configuration loaded into memory at compile time.

### Method
Constructor: Hyphenator(LanguageConfig, {symbol, hyphen, minWordLength, minLetterCount})

### Parameters
#### Request Body
- **language** (LanguageConfig) - Required - The language configuration object (e.g., Language_en_us()).
- **symbol** (String) - Optional - The character used for hyphenation points (default: '\u{00AD}').
- **minWordLength** (int) - Optional - Minimum length of a word to be considered for hyphenation.

### Request Example
final hyphenator = Hyphenator(Language_en_us(), symbol: '_');

### Response
- **Hyphenator** (Instance) - Returns an object capable of performing hyphenation operations.
```

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

### Tokenize Text for Advanced Layouts

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Illustrates how to break text into a structured tree of tokens (words, whitespace, newlines) using hyphenateTextToTokens for custom text rendering algorithms.

```dart
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/language_en_us.dart';
import 'package:hyphenatorx/token/tokens.dart';

final hyphenator = Hyphenator(Language_en_us());

final text = """A vast subdivision of culture,
composed of many creative endeavors.""";

List<TextPartToken> tokens = hyphenator.hyphenateTextToTokens(text);

for (final part in tokens) {
  if (part is NewlineToken) {
    print('NEWLINE: ${part.text}');
  } else if (part is TabsAndSpacesToken) {
    print('WHITESPACE: "${part.text}"');
  } else if (part is WordToken) {
    print('WORD with syllables:');
    for (final syllable in part.parts) {
      print('  - ${syllable.text}');
    }
  }
}
```

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

### Hyphenate Single Words with HyphenatorX

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Demonstrates how to initialize the Hyphenator class and use the hyphenateWord method to insert hyphen symbols into words. It also highlights internal caching mechanisms for performance.

```dart
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/language_en_us.dart';

final hyphenator = Hyphenator(Language_en_us(), symbol: '-');

print(hyphenator.hyphenateWord('subdivision'));
print(hyphenator.hyphenateWord('extraordinary'));
print(hyphenator.hyphenateWord('accomplishment'));
print(hyphenator.hyphenateWord('internationalization'));

print(hyphenator.hyphenateWord('the'));
print(hyphenator.hyphenateWord('art'));

print(hyphenator.cachedHyphendWords);
print(hyphenator.cachedNonHyphendWords);
```

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

### Function Call: Hyphenate and Syllables

Source: https://github.com/xerik/hyphenatorx/blob/master/README.md

Explains how to use the hyphenateText, hyphenateWord, and syllablesWord functions.

```APIDOC
## Function Call: Hyphenate and Syllables

### Description
This section details the usage of `hyphenateText`, `hyphenateWord`, and `syllablesWord` functions to manipulate text hyphenation and extract syllables.

### Method
N/A (Function Usage)

### Endpoint
N/A (Function Usage)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```dart
final hyphenator = Hyphenator(Language_en_us());

expect(
  hyphenator.hyphenateText('subdivision subdivision', 
    hyphenAtBoundaries: true),
  'sub_di_vi_sion_ _sub_di_vi_sion');

expect(
  hyphenator.hyphenateText('subdivision subdivision'),
  'sub_di_vi_sion sub_di_vi_sion');

expect(
  hyphenator.hyphenateWord('subdivision'),
  'sub_di_vi_sion');

expect(
  hyphenator.syllablesWord('subdivision'),
  ['sub', 'di', 'vi', 'sion']);
```

### Response
N/A (Function Usage)
```

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

### Function Call: Wrap

Source: https://github.com/xerik/hyphenatorx/blob/master/README.md

Details the usage of the wrap function for text wrapping with hyphenation and size checking.

```APIDOC
## Function Call: Wrap

### Description
This section explains how to use the `wrap` function to get hyphenated text that fits within a specified maximum width and checks if the size matches.

### Method
N/A (Function Usage)

### Endpoint
N/A (Function Usage)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```dart
final hyphenator = Hyphenator(Language_en_us());

WrapResult wrap = hyphenator.wrap(
  final Text text, final TextStyle style, final maxWidth);

// The hyphenated text with hyphens and newlines:
// 
// sub-
// di-
// vi-
// sion- 
print( wrap.textStr ); 

// Whether the returned text is equal to 
// or smaller than maxWidth.
//
// If FALSE, try a different font size.

print( wrap.isSizeMatching );
```

### Response
N/A (Function Usage)
```

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

### Language Enum Usage

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Demonstrates how to use the `Language` enum for type-safe loading of hyphenation configurations in HyphenatorX.

```APIDOC
## Language Enum Usage

### Description
This section illustrates the usage of the `Language` enum provided by the HyphenatorX library. The enum allows for type-safe selection of languages, ensuring that only supported languages can be loaded at compile time. It also shows how to convert string representations of languages into their corresponding enum values and how the library handles invalid language inputs.

### Method
Dart (asynchronous and synchronous operations)

### Endpoint
N/A (This is a library usage example, not an API endpoint)

### Parameters
N/A

### Request Example
```dart
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/languageconfig.dart';

// Using Language enum for type safety
Future<void> enumExample() async {
  // English (US)
  final enUs = await Hyphenator.loadAsync(Language.language_en_us);

  // German (1996 spelling reform)
  final de = await Hyphenator.loadAsync(Language.language_de_1996);

  // French
  final fr = await Hyphenator.loadAsync(Language.language_fr);

  // Spanish
  final es = await Hyphenator.loadAsync(Language.language_es);

  // Convert string to enum
  Language lang = Hyphenator.getLanguageEnum('en_us');
  // Returns: Language.language_en_us

  // Invalid language throws exception
  try {
    Hyphenator.getLanguageEnum('invalid');
  } catch (e) {
    print(e); // 'Language not found: invalid (language_invalid). Try: [af, as, ...]' 
  }
}
```

### Response
N/A (This is a code example demonstrating library functionality)

### Available Language Enum Values

- `Language.language_af` (Afrikaans)
- `Language.language_en_us` (English US)
- `Language.language_en_gb` (English GB)
- `Language.language_de_1996` (German, 1996 reform)
- `Language.language_de_1901` (German, 1901 spelling)
- `Language.language_fr` (French)
- `Language.language_es` (Spanish)
- `Language.language_it` (Italian)
- `Language.language_pt` (Portuguese)
- `Language.language_ru` (Russian)
- `Language.language_zh_latn_pinyin` (Chinese Pinyin)
- ... and 60+ more languages
```

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

### Perform Manual Hyphenation with Tokenization

Source: https://github.com/xerik/hyphenatorx/blob/master/README.md

Demonstrates how to use the Hyphenator class to break text into tokens and iterate through syllables. It handles different token types like newlines, whitespace, and words.

```dart
final text = """A vast subdivision of culture, \n    composed of many creative endeavors and disciplines.""";\n\nfinal hyphenator = Hyphenator(Language_en_us());\nfinal List<TextPartToken> tokens = hyphenator.hyphenateTextToTokens(text);\n\ntokens.forEach((part) {\n  if (part is NewlineToken) {\n    print(part.text);\n  } else if (part is TabsAndSpacesToken) {\n    print(part.text);\n  } else if (part is WordToken) {\n    part.parts.forEach((syllableAndSurrounding) {\n      print(syllableAndSurrounding.text);\n    });\n  }\n});
```

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

### Asynchronous Hyphenator Loading

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Loads hyphenation patterns from JSON assets asynchronously to optimize memory usage in mobile applications.

```APIDOC
## Asynchronous Hyphenator Loading

### Description
Loads language data on-demand from JSON assets, which is recommended for memory-constrained environments.

### Method
Static Method: Hyphenator.loadAsync(Language, {symbol, ...}) or Hyphenator.loadAsyncByAbbr(String, {symbol, ...})

### Parameters
#### Query Parameters
- **language** (Language Enum/String) - Required - The language code or abbreviation (e.g., 'de_1996').

### Request Example
final hyphenator = await Hyphenator.loadAsync(Language.language_en_us, symbol: '-');

### Response
- **Future<Hyphenator>** (Instance) - A future that resolves to a configured Hyphenator instance.
```

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

### Retrieve Supported Language Abbreviations

Source: https://github.com/xerik/hyphenatorx/blob/master/README.md

Retrieves a list of all supported language abbreviations available in the Hyphenator package.

```dart
List<String> abbr = Hyphenator.languageAbbr();\nprint(abbr);
```

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

### Width-based Text Wrapping

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Wraps hyphenated text to fit within a specified pixel width, returning a `WrapResult` with formatted text and sizing information.

```APIDOC
## wrap - Width-based Text Wrapping

### Description
Wraps hyphenated text to fit within a specified pixel width, returning a `WrapResult` with the formatted text and sizing information. Essential for responsive text layouts that need to fit within constrained spaces.

### Method
This is a method within the Hyphenator class.

### Endpoint
N/A (This is a library function, not a web endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```dart
import 'package:flutter/material.dart';
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/language_en_us.dart';
import 'package:hyphenatorx/token/wrapresult.dart';

final hyphenator = Hyphenator(Language_en_us());

// Wrap text within a specific width
void wrapExample(BuildContext context) {
  final text = Text('A vast subdivision of culture');
  final style = TextStyle(fontSize: 24);
  final maxWidth = 150.0; // pixels

  WrapResult result = hyphenator.wrap(text, style, maxWidth);

  // Get the wrapped text string with hyphens and newlines
  print(result.textStr);
  // Output:
  // 'A vast sub-
  // di-vi-
  // sion of
  // cul-ture'

  // Check if text fits within maxWidth
  print(result.isSizeMatching); // true if width <= maxWidth

  // Get computed size
  print(result.size); // Size(width, height) in pixels

  // Access the wrapped Text widget
  Text wrappedText = result.text;
}
```

### Response
#### Success Response (WrapResult)
Returns a `WrapResult` object containing the wrapped text, sizing information, and the wrapped `Text` widget.

#### Response Example
`WrapResult(textStr: 'A vast sub-\ndi-vi-\nsion of\ncul-ture', isSizeMatching: true, size: Size(150.0, 80.0), text: Text('A vast sub-\ndi-vi-\nsion of\ncul-ture'))`
```

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

### Widget Usage: TextHyphenated

Source: https://github.com/xerik/hyphenatorx/blob/master/README.md

Provides details on using the TextHyphenated widget for responsive text wrapping with hyphenation.

```APIDOC
## Widget Usage: TextHyphenated

### Description
This widget outputs a `Text` widget that hyphenates and wraps the input `String` based on the available width.

### Method
N/A (Widget Usage)

### Endpoint
N/A (Widget Usage)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```dart
import 'package:hyphenatorx/widget/texthyphenated.dart';

TextHyphenated('subdivision', 
  'en_us',
  style: TextStyle(fontSize: 56))

// Wraps the output according to the available width:
// 
// sub-
// di-
// vi-
// sion
```

### Response
N/A (Widget Usage)
```

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

### Wrap Text Without Hyphenation (Dart)

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Demonstrates the static `wrapNoHyphen` method for wrapping text at word boundaries without performing hyphenation. It takes a `Text` widget, `TextStyle`, and maximum width as input, returning a `WrapResult` object containing the wrapped text string and its computed dimensions. This is useful when preserving whole words is critical.

```dart
import 'package:flutter/material.dart';
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/token/wrapresult.dart';

// Wrap text without hyphenation
void noHyphenWrapExample() {
  final text = Text('A vast subdivision of culture');
  final style = TextStyle(fontSize: 24);
  final maxWidth = 150.0;

  // Static method - no Hyphenator instance needed
  WrapResult result = Hyphenator.wrapNoHyphen(text, style, maxWidth);

  print(result.textStr);
  // Output wraps at word boundaries only:
  // 'A vast
  // subdivision
  // of culture'

  print(result.isSizeMatching); // Check if text fits
  print(result.size);           // Computed dimensions
}
```

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

### Extract Syllables from Words

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Shows how to retrieve a list of syllables for a given word using the syllablesWord method. This is useful for custom rendering or advanced text analysis.

```dart
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/language_en_us.dart';

final hyphenator = Hyphenator(Language_en_us());

List<String> syllables1 = hyphenator.syllablesWord('subdivision');
List<String> syllables2 = hyphenator.syllablesWord('accomplishment');
List<String> syllables3 = hyphenator.syllablesWord('internationalization');
List<String> syllables4 = hyphenator.syllablesWord('cat');

String customHyphenation = syllables1.join('|');
```

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

### Token-based Text Processing

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Breaks text into a structured token tree for custom hyphenation rendering. Each token represents a word, whitespace, or newline.

```APIDOC
## hyphenateTextToTokens - Token-based Text Processing

### Description
Breaks text into a structured token tree for custom hyphenation rendering. Each token represents a word (with syllables), whitespace, or newline, enabling advanced text layout algorithms.

### Method
This is a method within the Hyphenator class.

### Endpoint
N/A (This is a library function, not a web endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```dart
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/language_en_us.dart';
import 'package:hyphenatorx/token/tokens.dart';

final hyphenator = Hyphenator(Language_en_us());

final text = """
A vast subdivision of culture,
composed of many creative endeavors."""

List<TextPartToken> tokens = hyphenator.hyphenateTextToTokens(text);

// Process tokens for custom rendering
for (final part in tokens) {
  if (part is NewlineToken) {
    print('NEWLINE: ${part.text}');
  } else if (part is TabsAndSpacesToken) {
    print('WHITESPACE: "${part.text}"');
  } else if (part is WordToken) {
    print('WORD with syllables:');
    for (final syllable in part.parts) {
      print('  - ${syllable.text}');
    }
  }
}

// Output:
// WORD with syllables:
//   - A
// WHITESPACE: " "
// WORD with syllables: 
//   - vast
// WHITESPACE: " "
// WORD with syllables:
//   - sub
//   - di
//   - vi
//   - sion
// ...
```

### Response
#### Success Response (List<TextPartToken>)
Returns a list of `TextPartToken` objects representing words, whitespace, and newlines.

#### Response Example
`[WordToken(parts: [TextPart(text: 'A')]), TabsAndSpacesToken(text: ' '), WordToken(parts: [TextPart(text: 'vast')]), TabsAndSpacesToken(text: ' '), WordToken(parts: [TextPart(text: 'sub'), TextPart(text: 'di'), TextPart(text: 'vi'), TextPart(text: 'sion')]), ...]`
```

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

### Syllable Extraction

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Returns a list of syllables for a single word, useful for custom hyphenation rendering or text analysis.

```APIDOC
## syllablesWord - Syllable Extraction

### Description
Returns a list of syllables for a single word, useful for custom hyphenation rendering or text analysis. Each syllable represents a valid break point for hyphenation.

### Method
This is a method within the Hyphenator class.

### Endpoint
N/A (This is a library function, not a web endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```dart
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/language_en_us.dart';

final hyphenator = Hyphenator(Language_en_us());

// Get syllables as a list
List<String> syllables1 = hyphenator.syllablesWord('subdivision');
// Output: ['sub', 'di', 'vi', 'sion']

List<String> syllables2 = hyphenator.syllablesWord('accomplishment');
// Output: ['ac', 'com', 'plish', 'ment']

List<String> syllables3 = hyphenator.syllablesWord('internationalization');
// Output: ['in', 'ter', 'na', 'tion', 'al', 'iza', 'tion']

// Words that cannot be hyphenated return single-element list
List<String> syllables4 = hyphenator.syllablesWord('cat');
// Output: ['cat']

// Custom processing example
String customHyphenation = syllables1.join('|');
// Output: 'sub|di|vi|sion'
```

### Response
#### Success Response (List<String>)
Returns a list of strings, where each string is a syllable of the input word.

#### Response Example
['sub', 'di', 'vi', 'sion']
```

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

### hyphenateText - Text Hyphenation

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Processes a full string to insert hyphenation symbols while preserving original whitespace and punctuation.

```APIDOC
## hyphenateText

### Description
Applies hyphenation rules to an entire string, preserving formatting and optionally adding boundary markers.

### Method
Instance Method: hyphenateText(String text, {bool hyphenAtBoundaries})

### Parameters
#### Request Body
- **text** (String) - Required - The input text to be hyphenated.
- **hyphenAtBoundaries** (bool) - Optional - If true, adds hyphen symbols at word boundaries.

### Request Example
hyphenator.hyphenateText('subdivision', hyphenAtBoundaries: true);

### Response
- **String** - The resulting hyphenated text string.
```

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

### TextHyphenated Widget for Flutter (Dart)

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Showcases the `TextHyphenated` Flutter widget, which automatically hyphenates and wraps text based on available width. It supports various configurations, including language codes, custom hyphen symbols, debug overlays, and all standard `Text` widget properties like `style`, `textAlign`, `maxLines`, and `overflow`. Language data is loaded asynchronously.

```dart
import 'package:flutter/material.dart';
import 'package:hyphenatorx/widget/texthyphenated.dart';

class HyphenatedTextExample extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Column(
        children: [
          // Basic usage with language code
          TextHyphenated(
            'A vast subdivision of culture, composed of many creative endeavors.',
            'en_us',
            style: TextStyle(fontSize: 24),
          ),

          // With custom hyphen symbol
          TextHyphenated(
            'internationalization',
            'en_us',
            symbol: '-',  // Visible hyphen (default is soft-wrap)
            style: TextStyle(fontSize: 56),
          ),

          // German text example
          TextHyphenated(
            'Geschwindigkeitsbegrenzung auf der Autobahn',
            'de_1996',
            style: TextStyle(fontSize: 32),
          ),

          // With debug overlay showing size info
          TextHyphenated(
            'subdivision',
            'en_us',
            doShowDebug: true,
            style: TextStyle(fontSize: 48),
          ),

          // Full configuration with all Text properties
          TextHyphenated(
            'Creative endeavors and disciplines',
            'en_us',
            symbol: '\u{00AD}',
            style: TextStyle(
              fontSize: 20,
              fontWeight: FontWeight.bold,
              color: Colors.blue,
            ),
            textAlign: TextAlign.center,
            maxLines: 3,
            overflow: TextOverflow.ellipsis,
            softWrap: true,
          ),
        ],
      ),
    );
  }
}
```

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

### Widget Usage: TextHyphenated in Dart

Source: https://github.com/xerik/hyphenatorx/blob/master/README.md

Illustrates how to use the TextHyphenated widget to display hyphenated text that wraps according to available width. This is useful for UI elements where text needs to fit within specific constraints.

```dart
import 'package:hyphenatorx/widget/texthyphenated.dart';

TextHyphenated('subdivision', 
  'en_us',
  style: TextStyle(fontSize: 56))

// Wraps the output according to the available width:
// 
// sub-
// di-
// vi-
// sion
```

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

### Single Word Hyphenation

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Hyphenates a single word, inserting hyphen symbols at valid break points. Results are cached for performance.

```APIDOC
## hyphenateWord - Single Word Hyphenation

### Description
Hyphenates a single word, returning the word with hyphen symbols inserted at all valid break points. Results are cached internally for performance optimization on repeated calls.

### Method
This is a method within the Hyphenator class.

### Endpoint
N/A (This is a library function, not a web endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```dart
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/language_en_us.dart';

final hyphenator = Hyphenator(Language_en_us(), symbol: '-');

// Hyphenate individual words
print(hyphenator.hyphenateWord('subdivision'));     // 'sub-di-vi-sion'
print(hyphenator.hyphenateWord('extraordinary'));   // 'ex-traor-di-nary'
print(hyphenator.hyphenateWord('accomplishment'));  // 'ac-com-plish-ment'
print(hyphenator.hyphenateWord('internationalization')); // 'in-ter-na-tion-al-iza-tion'

// Short words are not hyphenated (based on minWordLength)
print(hyphenator.hyphenateWord('the'));   // 'the' (no hyphenation)
print(hyphenator.hyphenateWord('art'));   // 'art' (no hyphenation)

// Access cache for debugging/optimization
print(hyphenator.cachedHyphendWords);     // List of cached hyphenated words
print(hyphenator.cachedNonHyphendWords);  // List of cached non-hyphenatable words
```

### Response
#### Success Response (String)
Returns the hyphenated word as a string.

#### Response Example
'sub-di-vi-sion'
```

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

### Language Enumeration

Source: https://github.com/xerik/hyphenatorx/blob/master/README.md

The Language enum contains all supported languages for hyphenation, prefixed with 'language_' to avoid conflicts with reserved keywords like 'is'.

```dart
enum Language { language_af, language_as, language_bg, language_bn, language_ca, language_cop, language_cs, language_cy, language_da, language_de_1901, language_de_1996, language_de_ch_1901, language_el_monoton, language_el_polyton, language_en_gb, language_en_us, language_eo, language_es, language_et, language_eu, language_fi, language_fr, language_fur, language_ga, language_gl, language_grc, language_gu, language_hi, language_hr, language_hsb, language_hu, language_hy, language_ia, language_id, language_is, language_it, language_ka, language_kmr, language_kn, language_la_x_classic, language_la, language_lt, language_lv, language_ml, language_mn_cyrl_x_lmc, language_mn_cyrl, language_mr, language_mul_ethi, language_nb, language_nl, language_nn, language_or, language_pa, language_pl, language_pms, language_pt, language_rm, language_ro, language_ru, language_sa, language_sh_cyrl, language_sk, language_sl, language_sv, language_ta, language_te, language_th, language_tk, language_tr, language_uk, language_zh_latn_pinyin }
```

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

### hyphenateText - Text Hyphenation in Dart

Source: https://context7.com/xerik/hyphenatorx/llms.txt

Details the `hyphenateText` method for hyphenating all words within a given text string. It preserves original whitespace and punctuation, inserting a specified hyphen symbol at valid hyphenation points. An optional `hyphenAtBoundaries` parameter is available for adding hyphens between words.

```dart
import 'package:hyphenatorx/hyphenatorx.dart';
import 'package:hyphenatorx/languages/language_en_us.dart';

final hyphenator = Hyphenator(Language_en_us(), symbol: '_');

// Basic text hyphenation (words only)
String text = hyphenator.hyphenateText(
  'A vast subdivision of culture, composed of many creative endeavors.'
);
// Output: 'A vast sub_di_vi_sion of cul_ture, com_posed of many cre_ative en_deav_ors.'

// With boundary hyphenation (adds symbols between words)
String withBoundaries = hyphenator.hyphenateText(
  'subdivision subdivision',
  hyphenAtBoundaries: true,
);
// Output: 'sub_di_vi_sion_ _sub_di_vi_sion'

// Handles multiple whitespace and newlines
String multiline = hyphenator.hyphenateText('''
The arts are a vast subdivision
of culture, composed of many
creative endeavors and disciplines.
''');
// Preserves newlines and spacing while hyphenating words
```
Tokens:
Raw