terminfokit

https://docs.rs/terminfokit/
Admin
terminfokit is a Rust library and toolkit for compiling, decoding, editing, decompiling, querying,...
Tokens:266,845
Snippets:2,052
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### install(&self, entry: &Entry, options: InstallOptions) -> Result<InstallReport, DatabaseError>

Source: https://docs.rs/terminfokit/latest/terminfokit/database/struct.DirectoryDatabase.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Atomically installs an entry and optionally its aliases.

```APIDOC
## install(&self, entry: &Entry, options: InstallOptions) -> Result<InstallReport, DatabaseError>

### Description
Atomically installs an entry and optionally its aliases.

### Method
install

### Parameters
- **self** (&self) - The database instance.
- **entry** (&Entry) - Required - The entry to install.
- **options** (InstallOptions) - Required - Installation options.

### Returns
- **Result<InstallReport, DatabaseError>** - A report of the installation or an error.

### Example
```rust
let report = db.install(&entry, InstallOptions::default())?;
```
```

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

### pub fn install(&self, entry: &Entry, options: InstallOptions) -> Result<InstallReport, DatabaseError>

Source: https://docs.rs/terminfokit/latest/terminfokit/database/struct.DirectoryDatabase.html

Atomically installs an entry and optionally its aliases.

```APIDOC
## pub fn install(&self, entry: &Entry, options: InstallOptions) -> Result<InstallReport, DatabaseError>

### Description
Atomically installs an entry and optionally its aliases.

### Method
install

### Parameters
- **self** (&Self) - The database instance.
- **entry** (&Entry) - Required - The entry to install.
- **options** (InstallOptions) - Required - Installation options, including alias handling.

### Returns
- **Result<InstallReport, DatabaseError>** - An InstallReport on success, or a DatabaseError on failure.

```

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

### DirectoryDatabase install method

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Implements the install method for DirectoryDatabase, handling entry installation with alias support and atomic writes.

```rust
            .map_err(|error| DatabaseError::UnsupportedBackend(error.to_string()))?;
        let primary = entry.names().primary();
        validate_db_name(primary)?;
        let layout = resolved_layout(options.layout);
        let path = entry_path(&self.root, primary, layout);
        let parent = path
            .parent()
            .ok_or_else(|| DatabaseError::InvalidName(primary.to_string()))?;
        ensure_entry_directory(&self.root, parent)?;
        reject_symlink(&path)?;
        let changed = !fs::read(&path).is_ok_and(|current| current == bytes);
        if changed {
            atomic_write(&path, &bytes)?;
        }

        let mut installed_aliases = Vec::new();
        if options.aliases {
            for alias in entry.names().aliases() {
                validate_db_name(alias)?;
                let alias_path = entry_path(&self.root, alias, layout);
                if let Some(parent) = alias_path.parent() {
                    ensure_entry_directory(&self.root, parent)?;
                }
                let method = install_alias(&path, &alias_path, &bytes)?;
                installed_aliases.push(AliasInstall {
                    name: alias.to_string(),
                    path: alias_path,
                    method,
                });
            }
        }
        Ok(InstallReport {
            primary: path,
            aliases: installed_aliases,
            changed,
        })
    }
}
```

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

### Install aliases and return InstallReport

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html

Installs aliases for a terminfo entry when options.aliases is true. Validates each alias name, ensures the parent directory exists, and installs the alias via install_alias. Returns an InstallReport containing the primary path, installed aliases, and whether the primary file changed.

```rust
        let mut installed_aliases = Vec::new();
        if options.aliases {
            for alias in entry.names().aliases() {
                validate_db_name(alias)?;
                let alias_path = entry_path(&self.root, alias, layout);
                if let Some(parent) = alias_path.parent() {
                    ensure_entry_directory(&self.root, parent)?;
                }
                let method = install_alias(&path, &alias_path, &bytes)?;
                installed_aliases.push(AliasInstall {
                    name: alias.to_string(),
                    path: alias_path,
                    method,
                });
            }
        }
        Ok(InstallReport {
            primary: path,
            aliases: installed_aliases,
            changed,
        })
```

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

### AliasInstall Struct

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html

An installed alias and path.

```APIDOC
## AliasInstall

### Description
An installed alias and path.

### Methods
- `name(&self) -> &str` - Returns the alias name.
- `path(&self) -> &Path` - Returns the installed alias path.
- `method(&self) -> AliasMethod` - Returns how the alias was materialized.
```

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

### InstallOptions Struct

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html

Options controlling installation of a compiled entry.

```APIDOC
## InstallOptions

### Description
Options controlling installation of a compiled entry.

### Constructors
- `new() -> Self` - Creates options with automatic layout and alias installation.

### Methods
- `layout(self) -> DirectoryLayout` - Returns the requested directory layout.
- `aliases(self) -> bool` - Reports whether aliases will be installed.
- `encode_options(self) -> EncodeOptions` - Returns the options used to encode the installed entry.
- `with_layout(mut self, value: DirectoryLayout) -> Self` - Replaces the directory layout.
- `with_aliases(mut self, value: bool) -> Self` - Enables or disables alias installation.
- `with_encode_options(mut self, value: EncodeOptions) -> Self` - Replaces the options used to encode the installed entry.
```

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

### InstallOptions::layout

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns the requested directory layout for installation.

