---
name: "Arch::Inventory"
section: "3pm"
platform: "linux"
package: "libarch-perl"
version: "0.5.2-2"
release: "Debian 11 (Bullseye)"
platforms: ["linux"]
url: "https://new.carta.tech/Arch::Inventory"
---

# Arch::Inventory(3pm)

class representing a tree inventory

## NAME

Arch::Inventory - class representing a tree inventory

## SYNOPSIS

```
    use Arch::Inventory qw(:category :type);
    my $inv = Arch::Inventory->new;  # use cwd
    print Arch::Inventory->to_string($inv->get_root_entry), "\n";
    print $inv->get_listing;
```

or (most commonly):

```
    use Arch::Tree;
    my $tree = Arch::Tree->new;
    my $inv = $tree->get_inventory;
    print $inv->get_listing;
```

## DESCRIPTION

Arch::Inventory generates a tree inventory.

An inventory is a tree structure of elements, each representing a single directory entry of the source tree. Each inventory entry is described by an hash with the following fields:

- **category**

  The classification of the tree element. **category** can be one of **TREE**, **SOURCE**, **PRECIOUS**, **BACKUP** or **JUNK**.

- **untagged**

  A boolean value indicating whether the element was first classified as **SOURCE** but lacked an inventory id.

- **type**

  The tree element type. **type** can be one of **FILE**, **DIRECTORY** or **SYMLINK**.

- **path**

  The complete path to the tree element relative to the inventory base directory.

- **id**

  The elements inventory id. May be `"undef"`.

- **children**

  A hash of the elements direct children, idexed by their last path element.

  This field exists for elements of type **DIRECTORY** only.

The **category** and **type** constants can be conveniently imported using the tags `":category"` and `":type"`.

```
    use Arch::Inventory qw(:category :type);
```

## METHODS

The following methods are available:

**new**, **directory**, **get\_root\_entry**, **get\_entry**, **get\_listing**, **annotate\_fs**, **foreach**, **dump**, **to\_string**.

- **new** \[*$dir*\]

  Create an inventory for *$dir* or the current directory if *$dir* is not specified.

- **directory**

  Returns the inventories base directory as passed to **new**.

- **get\_root\_entry**

  Returns the inventory element for the base directory.

  The root entry always has the following properties:

  ```
      $root = {
          category => TREE,       # if {arch} exists, SOURCE otherwise
          untagged => 1,
          type     => DIRECTORY,
          path     => '',
          id       => undef,
          children => { ... },
      }
  ```

- **get\_entry** *$path*

  - **get\_entry** *@path\_elements*

  Returns the inventory element for the specified path. The path may either be given as a single string or as a list of path elements.

  If the element does not exist `"undef"` is returned.

  Using an empty or no path is equivalent to calling **get\_root\_entry**.

- **get\_listing**

  Generates a textual inventory listing equivalent to the output of

  ```
      tla inventory -tspbju -B --kind --ids --untagged
  ```

  **Note:** The output order is not equivalent to tla. Instead of strict ASCII order of path names, a directory entry is always directly followed by its child entries. Entries with the same parent entry are ASCII ordered.

- **annotate\_fs**

  - **annotate\_fs** *$entry*

  Add filesystem information to *$entry* or every inventory entry if none is provided. This adds the fields **stat** and **symlink** to the annotated entries which contain the output of **lstat** and **readlink** respectively.

- **foreach** *$coderef*

  Execute *$coderef* for every inventory entry, passing the entry as `$_`\[0\].

- **dump**

  Generates a dump of the inventory structure using Data::Dumper.

- **to\_string** *$inventory\_element*

  Generates an inventory line for the inventory element as produced by tla.

## BUGS

Awaiting for your reports.

## AUTHORS

Mikhael Goikhman (migo@homemail.com--Perl-GPL/arch-perl--devel).

Enno Cramer (uebergeek@web.de--2003/arch-perl--devel).

## SEE ALSO

For more information, see tla, Arch::Util.