#!/usr/bin/env perl

# PODNAME: maclog
# ABSTRACT: write to the macOS unified log from the command line

use 5.018;
use warnings;

#<<<
our $VERSION = '0.0.5'; # VERSION
#>>>

use Getopt::Long;
use Pod::Usage;
use Log::Any::Adapter;

#pod =head1 USAGE
#pod
#pod Simple version:
#pod
#pod     maclog --message 'Hello world!'
#pod
#pod All the bells and whistles:
#pod
#pod     maclog --subsystem com.phoenixtrap.maclog \
#pod            --level info                       \
#pod            --category general                 \
#pod            --format "Hello %s number %i"      \
#pod            --message 'world'                  \
#pod            --message 42
#pod
#pod Arbitrary number of message strings without B<--message>:
#pod
#pod     maclog --format "Hello %s number %i" -- world 42
#pod
#pod =head1 DESCRIPTION
#pod
#pod This script provides an easy way to add entries to the macOS unified
#pod log from the command line, a feat normally reserved for users of Apple's
#pod Swift and Objective-C APIs.
#pod
#pod It is a thin wrapper around L<Log::Any::Adapter::MacOS::OSLog>.
#pod
#pod =required B<--subsystem>
#pod
#pod The name of the subsystem field in the log entry in reverse DNS order.
#pod Defaults to C<com.phoenixtrap.maclog>.
#pod
#pod =cut

my $subsystem = 'com.phoenixtrap.maclog';

#pod =required B<--level>
#pod
#pod The desired logging level. As this command script is a thin wrapper
#pod around L<Log::Any::Adapter::MacOS::OSLog>, it uses the following level
#pod names, mapped to corresponding macOS L<os_log(3)> levels:
#pod
#pod =over
#pod
#pod =item * trace: L<os_log_debug(3)>
#pod
#pod =item * debug: L<os_log_debug(3)>
#pod
#pod =item * info: L<os_log_info(3)>
#pod
#pod =item * notice: L<os_log_info(3)>
#pod
#pod =item * warning: L<os_log_fault(3)>
#pod
#pod =item * error: L<os_log_error(3)>
#pod
#pod =item * critical: L<os_log(3)>
#pod
#pod =item * alert: L<os_log(3)>
#pod
#pod =item * emergency: L<os_log(3)>
#pod
#pod =back
#pod
#pod Defaults to C<info>.
#pod
#pod =cut

my $level = 'info';

#pod =required B<--category>
#pod
#pod The desired category field in the unified log entry.
#pod Note that this is B<not> related to
#pod L<Log::Any's notion of categories|Log::Any/CATEGORIES>.
#pod
#pod Defaults to C<general>.
#pod
#pod =cut

my $category = 'general';

#pod =option B<--private>
#pod
#pod Redacts the log message.
#pod
#pod =cut

my $private;

#pod =option B<--format>
#pod
#pod A L<sprintf|perlfunc/sprintf> format describing where and how to format
#pod individual message values.
#pod If no B<--format> is specified, message values will be joined together
#pod with spaces.
#pod
#pod =cut

my $format;

#pod =option B<--message>
#pod
#pod Can be specified multiple times. Each B<--message> value will be filled
#pod into the corresponding formatting code in the B<format>.
#pod You may instead provide one or more message values at the end of the
#pod command preceded by C<-->.
#pod
#pod =cut

my @message;

#pod =option B<--help>
#pod
#pod Prints helpful information about how to use this command script.
#pod
#pod =cut

my $help;

#pod =option B<--man>
#pod
#pod Prints this command script's entire manual page.
#pod
#pod =cut

my $man;

GetOptions(
    'help|?'      => \$help,
    'man'         => \$man,
    'subsystem=s' => \$subsystem,
    'level=s'     => \$level,
    'private!'    => \$private,
    'category=s'  => \$category,
    'format:s'    => \$format,
    'message:s'   => \@message,
) or pod2usage(1);

{
    ## no critic (ControlStructures::ProhibitPostfixControls)
    pod2usage(
        -exitval  => 0,
        -verbose  => 99,
        -sections => 'USAGE',
    ) if $help;
    pod2usage( -exitval => 0, -verbose => 2 ) if $man;

    @message = @ARGV unless @message;
    pod2usage(1)     unless @message;
}

Log::Any::Adapter->set(
    'MacOS::OSLog',
    subsystem   => $subsystem,
    level       => $level,
    os_category => $category,
    private     => $private,
);
my $log = Log::Any->get_logger();

( @message > 1 ) && ( $format ||= join q{ }, ('%s') x @message );
if ($format) {
    $level = "${level}f";
    unshift @message, $format;
}
$log->$level(@message);

__END__

=pod

=encoding UTF-8

=head1 NAME

maclog - write to the macOS unified log from the command line

=head1 VERSION

version 0.0.5

=head1 USAGE

Simple version:

    maclog --message 'Hello world!'

All the bells and whistles:

    maclog --subsystem com.phoenixtrap.maclog \
           --level info                       \
           --category general                 \
           --format "Hello %s number %i"      \
           --message 'world'                  \
           --message 42

Arbitrary number of message strings without B<--message>:

    maclog --format "Hello %s number %i" -- world 42