```APIDOC
## InstallOptions::layout

### Description
Returns the requested directory layout.

### Method
layout

### Signature
pub const fn layout(self) -> DirectoryLayout

### Parameters
None

### Returns
- **DirectoryLayout** - The directory layout configuration.

### Example
```rust
let layout = options.layout();
```
```

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

### Install terminfokit CLI

Source: https://docs.rs/terminfokit/latest/index.html

Installs the terminfokit CLI and its companion tools. The ncurses names are deliberately prefixed to avoid replacing system tools.

```bash
cargo install terminfokit-cli
```

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

### InstallOptions::new

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new InstallOptions instance with automatic layout and alias installation enabled.

```APIDOC
## InstallOptions::new

### Description
Creates options with automatic layout and alias installation.

### Method
new

### Signature
pub const fn new() -> Self

### Parameters
None

### Returns
- **Self** - A new InstallOptions instance with default settings.

### Example
```rust
let options = InstallOptions::new();
```
```

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

### Search report preserves priority and origin

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=std%3A%3Avec

Creates two directories with entries named 'priority' having different COLUMNS values, installs them, builds a SearchPath with both, loads a report, and asserts the path starts with the first directory, origin is Directory, and COLUMNS is 80.

```rust
        let suffix = TEMP_COUNTER.fetch_add(1, Ordering::Relaxed);
        let base = std::env::temp_dir().join(format!(
            "terminfokit-search-report-{}-{suffix}",
            std::process::id()
        ));
        let first = base.join("first");
        let second = base.join("second");
        let first_entry = EntryBuilder::new("priority")
            .unwrap()
            .number(crate::caps::NumericCap::COLUMNS, 80)
            .unwrap()
            .build();
        let second_entry = EntryBuilder::new("priority")
            .unwrap()
            .number(crate::caps::NumericCap::COLUMNS, 132)
            .unwrap()
            .build();
        DirectoryDatabase::new(&first)
            .install(&first_entry, InstallOptions::new())
            .unwrap();
        DirectoryDatabase::new(&second)
            .install(&second_entry, InstallOptions::new())
            .unwrap();
        let mut search = SearchPath::new();
        search.push(&first);
        search.push(&second);
        let report = search.load_report("priority").unwrap();
        assert!(report.path().unwrap().starts_with(&first));
        assert!(matches!(report.origin(), LoadOrigin::Directory { .. }));
        assert_eq!(
            report.entry().number(crate::caps::NumericCap::COLUMNS),
            crate::CapabilityState::Value(crate::Number::new(80).unwrap())
        );
        fs::remove_dir_all(base).unwrap();
```

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

### DirectoryDatabase::install

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Atomically installs an entry and optionally its aliases.

```APIDOC
## DirectoryDatabase::install

### Description
Atomically installs an entry and optionally its aliases.

### Method
`pub fn install(&self, entry: &Entry, options: InstallOptions) -> Result<InstallReport, DatabaseError>`

### Parameters
- **entry** (`&Entry`) - Required - The entry to install.
- **options** (`InstallOptions`) - Required - Installation options.

### Returns
- `Result<InstallReport, DatabaseError>` - The install report on success, or a database error.

### Errors
Returns `DatabaseError` if the installation fails.
```

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

### InstallOptions::with_aliases

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Enables or disables alias installation.

```APIDOC
## InstallOptions::with_aliases

### Description
Enables or disables alias installation.

### Method
with_aliases

### Signature
pub const fn with_aliases(mut self, value: bool) -> Self

### Parameters
- **value** (bool) - Required - Whether to enable alias installation.

### Returns
- **Self** - The updated InstallOptions instance.

### Example
```rust
let options = options.with_aliases(false);
```
```

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

### pub fn aliases(&self) -> &[AliasInstall]

Source: https://docs.rs/terminfokit/latest/terminfokit/database/struct.InstallReport.html

Returns installed alias records.

```APIDOC
## pub fn aliases(&self) -> &[AliasInstall]

### Description
Returns installed alias records.

### Method
aliases

### Signature
pub fn aliases(&self) -> &[AliasInstall]

### Parameters
- **self** (&self) - The InstallReport instance.

### Returns
- **&[AliasInstall]** - A slice of installed alias records.
```

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

### InstallOptions::aliases

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Reports whether aliases will be installed.

```APIDOC
## InstallOptions::aliases

### Description
Reports whether aliases will be installed.

### Method
aliases

### Signature
pub const fn aliases(self) -> bool

### Parameters
None

### Returns
- **bool** - True if aliases will be installed, false otherwise.

### Example
```rust
let will_install_aliases = options.aliases();
```
```

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

### InstallReport Struct

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html

Result of installing a primary entry and its aliases.

```APIDOC
## InstallReport

### Description
Result of installing a primary entry and its aliases.

### Methods
- `primary(&self) -> &Path` - Returns the primary compiled-entry path.
- `aliases(&self) -> &[AliasInstall]` - Returns installed alias records.
- `changed(&self) -> bool` - Reports whether the primary file's bytes changed.
```

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

### AliasInstall::path

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns the installed alias path.

```APIDOC
## AliasInstall::path

### Description
Returns the installed alias path.

### Method
path

### Signature
pub fn path(&self) -> &Path

### Parameters
None

### Returns
- **&Path** - The path to the installed alias.

### Example
```rust
let path = alias_install.path();
```
```

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

### default_install_root

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=std%3A%3Avec

Returns the default writable per-user installation root, when available. Checks TERMINFO and HOME environment variables.

```APIDOC
## default_install_root

### Description
Returns the default writable per-user installation root, when available. Checks TERMINFO and HOME environment variables.

### Method
Free function

### Signature
pub fn default_install_root() -> Option<PathBuf>

### Parameters
None

### Return Value
- **Option<PathBuf>** - The default installation root path, or None if not available.
```

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

### pub fn default_install_root() -> Option<PathBuf>

Source: https://docs.rs/terminfokit/latest/terminfokit/database/fn.default_install_root.html

Returns the default writable per-user installation root, when available. This function is part of the `terminfokit::database` module and is intended for use by applications that need to determine the default installation directory for user-level data.

```APIDOC
## Function: default_install_root

### Description
Returns the default writable per-user installation root, when available.

### Signature
```rust
pub fn default_install_root() -> Option<PathBuf>
```

### Parameters
None.

### Return Value
- **Option<PathBuf>** - The default writable per-user installation root, or `None` if not available.

### Example
```rust
use terminfokit::database::default_install_root;

if let Some(root) = default_install_root() {
    println!("Default install root: {:?}", root);
} else {
    println!("No default install root available.");
}
```
```

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

### default_install_root

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns the default writable per-user installation root, when available.

```APIDOC
## default_install_root

### Description
Returns the default writable per-user installation root, when available.

### Method
Rust function

### Endpoint
`pub fn default_install_root() -> Option<PathBuf>`

### Parameters
None

### Returns
- **Option<PathBuf>** - The default installation root path, or None if not available.

### Example
```rust
if let Some(root) = default_install_root() {
    println!("Install root: {}", root.display());
}
```
```

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

### InstallReport::aliases

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns installed alias records.

```APIDOC
## InstallReport::aliases

### Description
Returns installed alias records.

### Method
aliases

### Signature
pub fn aliases(&self) -> &[AliasInstall]

### Parameters
None

### Returns
- **&[AliasInstall]** - A slice of installed alias records.

### Example
```rust
let aliases = report.aliases();
```
```

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

### InstallOptions::encode_options

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns the options used to encode the installed entry.

```APIDOC
## InstallOptions::encode_options

### Description
Returns the options used to encode the installed entry.

### Method
encode_options

### Signature
pub const fn encode_options(self) -> EncodeOptions

### Parameters
None

### Returns
- **EncodeOptions** - The encoding options.

### Example
```rust
let encode_opts = options.encode_options();
```
```

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

### Test: install portable entry with alias and verify load

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a temporary directory, installs a portable entry with an alias twice, then asserts that loading either name returns the primary name 'portable'. Also verifies that a path traversal name like '../portable' is rejected with DatabaseError::InvalidName. Cleans up the temporary directory afterward.

```rust
        std::process::id(),
        TEMP_COUNTER.fetch_add(1, Ordering::Relaxed)
    ));
    let entry = EntryBuilder::new("portable")
        .unwrap()
        .alias("portable-alias")
        .unwrap()
        .build();
    let database = DirectoryDatabase::new(&root);
    database
        .install(
            &entry,
            InstallOptions::new().with_layout(DirectoryLayout::Hex),
        )
        .unwrap();
    database
        .install(
            &entry,
            InstallOptions::new().with_layout(DirectoryLayout::Hex),
        )
        .unwrap();
    assert_eq!(
        database.load("portable").unwrap().names().primary(),
        "portable"
    );
    assert_eq!(
        database.load("portable-alias").unwrap().names().primary(),
        "portable"
    );
    assert!(matches!(
        database.load("../portable"),
        Err(DatabaseError::InvalidName(_))
    ));
    fs::remove_dir_all(root).unwrap();
}
```

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

### InstallOptions::with_encode_options

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Replaces the options used to encode the installed entry.

```APIDOC
## InstallOptions::with_encode_options

### Description
Replaces the options used to encode the installed entry.

### Method
with_encode_options

### Signature
pub const fn with_encode_options(mut self, value: EncodeOptions) -> Self

### Parameters
- **value** (EncodeOptions) - Required - The new encoding options.

### Returns
- **Self** - The updated InstallOptions instance.

### Example
```rust
let options = options.with_encode_options(new_encode_options);
```
```

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

### Implement EntryProvider for DirectoryDatabase

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html

Implements EntryProvider for DirectoryDatabase. get returns Some(entry) on success, None when the entry is not found, and a ProviderError for other errors.

```rust
impl EntryProvider for DirectoryDatabase {
    fn get(&self, name: &str) -> Result<Option<Entry>, ProviderError> {
        match self.load(name) {
            Ok(entry) => Ok(Some(entry)),
            Err(DatabaseError::NotFound(_)) => Ok(None),
            Err(error) => Err(ProviderError::new(error.to_string())),
        }
    }
}
```

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

### pub fn path(&self) -> &Path

Source: https://docs.rs/terminfokit/latest/terminfokit/database/struct.AliasInstall.html

Returns the installed alias path as a reference to a Path.

```APIDOC
## pub fn path(&self) -> &Path

### Description
Returns the installed alias path.

### Method
`pub fn path(&self) -> &Path`

### Parameters
- `self` (reference) - The AliasInstall instance.

### Returns
- `&Path` - The installed alias path.

```

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

