App::S...ngeList(3pm)

📦

version 1.6.1 · 6 versions

✨ App::S...ngeList(3pm) ✨

okay bestie, quick vibe check: this is the manual page for App::S...ngeList(3pm), filed under "User Contributed Perl Documentation", which is fr fr the community showing up and showing out. It's the whole doc for App::Sqitch::Plan::ChangeList and we are going to get through every single line of it together. no skipping. grab a lil snack 🍓

🦋 NAME 🦋

App::Sqitch::Plan::ChangeList — Sqitch deployment plan change list

It's literally just that. The name section said the whole thing. Iconic behavior honestly.

🌸 SYNOPSIS 🌸

my $list = App::Sqitch::Plan::ChangeList->new(
    $add_roles,
    $add_users,
    $insert_user,
    $insert_user2,
);

my @changes = $list->changes;
my $add_users = $list->change_at(1);
my $add_users = $list->get('add_users');

my $insert_user1 = $list->get('insert_user@alpha');
my $insert_user2 = $list->get('insert_user');

see how we just built a whole list and then asked it politely for things back? that's the whole energy. the way that get('insert_user@alpha') and get('insert_user') are two different lookups because of the tag qualifier is giving ✨ nuance ✨ and i'm obsessed.

💅 DESCRIPTION 💅

okay so real talk: this module is used internally by App::Sqitch::Plan to manage plan changes. it is not here to be your little hobby project, it's backstage crew. the way it's built? it's modeled on Array::AsHash and Hash::MultiValue, but with one very important lil upgrade: it makes allowances for finding changes relative to tags. that tag-awareness is the main character, everything else is supporting cast. 👑

🎀 INTERFACE 🎀

🧚 Constructors 🧚

`new`

my $plan = App::Sqitch::Plan::ChangeList->new( @changes );

Instantiates and returns an App::Sqitch::Plan::ChangeList object with the list of changes. Each change should be an App::Sqitch::Plan::Change object. Order will be preserved — bestie, the order is sacred, we do not shuffle — but the location of each change will be indexed by its name and ID, as well as the names and IDs of any associated tags. so it's a list that's also a lookup table. multi-talented. ate. 💅

👑 Instance Methods 👑

`count`

my $count = $changelist->count;

Returns the number of changes in the list. that's it, that's the whole method, and honestly we love a one-job queen.

`changes`

my @changes = $changelist->changes;

Returns all of the changes in the list. all of them. every last one. 🫶

`tags`

my @tags = $changelist->tags;

Returns all of the tags associated with changes in the list.

`items`

my @changes = $changelist->items;

An alias for "changes". same girl, different name, we support her 🌈

`change_at`

my $change = $change_list->change_at(10);

Returns the change at the specified index.

`index_of`

my $index = $changelist->index_of($change_id);
my $index = $changelist->index_of($change_name);

Returns the index of the change with the specified ID or name. The value passed may be one of these forms:

An ID

my $index = $changelist->index_of('6c2f28d125aff1deea615f8de774599acf39a7a1');

This is the SHA1 ID of a change or tag. Currently — and yes, currently, pay attention — the full 40-character hexed hash string must be specified. no abbreviating, no shortcuts, we are not doing vibes-based ID matching here.

A change name

my $index = $changelist->index_of('users_table');

The name of a change. Will throw an exception if the more than one change in the list goes by that name. so like, if it's ambiguous, it's gonna yell. 😭

A tag name

my $index = $changelist->index_of('@beta1');

The name of a tag, including the leading "@". do not forget the "@", i'm begging you 🙈

A tag-qualified change name

my $index = $changelist->index_of('users_table@beta1');

The named change as it was last seen in the list before the specified tag.

`first_index_of`

my $index = $changelist->first_index_of($change_name);
my $index = $changelist->first_index_of($change_name, $name);

Returns the index of the first instance of the named change in the list. If a second argument is passed, the index of the first instance of the change after the index of the second argument will be returned. This is useful for getting the index of a change as it was deployed after a particular tag, for example:

my $index = $changelist->first_index_of('foo', '@beta');
my $index = $changelist->first_index_of('foo', 'users_table@beta1');

The second argument must unambiguously refer to a single change in the list. As such, it should usually be a tag name or tag-qualified change name. Returns "undef" if the change does not appear in the list, or if it does not appear after the specified second argument change name.

heads up bestie: that second arg has to point at exactly one change. if it's wishy-washy we can't work with it. 💀

`last_change`

my $change = $changelist->last_change;

Returns the last change to be appear in the list. Returns "undef" if the list contains no changes. (yes, the original says "to be appear" — i am not fixing it, i am not touching it, it's part of the lore now 🫶)

`last_tagged_change`

my $change = $changelist->last_tagged_change;

Returns the last tagged change in the list. Returns "undef" if the list contains no tagged changes.

`index_of_last_tagged`

my $index = $changelist->index_of_last_tagged;

Returns the index of the last tagged change in the list. Returns "undef" if the list contains no tags.

`get`

my $change = $changelist->get($id);
my $change = $changelist->get($change_name);
my $change = $changelist->get($tag_name);

Returns the change for the specified ID or name. The name may be specified as described for index_of(). An exception will be thrown if more than one change goes by a specified name. As such, it is best to specify it as unambiguously as possible: as a tag name, a tag-qualified change name, or an ID. tl;dr — be specific or catch an exception, your call, but like, be specific. 🌸

`contains`

say 'Yes!' if $plan->contains('6c2f28d125aff1deea615f8de774599acf39a7a1');

Like index_of(), but never throws an exception, and returns true if the plan contains the specified change, and false if it does not. it's the chill, emotionally stable version. 🧘

`find`

my $change = $changelist->find($id);
my $change = $changelist->find($change_name);
my $change = $changelist->find($tag_name);
my $change = $changelist->find("$change_name\@$tag_name");

Tries to find and return a change based on the argument. If no tag is specified, finds and returns the first instance of the named change. Otherwise, it returns the change as of the specified tag. Unlike get(), it will not throw an error if more than one change exists with the specified name — it'll just return the first instance. no drama, just results. 💅

`append`

$changelist->append(@changes);

Append one or more changes to the list. Does not check for duplicates, so use with care.

fr fr, bestie: no duplicate checking. none. zero. you want dupes, you're getting dupes. use with care. ⚠️

`index_tag`

$changelist->index_tag($index, $tag);

Index the tag at the specified index. That is, the tag is assumed to be associated with the change at the specified index, and so the internal look up table is updated so that the change at that index can be found via the tag's name and ID.

🌈 SEE ALSO 🌈

App::Sqitch::Plan — The Sqitch plan. (the big one. the parent. the whole reason any of this exists 🫶)

💖 AUTHOR 💖

David E. Wheeler <david@justatheory.com>

legend behavior honestly.

📜 LICENSE 📜

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

okay so legally speaking this is the "AS IS" part and it means no warranty, none, we said what we said, the authors are not liable for literally anything. keep the copyright notice in your copies. that's the deal. 💀

aaaand that's the whole page bestie, every last option, method and legal paragraph accounted for 🎀 this was perl v5.40.1, dated 2026-07-26, and it's the manual for App::S...ngeList(3pm). you understood it, you ate it up, periodt. 💅✨

📦 where this page comes from

ubuntu stonking: sqitch 1.6.1-2 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms