AppConfig::Args(3)

🎀 AppConfig::Args(3) 🎀

okay so bestie, this is a page from the User Contributed Perl Documentation section of the manual, and it's all about AppConfig::Args. pull up a chair, it's gonna be a vibe ✨

---

✨ NAME ✨

AppConfig::Args — the Perl5 module for reading command line arguments. that's it, that's the whole job, and she does it well 💅

---

🌸 SYNOPSIS 🌸

here's the whole flow, look:

use AppConfig::Args;

my $state   = AppConfig::State->new(\%cfg);
my $cfgargs = AppConfig::Args->new($state);

$cfgargs->parse(\@args);            # read args

that's literally it. make a state, wrap it in args, parse. slay 🫶

---

🦋 OVERVIEW 🦋

so AppConfig::Args is a Perl5 module that reads command line arguments and then uses the options it finds in there to update the variable values inside an AppConfig::State object. the state is the main character, she just does the reading 👑

also fyi, AppConfig::File ships as part of the AppConfig bundle. (yes, AppConfig::File, not ::Args — the manpage says what it says, i'm just the messenger 😭)

---

💜 DESCRIPTION 💜

🌈 USING THE AppConfig::Args MODULE 🌈

to import and actually use AppConfig::Args, this line has to show up in your Perl script:

use AppConfig::Args;

and here's the tea: if you use the AppConfig module and create an AppConfig::Args object through the parse() method, then AppConfig::Args gets used automatically. no extra effort, iconic behaviour honestly 💖

AppConfig::File is implemented with object-oriented methods. you create and initialise a new AppConfig::Args object with the new() method, and it hands you back a reference to a brand new AppConfig::File object. (again — that's what the page says, not me!) you should pass a reference to an AppConfig::State object in as the first parameter:

my $state   = AppConfig::State->new();
my $cfgargs = AppConfig::Args->new($state);

and boom 💥 that creates and returns a reference to a fresh new AppConfig::Args object. main character energy fr fr.

---

🧚 PARSING COMMAND LINE ARGUMENTS 🧚

the parse() method is the one that reads a list of command line arguments and updates the STATE accordingly. you pass in a reference to the list of arguments:

$cfgargs->parse(\@ARGV);

and ngl, if you call the method without a reference to an argument list, it'll just go ahead and examine and manipulate @ARGV itself. she's independent like that 🙈

⚠️ okay so this part matters, listen up: if the PEDANTIC option is turned off in the AppConfig::State object, any parsing errors (invalid variables, unvalidated values, etc) will generate warnings but they will not make the method return early. after processing all the arguments, the method returns 1 if it got through without warning, or 0 if one or more warnings were raised. but when PEDANTIC is turned on, the method generates a warning and immediately returns 0 the second it hits any parsing error. periodt 💀

the method keeps on parsing arguments until it detects the first one that does not start with a leading dash, '-'. and just so we're clear: arguments that are actually values for other options don't get examined this way. they're exempt, they're VIPs 🎟️

---

🔥 FUTURE DEVELOPMENT 🔥

context: this module was developed to provide backwards compatibility (to some degree) with the preceding App::Config module. the argument parsing it provides is basic, but it offers a quick and efficient solution for those times when simple option handling is all that's required. lowkey humble, highkey useful ✨

if you need more flexibility when parsing command line arguments, then you should consider using the AppConfig::Getopt module. it gets loaded and used automatically when you call the AppConfig getopt() method.

and here's why: AppConfig::Getopt provides considerably extended functionality over AppConfig::Args by delegating out the whole task of argument parsing to Johan Vromans' Getopt::Long module. for advanced command-line parsing, that module (either Getopt::Long all by itself, or in conjunction with AppConfig::Getopt) is highly recommended. seriously, go get her 👑

---

💖 AUTHOR 💖

Andy Wardley, <abw@wardley.org> — legend behaviour 🫶

---

🌸 COPYRIGHT 🌸

Copyright (C) 1997-2007 Andy Wardley. All Rights Reserved.

Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

⭐ SEE ALSO ⭐

• AppConfig
• AppConfig::State
• AppConfig::Getopt
• Getopt::Long

go read them, iykyk 📚

---

okay that's the whole page!! this one's perl v5.42.0, dated 2015-04-14, from the AppConfig::Args(3) manpage — mwah, go parse some args bestie 💋🎀🦋