### pub fn builder(primary: impl Into<String>) -> Result<EntryBuilder, BuildError>

Source: https://docs.rs/terminfokit/latest/terminfokit/model/struct.Entry.html

Starts checked construction with a primary name.

```APIDOC
## builder

### Method
`pub fn builder(primary: impl Into<String>) -> Result<EntryBuilder, BuildError>`

### Description
Starts checked construction with a primary name.

### Parameters
- `primary`: `impl Into<String>` - The primary name for the entry.

### Returns
`Result<EntryBuilder, BuildError>` - A builder for constructing the entry.
```

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

### AliasInstall::method

Source: https://docs.rs/terminfokit/latest/terminfokit/database/struct.AliasInstall.html?search=std%3A%3Avec

Returns how the alias was materialized as an AliasMethod.

```APIDOC
## AliasInstall::method

### Description
Returns how the alias was materialized.

### Method
`pub const fn method(&self) -> AliasMethod`

### Parameters
None.

### Returns
- `AliasMethod` - The method used to materialize the alias.

```

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

### AliasInstall::method

Source: https://docs.rs/terminfokit/latest/terminfokit/database/struct.AliasInstall.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns how the alias was materialized as an AliasMethod.

```APIDOC
## AliasInstall::method

### Description
Returns how the alias was materialized.

### Method
pub const fn method(&self) -> AliasMethod

### Parameters
- **self** (&AliasInstall) - The AliasInstall instance.

### Returns
- **AliasMethod** - The method used to materialize the alias.

```

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

### Directory install test

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Unit test for directory installation that loads hex and alias entries and rejects path traversal. The test body is not shown in the source.

```rust
#[test]
    fn directory_install_loads_hex_and_alias_and_rejects_traversal() {
        let root = std::env::temp_dir().join(format!(
            "terminfokit-database-{}-{}",
```

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

### AliasInstall::method

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns how the alias was materialized.

```APIDOC
## AliasInstall::method

### Description
Returns how the alias was materialized.

### Method
method

### Signature
pub const fn method(&self) -> AliasMethod

### Parameters
None

### Returns
- **AliasMethod** - The method used to create the alias.

### Example
```rust
let method = alias_install.method();
```
```

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

### Rust test: installation_rejects_symlinked_entry_directories

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=u32+-%3E+bool

Test that verifies installation rejects symlinked entry directories. It creates a symlink to an outside directory and expects an UntrustedSymlink error when installing an entry.

```rust
    #[cfg(unix)]
    #[test]
    fn installation_rejects_symlinked_entry_directories() {
        use std::os::unix::fs::symlink;

        let suffix = TEMP_COUNTER.fetch_add(1, Ordering::Relaxed);
        let root = std::env::temp_dir().join(format!(
            "terminfokit-database-symlink-{}-{suffix}",
            std::process::id()
        ));
        let outside = std::env::temp_dir().join(format!(
            "terminfokit-database-outside-{}-{suffix}",
            std::process::id()
        ));
        fs::create_dir_all(&root).unwrap();
        fs::create_dir_all(&outside).unwrap();
        symlink(&outside, root.join("p")).unwrap();

        let entry = EntryBuilder::new("portable").unwrap().build();
        let error = DirectoryDatabase::new(&root)
            .install(
                &entry,
                InstallOptions::new().with_layout(DirectoryLayout::Letter),
            )
            .unwrap_err();
        assert!(matches!(error, DatabaseError::UntrustedSymlink(_)));

        fs::remove_dir_all(root).unwrap();
        fs::remove_dir_all(outside).unwrap();
    }
```

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

### Installation rejects symlinked entry directories

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=std%3A%3Avec

On Unix, creates a symlink pointing outside the database root, attempts to install an entry with DirectoryLayout::Letter, and asserts the error is DatabaseError::UntrustedSymlink.

```rust
        use std::os::unix::fs::symlink;

        let suffix = TEMP_COUNTER.fetch_add(1, Ordering::Relaxed);
        let root = std::env::temp_dir().join(format!(
            "terminfokit-database-symlink-{}-{suffix}",
            std::process::id()
        ));
        let outside = std::env::temp_dir().join(format!(
            "terminfokit-database-outside-{}-{suffix}",
            std::process::id()
        ));
        fs::create_dir_all(&root).unwrap();
        fs::create_dir_all(&outside).unwrap();
        symlink(&outside, root.join("p")).unwrap();

        let entry = EntryBuilder::new("portable").unwrap().build();
        let error = DirectoryDatabase::new(&root)
            .install(
                &entry,
                InstallOptions::new().with_layout(DirectoryLayout::Letter),
            )
            .unwrap_err();
        assert!(matches!(error, DatabaseError::UntrustedSymlink(_)));

        fs::remove_dir_all(root).unwrap();
        fs::remove_dir_all(outside).unwrap();
```

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

### finish_record: Build LogicalRecord from text and segments

Source: https://docs.rs/terminfokit/latest/src/terminfokit/source.rs.html?search=

Constructs a LogicalRecord by computing the physical span from the first and last segments. Uses the start of the first segment and the end of the last segment, falling back to the start if no segments exist.

```rust
fn finish_record(
    text: Vec<u8>,
    segments: Vec<LogicalSegment>,
    source_id: SourceId,
) -> LogicalRecord {
    let start = segments
        .first()
        .map_or(0, |segment| segment.physical.start());
    let end = segments
        .last()
        .map_or(start, |segment| segment.physical.end());
    LogicalRecord {
        text,
        span: Span::new(source_id, TextRange::new(start, end)),
        segments,
    }
}
```

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

