packkit - v0.1.0

packkit/entry

Types

Entry

opaque </>

Opaque logical archive entry.

pub opaque type Entry

EntryError

</>

Why a checked entry or path constructor rejected the input.

pub type EntryError {
  EmptyPath
  AbsolutePath(value: String)
  PathTraversal(value: String)
  WindowsPath(value: String)
  EmptySegment(value: String)
  DotSegment(value: String)
  ContainsNul(value: String)
}

Constructors 

  • EmptyPath
  • AbsolutePath(value: String)
  • PathTraversal(value: String)
  • WindowsPath(value: String)
  • EmptySegment(value: String)
  • DotSegment(value: String)
  • ContainsNul(value: String)

EntryKind

</>

Pattern-matchable tag identifying the kind of an Entry. The Entry itself stays opaque; this transparent enum replaces the previous stringly-typed kind so callers and encoders get compile-time exhaustiveness instead of “did I spell that right?”.

pub type EntryKind {
  File
  Directory
  Symlink
  Hardlink
}

Constructors 

  • File
  • Directory
  • Symlink
  • Hardlink

EntryPath

opaque </>

Validated relative archive path safe to carry as an entry name.

pub opaque type EntryPath

Metadata

opaque </>

Common metadata carried by archive entries.

pub opaque type Metadata

MetadataError

</>

Why a checked metadata setter rejected the input. Distinct from the path-validation EntryError so callers can pattern-match on the numeric-field cases without conflating them.

pub type MetadataError {
  ModeOutOfRange(value: Int)
  OwnerOutOfRange(value: Int)
  ModifiedAtOutOfRange(value: Int)
}

Constructors 

  • ModeOutOfRange(value: Int)

    mode must fit in 16 unsigned bits (the widest field shape any of our archive families serialise it through).

  • OwnerOutOfRange(value: Int)

    uid / gid must be non-negative. Maximum is 2^32-1 (the widest format-side cap, cpio newc).

  • ModifiedAtOutOfRange(value: Int)

    modified_at_unix must be non-negative. Maximum is 2^32-1 (32-bit gzip / cpio newc cap); larger timestamps are rejected here rather than silently corrupted at encode time.

Values

body

</> 
pub fn body(entry: Entry) -> BitArray

Read the raw byte body for file-like entries.

depth

</> 
pub fn depth(path: EntryPath) -> Int

Number of segments in the path.

directory

</> 
pub fn directory(path path: String) -> Entry

Panicking counterpart of directory_checked.

directory_checked

</> 
pub fn directory_checked(
  path path: String,
) -> Result(Entry, EntryError)

Build a directory entry after path validation.

file

</> 
pub fn file(path path: String, body body: BitArray) -> Entry

Panicking counterpart of file_checked.

file_checked

</> 
pub fn file_checked(
  path path: String,
  body body: BitArray,
) -> Result(Entry, EntryError)

Build a regular file entry after path validation.

group_id

</> 
pub fn group_id(metadata: Metadata) -> Int

Group identifier stored in metadata.

</> 
pub fn hardlink(
  path path: String,
  target target: String,
) -> Entry

Panicking counterpart of hardlink_checked.

</> 
pub fn hardlink_checked(
  path path: String,
  target target: String,
) -> Result(Entry, EntryError)

Build a hard-link entry. The entry path is strictly validated. The link target is preserved as metadata but must not contain NUL.

is_directory

</> 
pub fn is_directory(entry: Entry) -> Bool

Short-circuit predicate for kind(entry) == Directory.

is_file

</> 
pub fn is_file(entry: Entry) -> Bool

Short-circuit predicate for kind(entry) == File. Saves callers from importing EntryKind just to filter a list of entries.

</> 
pub fn is_hardlink(entry: Entry) -> Bool

Short-circuit predicate for kind(entry) == Hardlink.

</> 
pub fn is_symlink(entry: Entry) -> Bool

Short-circuit predicate for kind(entry) == Symlink.

kind

</> 
pub fn kind(entry: Entry) -> EntryKind

Read the logical entry kind.

</> 
pub fn link_target(entry: Entry) -> option.Option(String)

Read the optional link target.

metadata

</> 
pub fn metadata(entry: Entry) -> Metadata

Read the metadata bundle.

mode

</> 
pub fn mode(metadata: Metadata) -> Int

File mode stored in metadata.

modified_at_unix

</> 
pub fn modified_at_unix(metadata: Metadata) -> Int

Last-modified Unix timestamp stored in metadata.

path

</> 
pub fn path(entry: Entry) -> EntryPath

Read the validated entry path.

path_checked

</> 
pub fn path_checked(
  value: String,
) -> Result(EntryPath, EntryError)

Validate a relative archive path.

path_unchecked

</> 
pub fn path_unchecked(value: String) -> EntryPath

Panicking counterpart of path_checked. The getter on Entry claims the short name; this constructor takes the explicit suffix.

</> 
pub fn symlink(path path: String, target target: String) -> Entry

Panicking counterpart of symlink_checked.

</> 
pub fn symlink_checked(
  path path: String,
  target target: String,
) -> Result(Entry, EntryError)

Build a symbolic-link entry. The entry path is strictly validated. The link target is preserved as metadata but must not contain NUL.

to_string

</> 
pub fn to_string(path: EntryPath) -> String

Convert an EntryPath back to its canonical string form.

user_id

</> 
pub fn user_id(metadata: Metadata) -> Int

User identifier stored in metadata.

with_mode

</> 
pub fn with_mode(entry: Entry, mode mode: Int) -> Entry

Override the entry mode. Out-of-range values panic; use [with_mode_checked] for caller-controlled error handling.

with_mode_checked

</> 
pub fn with_mode_checked(
  entry: Entry,
  mode mode: Int,
) -> Result(Entry, MetadataError)

Override the entry mode after validating it fits the widest mode field any of our archive families serialise it through.

with_modified_at

</> 
pub fn with_modified_at(
  entry: Entry,
  unix_seconds unix_seconds: Int,
) -> Entry

Override the last-modified timestamp. Negative values panic; see [with_modified_at_checked] for the validated variant. As with [with_owner], the format-specific upper bound (gzip 32-bit, tar 11-octal-digit, …) is enforced at encode time.

with_modified_at_checked

</> 
pub fn with_modified_at_checked(
  entry: Entry,
  unix_seconds unix_seconds: Int,
) -> Result(Entry, MetadataError)

Override the last-modified timestamp after validating it is non-negative. The format-specific upper bound is enforced at encode time as ArchiveFieldOverflow.

with_owner

</> 
pub fn with_owner(
  entry: Entry,
  user_id user_id: Int,
  group_id group_id: Int,
) -> Entry

Override the entry owner identifiers. Negative values panic; see [with_owner_checked] for the validated variant. No upper bound is enforced here — format-specific encoders (tar, ar, cpio newc) each apply their own narrower field-width checks at encode time, so a value that’s valid for one format and oversized for another can still be expressed as an Entry.

with_owner_checked

</> 
pub fn with_owner_checked(
  entry: Entry,
  user_id user_id: Int,
  group_id group_id: Int,
) -> Result(Entry, MetadataError)

Override the entry owner identifiers after validating they are non-negative. Format-side overflow (e.g. tar’s 21-bit field) is still surfaced at encode time as ArchiveFieldOverflow.

✨ Search Document