=head1 DESCRIPTION

This script provides an easy way to add entries to the macOS unified
log from the command line, a feat normally reserved for users of Apple's
Swift and Objective-C APIs.

It is a thin wrapper around L<Log::Any::Adapter::MacOS::OSLog>.

=head1 REQUIRED ARGUMENTS

=head2 B<--subsystem>

The name of the subsystem field in the log entry in reverse DNS order.
Defaults to C<com.phoenixtrap.maclog>.

=head2 B<--level>

The desired logging level. As this command script is a thin wrapper
around L<Log::Any::Adapter::MacOS::OSLog>, it uses the following level
names, mapped to corresponding macOS L<os_log(3)> levels:

=over

=item * trace: L<os_log_debug(3)>

=item * debug: L<os_log_debug(3)>

=item * info: L<os_log_info(3)>

=item * notice: L<os_log_info(3)>

=item * warning: L<os_log_fault(3)>

=item * error: L<os_log_error(3)>

=item * critical: L<os_log(3)>

=item * alert: L<os_log(3)>

=item * emergency: L<os_log(3)>

=back

Defaults to C<info>.

=head2 B<--category>

The desired category field in the unified log entry.
Note that this is B<not> related to
L<Log::Any's notion of categories|Log::Any/CATEGORIES>.

Defaults to C<general>.

=head1 OPTIONS

=head2 B<--private>

Redacts the log message.

=head2 B<--format>

A L<sprintf|perlfunc/sprintf> format describing where and how to format
individual message values.
If no B<--format> is specified, message values will be joined together
with spaces.

=head2 B<--message>

Can be specified multiple times. Each B<--message> value will be filled
into the corresponding formatting code in the B<format>.
You may instead provide one or more message values at the end of the
command preceded by C<-->.

=head2 B<--help>

Prints helpful information about how to use this command script.

=head2 B<--man>

Prints this command script's entire manual page.

=head1 DIAGNOSTICS

The entire point of this command script is diagnostics. Use the macOS
L<log(1)> command or the Console app to view the results.

=head1 EXIT STATUS

Exits 0 on success or viewing the help/manual page,
1 if there is a problem with the command line arguments.
Other exit values may occur if there is a problem with code execution.

=head1 CONFIGURATION

None.

=head1 DEPENDENCIES

=over

=item * L<Log::Any::Adapter::MacOS::OSLog>

=back

=head1 INCOMPATIBILITIES

Because this command script relies on the macOS unified logging system
introduced in macOS Sierra version 10.12, it is incompatible with
earlier versions of OS X, Mac OS X, the classic Mac OS, and all other
non-Apple platforms (Microsoft Windows, Linux, other Unixes, etc.).

=head1 BUGS AND LIMITATIONS

Undoubtedly. Open an issue in the tracker.

=head1 SEE ALSO

The Eclectic Light Company's C<blowhole> command line utility, available
at L<https://eclecticlight.co/consolation-t2m2-and-log-utilities/>,
performs a similar function but does not enable the user to change
the subsystem or category.

=for :stopwords cpan testmatrix url bugtracker rt cpants kwalitee diff irc mailto metadata placeholders metacpan

=head1 SUPPORT

=head2 Perldoc

You can find documentation for this module with the perldoc command.

  perldoc maclog

=head2 Websites

The following websites have more information about this module, and may be of help to you. As always,
in addition to those websites please use your favorite search engine to discover more resources.

=over 4

=item *

MetaCPAN

A modern, open-source CPAN search engine, useful to view POD in HTML format.

L<https://metacpan.org/release/Log-Any-Adapter-MacOS-OSLog>

=item *

RT: CPAN's Bug Tracker

The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.

L<https://rt.cpan.org/Public/Dist/Display.html?Name=Log-Any-Adapter-MacOS-OSLog>

=item *

CPANTS

The CPANTS is a website that analyzes the Kwalitee ( code metrics ) of a distribution.

L<http://cpants.cpanauthors.org/dist/Log-Any-Adapter-MacOS-OSLog>

=item *

CPAN Testers

The CPAN Testers is a network of smoke testers who run automated tests on uploaded CPAN distributions.

L<http://www.cpantesters.org/distro/L/Log-Any-Adapter-MacOS-OSLog>

=item *

CPAN Testers Matrix

The CPAN Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms.

L<http://matrix.cpantesters.org/?dist=Log-Any-Adapter-MacOS-OSLog>

=item *

CPAN Testers Dependencies

The CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution.

L<http://deps.cpantesters.org/?module=Log::Any::Adapter::MacOS::OSLog>

=back

=head2 Bugs / Feature Requests

Please report any bugs or feature requests through the web interface at L<https://codeberg.org/mjgardner/perl-Log-Any-Adapter-MacOS-OSLog/issues>.

=head2 Source Code

The code is open to the world, and available for you to hack on. Please feel free to browse it and play
with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull
from your repository :)

L<https://codeberg.org/mjgardner/perl-Log-Any-Adapter-MacOS-OSLog>

  git clone https://codeberg.org/mjgardner/perl-Log-Any-Adapter-MacOS-OSLog.git

=head1 AUTHOR

Mark Gardner <mjgardner@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2025 by Mark Gardner.

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

=cut