### SearchPath::from_env

Source: https://docs.rs/terminfokit/latest/terminfokit/database/struct.SearchPath.html?search=

Constructs the ncurses-style directory order from the environment.

```APIDOC
## SearchPath::from_env

### Description
Constructs the ncurses-style directory order from the environment.

### Method
from_env

### Signature
pub fn from_env() -> Self

### Parameters
None

### Returns
Self - A SearchPath constructed from environment variables.

```

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

### edit

Source: https://docs.rs/terminfokit/latest/terminfokit/source/struct.SourceDocument.html

Starts a lossless token editor.

```APIDOC
## edit

### Description
Starts a lossless token editor.

### Method
pub fn edit(&mut self) -> SourceEditor<'_>

### Parameters
None

### Returns
- **SourceEditor<'_>** - A lossless token editor.

### Example
```rust
let mut editor = doc.edit();
```
```

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

### InstallReport::primary

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns the primary compiled-entry path.

```APIDOC
## InstallReport::primary

### Description
Returns the primary compiled-entry path.

### Method
primary

### Signature
pub fn primary(&self) -> &Path

### Parameters
None

### Returns
- **&Path** - The path to the primary compiled entry.

### Example
```rust
let primary_path = report.primary();
```
```

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

### pub const fn ncurses_6_6() -> Self

Source: https://docs.rs/terminfokit/latest/terminfokit/termcap/struct.ConvertOptions.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates the ncurses 6.6 compatibility profile.

```APIDOC
## pub const fn ncurses_6_6() -> Self

### Description
Creates the ncurses 6.6 compatibility profile.

### Method
Constructor

### Parameters
None

### Returns
- **Self** - A new ConvertOptions instance configured for ncurses 6.6 compatibility.

### Example
```rust
let options = ConvertOptions::ncurses_6_6();
```
```

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

### pub fn capabilities(&self) -> &[SourceCapability]

Source: https://docs.rs/terminfokit/latest/terminfokit/source/struct.SourceEntry.html

Returns parsed capability tokens in source order.

```APIDOC
## pub fn capabilities(&self) -> &[SourceCapability]

### Description
Returns parsed capability tokens in source order.

### Method
N/A (Rust method)

### Endpoint
N/A

### Parameters
None

### Returns
- **&[SourceCapability]** - A slice of capability tokens.

### Example
```rust
let entry = SourceEntry::new(); // hypothetical
let caps = entry.capabilities();
```
```

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

### builder

Source: https://docs.rs/terminfokit/latest/terminfokit/model/struct.Entry.html?search=

Starts checked construction with a primary name.

```APIDOC
## builder

### Description
Starts checked construction with a primary name.

### Method
pub fn builder(primary: impl Into<String>) -> Result<EntryBuilder, BuildError>

### Parameters
- **primary** (impl Into<String>) - The primary name for the entry.

### Returns
- **Result<EntryBuilder, BuildError>** - A builder for constructing an Entry, or a build error.
```

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

### InstallOptions::with_layout

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Replaces the directory layout with the provided value.

```APIDOC
## InstallOptions::with_layout

### Description
Replaces the directory layout.

### Method
with_layout

### Signature
pub const fn with_layout(mut self, value: DirectoryLayout) -> Self

### Parameters
- **value** (DirectoryLayout) - Required - The new directory layout.

### Returns
- **Self** - The updated InstallOptions instance.

### Example
```rust
let options = options.with_layout(DirectoryLayout::Hex);
```
```

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

### SourceDocument::edit

Source: https://docs.rs/terminfokit/latest/src/terminfokit/source.rs.html?search=

Starts a lossless token editor.

```APIDOC
## SourceDocument::edit

### Description
Starts a lossless token editor.

### Method
fn edit(&mut self) -> SourceEditor<'_>

### Parameters
None

### Returns
- **SourceEditor<'_>** - A token editor for this document.
```

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

### Entry::extended

Source: https://docs.rs/terminfokit/latest/src/terminfokit/model.rs.html?search=

Returns user-defined capabilities in binary order.

```APIDOC
## Entry::extended

### Description
Returns user-defined capabilities in binary order.

### Method
Entry::extended

### Parameters
- **&self** - The entry instance.

### Returns
- **&[ExtendedCapability]** - A slice of extended capabilities.

### Example
```rust
let extended = entry.extended();
```
```

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

### get

Source: https://docs.rs/terminfokit/latest/terminfokit/resolve/struct.Resolution.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Finds a resolved primary name or alias.

```APIDOC
## get

### Description
Finds a resolved primary name or alias.

### Method
get

### Parameters
- **name** (&str) - Required - The name to look up.

### Returns
- **Option<&Entry>** - The entry associated with the name, or `None` if not found.

### Example
```rust
let resolution: Resolution = /* ... */;
if let Some(entry) = resolution.get("name") {
    // use entry
}
```
```

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

### get

Source: https://docs.rs/terminfokit/latest/terminfokit/resolve/struct.Resolution.html

Finds a resolved primary name or alias.

