view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME
    Ask - ask your users about stuff

SYNOPSIS
    Object-oriented style:

       use Ask;
   
       my $ask = Ask->detect;
   
       if ($ask->question(text => "Are you happy?")
       and $ask->question(text => "Do you know it?")
       and $ask->question(text => "Really want to show it?")) {
          $ask->info(text => "Then clap your hands!");
       }

    Functional style:

       use Ask ':all';
   
       if (question("Are you happy?")
       and question("Do you know it?")
       and question("Really want to show it?")) {
          info("Then clap your hands!");
       }

DESCRIPTION
    The `Ask` suite is a set of modules for interacting with users; prompting
    them for information, displaying messages, warnings and errors, etc.

    There are already countless CPAN modules for doing this sort of thing, but
    what sets `Ask` apart from them is that `Ask` will detect how your script
    is being run (in a terminal, headless, etc) and choose an appropriate way
    to interact with the user.

  Class Methods
    `Ask->instance`
        Singleton pattern. Can also be passed an argument to use it as a
        setter.

    `Ask->detect(%arguments)`
        A constructor, sort of. It inspects the program's environment and
        returns an object that implements the Ask API (see below).

        Backend-specific arguments can be provided:

          my $ask = Ask->detect(
            %common_args,
            'Ask::STDIO'  => \%stdio_args,
            'Ask::Zenity' => \%zenity_args,
          );

        Note that these objects don't usually inherit from `Ask`, so the
        following will typically be false:

           my $ask = Ask->detect(%arguments);
           $ask->isa("Ask");

        Instead, check:

           my $ask = Ask->detect(%arguments);
           $ask->DOES("Ask::API");

    `Ask->backends`
        Returns a list of available backends. Each backend is a Perl class
        name. Some of the backends may be available (i.e. installed and able
        to be compiled) without being usable under current circumstances (e.g.
        the Gtk2 backend is available but cannot be used because no X server
        is running). To check usability, instantiate the class and call
        `is_usable` on the instance.

        The list is sorted in "quality" order, best to worst, though quality
        is subjective.

    `Ask->plugins`
        The same as `Ask->backends`, but doesn't check that each result is a
        loadable Perl class, and doesn't sort them in any particular order.

  The Ask API
    Objects returned by the `detect` method implement the Ask API. This
    section documents that API.

    The following methods are provided by objects implementing the Ask API.
    They are largely modeled on the interface for GNOME Zenity.

    `info(text => $text, %arguments)`
        Display a message to the user.