```APIDOC
## get

### Description
Finds a resolved primary name or alias.

### Method
N/A (Rust method)

### Signature
```rust
pub fn get(&self, name: &str) -> Option<&Entry>
```

### Parameters
- **name** (&str) - Required - The name to look up.

### Returns
- **Option<&Entry>** - The entry associated with the given name, or `None` if not found.

```

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

### pub const fn introduced(&self) -> CapabilityVersion

Source: https://docs.rs/terminfokit/latest/terminfokit/caps/struct.CapabilityMetadata.html

Returns the capability's vocabulary version.

```APIDOC
## Method: introduced

### Description
Returns the capability’s vocabulary version.

### Signature
```rust
pub const fn introduced(&self) -> CapabilityVersion
```

### Parameters
None.

### Returns
- **CapabilityVersion** - The vocabulary version in which the capability was introduced.

### Example
```rust
let metadata: CapabilityMetadata = /* ... */;
let version: CapabilityVersion = metadata.introduced();
```
```

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

### pub fn new(root: impl Into<PathBuf>) -> Self

Source: https://docs.rs/terminfokit/latest/terminfokit/database/struct.DirectoryDatabase.html

Creates a new DirectoryDatabase rooted at the specified directory path.

```APIDOC
## pub fn new(root: impl Into<PathBuf>) -> Self

### Description
Creates a new DirectoryDatabase rooted at the supplied directory.

### Method
new

### Parameters
- **root** (impl Into<PathBuf>) - Required - The root directory path for the database.

### Returns
- **Self** - A new DirectoryDatabase instance.

```

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

### TextRange::start

Source: https://docs.rs/terminfokit/latest/src/terminfokit/error.rs.html

Returns the inclusive start byte offset.

```APIDOC
## TextRange::start

### Description
Returns the inclusive start byte offset.

### Method
`pub const fn start(self) -> usize`

### Parameters
- **self** - The TextRange instance.

### Returns
- **usize** - The start offset.

### Example
```rust
let range = TextRange::new(0, 10);
let start = range.start(); // 0
```
```

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

### AliasInstall Methods

Source: https://docs.rs/terminfokit/latest/terminfokit/database/struct.AliasInstall.html?search=u32+-%3E+bool

Methods to access the properties of an AliasInstall instance.

```APIDOC
## AliasInstall Methods

### Description
Methods to retrieve the alias name, path, and materialization method from an AliasInstall instance.

### Methods

#### name
- **Signature**: `pub fn name(&self) -> &str`
- **Description**: Returns the alias name.

#### path
- **Signature**: `pub fn path(&self) -> &Path`
- **Description**: Returns the installed alias path.

#### method
- **Signature**: `pub const fn method(&self) -> AliasMethod`
- **Description**: Returns how the alias was materialized.

```

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

### Install entry with Hex layout and verify alias and invalid name

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=std%3A%3Avec

Creates a temporary directory, builds an entry with alias 'portable-alias', installs it twice with DirectoryLayout::Hex, then verifies loading by primary name and alias, and that loading '../portable' returns DatabaseError::InvalidName.

```rust
        let suffix = TEMP_COUNTER.fetch_add(1, Ordering::Relaxed);
        let root = std::env::temp_dir().join(format!(
            "terminfokit-database-{}-{suffix}",
            std::process::id()
        ));
        let entry = EntryBuilder::new("portable")
            .unwrap()
            .alias("portable-alias")
            .unwrap()
            .build();
        let database = DirectoryDatabase::new(&root);
        database
            .install(
                &entry,
                InstallOptions::new().with_layout(DirectoryLayout::Hex),
            )
            .unwrap();
        database
            .install(
                &entry,
                InstallOptions::new().with_layout(DirectoryLayout::Hex),
            )
            .unwrap();
        assert_eq!(
            database.load("portable").unwrap().names().primary(),
            "portable"
        );
        assert_eq!(
            database.load("portable-alias").unwrap().names().primary(),
            "portable"
        );
        assert!(matches!(
            database.load("../portable"),
            Err(DatabaseError::InvalidName(_))
        ));
        fs::remove_dir_all(root).unwrap();
```

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

### Tests for transport round-trip and directory install

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html

Unit tests for transport encoding and directory installation. transport_round_trip verifies hex and base64 round-trips and rejects invalid base64 inputs; directory_install_loads_hex_and_alias_and_rejects_traversal is incomplete in the source and tests loading hex and alias entries while rejecting path traversal.

```rust
#[cfg(test)]
mod tests {
    use super::*;
    use crate::model::EntryBuilder;

    #[test]
    fn transport_round_trip() {
        let entry = EntryBuilder::new("portable").unwrap().build();
        let bytes = entry.to_bytes().unwrap();
        assert_eq!(decode_hex(&encode_hex(&bytes)).unwrap(), bytes);
        assert_eq!(decode_base64(&encode_base64(&bytes)).unwrap(), bytes);
        assert_eq!(decode_base64("AA==").unwrap(), [0]);
        assert_eq!(decode_base64("AAA=").unwrap(), [0, 0]);
        for invalid in ["AA==AAAA", "AB==", "AAB=", "AA=A"] {
            assert!(
                decode_base64(invalid).is_err(),
                "{invalid:?} must be rejected"
            );
        }
    }

    #[test]
    fn directory_install_loads_hex_and_alias_and_rejects_traversal() {
        let root = std::env::temp_dir().join(format!(
            "terminfokit-database-{}-{}",
```

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

### Use terminfokit CLI commands

Source: https://docs.rs/terminfokit/latest/index.html

Shows basic usage of the terminfokit CLI and its companion tools.

```bash
terminfokit --help
terminfokit doctor
tik-tput colors
```

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

### pub const fn bsd() -> Self

Source: https://docs.rs/terminfokit/latest/terminfokit/termcap/struct.ConvertOptions.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates the conservative BSD compatibility profile.

```APIDOC
## pub const fn bsd() -> Self

### Description
Creates the conservative BSD compatibility profile.

### Method
Constructor

### Parameters
None

### Returns
- **Self** - A new ConvertOptions instance configured for BSD compatibility.

### Example
```rust
let options = ConvertOptions::bsd();
```
```

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

### Compiler::new

Source: https://docs.rs/terminfokit/latest/src/terminfokit/resolve.rs.html?search=

Creates a compiler with no external provider.

```APIDOC
## Compiler::new

### Description
Creates a compiler with no external provider.

### Method
new

### Parameters
None

### Returns
- `Compiler<'a>` - The new compiler.

```

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

### DirectoryDatabase::new

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a database rooted at the supplied directory.

```APIDOC
## DirectoryDatabase::new

### Description
Creates a database rooted at the supplied directory.

### Method
`pub fn new(root: impl Into<PathBuf>) -> Self`

### Parameters
- **root** (`impl Into<PathBuf>`) - Required - The root directory for the database.

### Returns
- `Self` - A new `DirectoryDatabase` instance.

### Errors
This method does not return errors.
```

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

### EntryProvider for SearchPath

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=std%3A%3Avec

Implements the EntryProvider trait for SearchPath, providing a get method that returns Option<Entry>.

```APIDOC
## EntryProvider for SearchPath

### Description
Implements the EntryProvider trait for SearchPath, providing a get method that returns Option<Entry>.

### Method
Trait implementation

### Signature
fn get(&self, name: &str) -> Result<Option<Entry>, ProviderError>

### Parameters
- **name** (string) - Required - The name of the terminfo entry to retrieve.

### Return Value
- **Result<Option<Entry>, ProviderError>** - Ok(Some(entry)) if found, Ok(None) if not found, or Err(ProviderError) on other errors.
```

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

### AliasInstall::name

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns the alias name.

```APIDOC
## AliasInstall::name

### Description
Returns the alias name.

### Method
name

### Signature
pub fn name(&self) -> &str

### Parameters
None

### Returns
- **&str** - The alias name.

### Example
```rust
let name = alias_install.name();
```
```

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

### Entry::builder

Source: https://docs.rs/terminfokit/latest/src/terminfokit/model.rs.html?search=

Starts checked construction of an Entry with a primary name. Returns an EntryBuilder or a BuildError if the name is invalid.

```APIDOC
## Entry::builder

### Description
Starts checked construction of an Entry with a primary name. Returns an EntryBuilder or a BuildError if the name is invalid.

### Method
Entry::builder

### Parameters
- **primary** (impl Into<String>) - Required - The primary name for the entry.

### Returns
- **Result<EntryBuilder, BuildError>** - A builder for constructing an Entry, or an error if the name is invalid.

### Example
```rust
let builder = Entry::builder("xterm")?;
```
```

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

### ALL

Source: https://docs.rs/terminfokit/latest/src/terminfokit/opt/rustwide/target/x86_64-unknown-linux-gnu/debug/build/terminfokit-3a3e3cf65aab75d1/out/caps_generated.rs.html?search=u32+-%3E+bool

Array of all capability identifiers in binary-slot order.

```APIDOC
## Constant: ALL

### Description
Provides a complete list of all capability identifiers in binary-slot order.

### Type
`&'static [Self]`

### Usage
Use this constant to iterate over all available capability identifiers.
```

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

### pub fn get(&self, name: &str) -> Option<&Entry>

Source: https://docs.rs/terminfokit/latest/terminfokit/resolve/struct.Resolution.html?search=std%3A%3Avec

Finds a resolved primary name or alias.

```APIDOC
## pub fn get(&self, name: &str) -> Option<&Entry>

### Description
Finds a resolved primary name or alias.

### Method
pub fn

### Signature
pub fn get(&self, name: &str) -> Option<&Entry>

### Parameters
- **name** (&str) - Required - The primary name or alias to look up.

### Returns
- **Option<&Entry>** - The entry associated with the given name, or None if not found.
```

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

### Test formatted source parses again

Source: https://docs.rs/terminfokit/latest/src/terminfokit/format.rs.html?search=

Builds a demo entry, formats it with SourceFormatter, and asserts the formatted text parses back successfully.

```rust
#[test]
fn formatted_source_parses_again() {
    let entry = EntryBuilder::new("demo")
        .unwrap()
        .description("demo terminal")
        .unwrap()
        .string(StringCap::CLEAR_SCREEN, b"\x1b[H,\".to_vec())
        .unwrap()
        .build();
    let text = SourceFormatter::default().format(&entry);
    assert!(crate::source::parse(text.as_bytes()).is_ok(), "{text}");
}
```

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

### trait EntryProvider

Source: https://docs.rs/terminfokit/latest/terminfokit/resolve/trait.EntryProvider.html?search=

Defines the EntryProvider trait with a required get method to retrieve a resolved entry by name or alias.

```APIDOC
## Trait EntryProvider

### Description
Supplies already-resolved entries referenced outside the input source.

### Definition
```rust
pub trait EntryProvider {
    // Required method
    fn get(&self, name: &str) -> Result<Option<Entry>, ProviderError>;
}
```

### Required Methods

#### `fn get(&self, name: &str) -> Result<Option<Entry>, ProviderError>`
Retrieves a resolved entry by primary name or alias.

### Dyn Compatibility
This trait **is** dyn compatible.

### Implementations on Foreign Types

#### `impl EntryProvider for ()`

##### `fn get(&self, _name: &str) -> Result<Option<Entry>, ProviderError>`

### Implementors

- `impl EntryProvider for DirectoryDatabase`
- `impl EntryProvider for SearchPath`
```

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

### pub fn get(&self, name: &str) -> Option<&CompiledEntry>

Source: https://docs.rs/terminfokit/latest/terminfokit/resolve/struct.Compilation.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Finds a compiled primary name or alias.

```APIDOC
## pub fn get(&self, name: &str) -> Option<&CompiledEntry>

### Description
Finds a compiled primary name or alias.

### Method
pub fn get(&self, name: &str) -> Option<&CompiledEntry>

### Parameters
- **name** (&str) - Required - The primary name or alias to look up.

### Returns
- **Option<&CompiledEntry>** - The compiled entry if found, otherwise None.
```

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

### EntryBuilder::new

Source: https://docs.rs/terminfokit/latest/src/terminfokit/model.rs.html?search=

Starts a new entry with a validated primary name. Returns a Result with the builder or a BuildError if the name is invalid.

```APIDOC
## EntryBuilder::new

### Description
Starts an entry with a validated primary name.

### Method
Constructor

### Signature
```rust
pub fn new(primary: impl Into<String>) -> Result<Self, BuildError>
```

### Parameters
- **primary** (impl Into<String>) - Required - The primary name for the entry.

### Returns
- **Result<Self, BuildError>** - The builder instance on success, or a BuildError if validation fails.

```

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

### pub fn format(&self, formatter: &SourceFormatter) -> String

Source: https://docs.rs/terminfokit/latest/terminfokit/format/struct.RelativeEntry.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Renders overrides followed by ordered use fields.

```APIDOC
## pub fn format(&self, formatter: &SourceFormatter) -> String

### Description
Renders overrides followed by ordered use fields.

### Method
N/A (Rust method)

### Parameters
- **formatter** (&SourceFormatter) - Required - The formatter used for rendering.

### Returns
- **String** - The formatted string.
```

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

### trait EntryProvider

Source: https://docs.rs/terminfokit/latest/terminfokit/resolve/trait.EntryProvider.html?search=std%3A%3Avec

Defines the EntryProvider trait with a required method `get` that retrieves a resolved entry by primary name or alias.

```APIDOC
## Trait EntryProvider

### Description
Supplies already-resolved entries referenced outside the input source.

### Definition
```rust
pub trait EntryProvider {
    // Required method
    fn get(&self, name: &str) -> Result<Option<Entry>, ProviderError>;
}
```

### Required Methods

#### `get`

```rust
fn get(&self, name: &str) -> Result<Option<Entry>, ProviderError>
```

Retrieves a resolved entry by primary name or alias.

### Dyn Compatibility
This trait **is** dyn compatible.

### Implementations on Foreign Types

#### `impl EntryProvider for ()`

```rust
fn get(&self, _name: &str) -> Result<Option<Entry>, ProviderError>
```

### Implementors
- `impl EntryProvider for DirectoryDatabase`
- `impl EntryProvider for SearchPath`
```

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

### Implement DatabaseBackend for DirectoryDatabase

Source: https://docs.rs/terminfokit/latest/src/terminfokit/database.rs.html

Implements DatabaseBackend for DirectoryDatabase. load_report delegates to the inherent method. names scans the root directory for subdirectories and files, skipping symlinks and non-files, validates each name, deduplicates, and returns sorted names.

```rust
impl DatabaseBackend for DirectoryDatabase {
    fn load_report(&self, name: &str) -> Result<LoadReport, DatabaseError> {
        DirectoryDatabase::load_report(self, name)
    }

    fn names(&self) -> Result<Vec<String>, DatabaseError> {
        let mut names = Vec::new();
        if !self.root.exists() {
            return Ok(names);
        }
        for directory in fs::read_dir(&self.root)? {
            let directory = directory?;
            if directory.file_type()?.is_symlink() || !directory.file_type()?.is_dir() {
                continue;
            }
            for item in fs::read_dir(directory.path())? {
                let item = item?;
                if item.file_type()?.is_symlink() || !item.file_type()?.is_file() {
                    continue;
                }
                if let Some(name) = item.file_name().to_str()
                    && validate_db_name(name).is_ok()
                    && !names.iter().any(|candidate| candidate == name)
                {
                    names.push(name.to_string());
                }
            }
        }
        names.sort();
        Ok(names)
    }
}
```

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

### layout

Source: https://docs.rs/terminfokit/latest/terminfokit/database/struct.LoadReport.html?search=u32+-%3E+bool

Returns the matched layout for a directory load.

```APIDOC
## layout

### Description
Returns the matched layout for a directory load.

### Method
layout

### Signature
pub const fn layout(&self) -> Option<DirectoryLayout>

### Parameters
None

### Returns
- **Option<DirectoryLayout>** - The matched layout, if any.
```
Tokens:
Raw