#!/usr/bin/perl
#
# This file is part of App-SpreadRevolutionaryDate
#
# This software is Copyright (c) 2019 by Gérald Sédrati-Dinet.
#
# This is free software, licensed under:
#
#   The GNU General Public License, Version 3, June 2007
#
use strict;
use warnings;
use utf8;

# PODNAME: spread-revolutionary-date
# ABSTRACT: Spread date and time from Revolutionary (Republican) Calendar

use App::SpreadRevolutionaryDate;
App::SpreadRevolutionaryDate->new->spread;

__END__

=pod

=encoding UTF-8

=head1 NAME

spread-revolutionary-date - Spread date and time from Revolutionary (Republican) Calendar

=head1 VERSION

version 0.04

=head1 DESCRIPTION

C<spread-revolutionary-date> is a L<Free Software|https://www.gnu.org/philosophy/free-sw.htmlhttps://www.gnu.org/philosophy/free-sw.html> that spreads the current date, expressed in L<French Revolutionary calendar|https://en.wikipedia.org/wiki/French_Republican_calendar>, to various social networks: L<Twitter|https://twitter.com/>, L<Mastodon|https://mastodon.social/>, and the L<Freenode|https://freenode.net/> Internet Relay Chat network.

The French Revolutionary calendar, also called Republican calendar, was introduced during the L<French Revolution|https://en.wikipedia.org/wiki/French_Revolution>, and used from late 1793 to 1805, and also during the L<Paris Commune|https://en.wikipedia.org/wiki/Paris_Commune> in 1871. This was an attempt to get rid of religious and royalist references found in Gregorian calendar when naming measures of Time. Months were given new names based on nature, each day of the year, instead of being named after an associated saint, had a unique name associated with the rural economy: agricultural tools, common animals, grains, pastures, trees, roots, flowers, fruits, plants, and minerals. But this was also an attempt to give more rational in measuring Time, basing measures on decimal system. Instead of weeks, each month was divided into exactly 3 I<décades>, that is ten days; days were divided into ten hours; hours into 100 minutes; and minutes into 100 seconds.

You B<must> have a registering account on each of the targets you want to spread the revolutionary date. And you must get credentials for C<spread-revolutionary-date> to post on Twitter and Mastodon. Finally, you have to configure C<spread-revolutionary-date> to use these credentials, see L</CONFIGURATION> and L</"COMMAND LINE PARAMETERS"> below.

The revolutionary date and time is computed thanks to the L<DateTime::Calendar::FrenchRevolutionary> Perl module, by Jean Forget.

=head1 USAGE

  # Just execute the script in your shell
  # to spread current date to configured accounts on Twitter, Mastodon and Freenode:
  $ spread-revolutionary-date

  # Or, since this script do nothing but calling the L<App::SpreadRevolutionaryDate> Perl module,
  # use this one-liner:
  $ perl -MApp::SpreadRevolutionaryDate -e 'App::SpreadRevolutionaryDate->new->spread;'

  # Test spreading to Mastodon only:
  $ spread-revolutionary-date --mastodon --test

  # Spread to Twitter and Freenode explicit channels
  $ spread-revolutionary-date --twitter --freenode \
      --freenode-channels='#revolution' --freenode-channels='#acab'

=head1 CONFIGURATION

Once again: you B<have to> configure C<spread-revolutionary-date> with credentials for registered account on each of the desired targets, so it can spread the revolutionary date on behalf of theses accounts.

Configuration options may also be specified as command line parameters, see L</"COMMAND LINE PARAMETERS"> below, which take precedence on options of the configuration file.

The configuration file should lie on C<~/.config/spread-revolutionary-date/spread-revolutionary-date.conf> or C<~/.spread-revolutionary-date.conf>. In case a file is found on both paths, the second one is ignored. The configuration file should use the popular L<INI file format|https://en.wikipedia.org/wiki/INI_file>. A sample configuration file can be found in this distribution at C<etc/sample-spread-revolutionary-date.conf>.

=head2 General options

These options should appear outside of any section of the cofiguration file.

=head3 twitter

Spread on Twitter explicitely. If none of the C<twitter>, C<mastodon>, C<freenode> option is set, the revolutionary date is spread on all of these three targets.

=head3 mastodon

Spread on Mastodon explicitely. If none of the C<twitter>, C<mastodon>, C<freenode> option is set, the revolutionary date is spread on all of these three targets.

=head3 freenode

Spread on Freenode explicitely. If none of the C<twitter>, C<mastodon>, C<freenode> option is set, the revolutionary date is spread on all of these three targets.

=head3 test

Do no not actually spread the revolutionary date, just print it on standard output for Twitter and Mastodon, and send it on configured test channels for Freenode (see <L/"test channels> below).

=head3 acab

Instead of spreading the current date and time, pretend that decimal time is 1:31:20 (which corresponds to 03:08:56 Paris winter time, in sexagesimal scale used by common Anglo-Babylonian Time).

=head2 Twitter options

Theses options are credentials for C<spread-revolutionary-date> to spread on a Twitter account. You have to get them from your L<Twitter API account|https://apps.twitter.com/> with C<write> access level.

=head3 consumer_key

Your Twitter Consumer API key for this application.

=head3 consumer_secret

Your Twitter Consumer API secret key for this application.

=head3 access_token

Your Twitter Access token for this application.

=head3 access_token_secret

Your Twitter Access token secret for this application.

=head2 Mastodon options

Theses options are credentials for C<spread-revolutionary-date> to spread on a Mastodon account. You have to get them from your L<Mastodon instance API account|https://mstdn.fr/settings/applications> with C<write> scope. Note that Mastodon is a decentralized network with multiple instances, the previous link is for L<mstdn.fr|https://mstdn.fr> instance, please replace url with your preferred instance.

=head3 instance

The domain name of your instance, eg: C<mastodon.social>, C<mstdn.fr>, etc.

=head3 client_id

Your Mastodon Client key for this application.

=head3 client_secret

Your Mastodon Client secret for this application.

=head3 access_token

Your Mastodon Access token for this application.

=head2 Freenode options

The first two options are credentials for C<spread-revolutionary-date> to spread on a Freenode account. See L<https://freenode.net/kb/answer/registration> to find out how to register an account on Freenode.

=head3 nickname

Your Freenode nickname.

=head3 password

Your Freenode password.

=head3 channels

This option can be specified multiple time. C<spread-revolutionary-date> will spread on every channel specified with this option. This option should be specified at least one time if L</test> option is not set. It is ignored if L</test> option is set.

=head3 test_channels

This option can be specified multiple time. C<spread-revolutionary-date> will spread on every channel specified with this option. This option should be specified at least one time if L</test> option is set. It is ignored if L</test> option is not set.

=head1 COMMAND LINE PARAMETERS

Any command line parameter takes precedence on the corresponding option specified on the confiuration file, see L</"CONFIGURATION> below.

=head2 General parameters

=head3 --twitter

Same as L</twitter> configuration option below.

=head3 --mastodon

Same as L</mastodon> configuration option below.

=head3 --freenode

Same as L</freenode> configuration option below.

=head3 --test

Same as L</test> configuration option below.

=head3 --acab

Same as L</acab> configuration option below.

=head2 Twitter parameters

Theses parameters specify credentials for C<spread-revolutionary-date> to spread on a Twitter account. You have to get them from your L<Twitter API account|https://apps.twitter.com/> with C<write> access level.

=head3 --twitter-consumer_key

Same as L</consumer-key> configuration option below.

=head3 --twitter-consumer_secret

Same as L</consumer-secret> configuration option below.

=head3 --twitter-access_token

Same as L</access_token> configuration option below.

=head3 --twitter-access_token_secret

Same as L</access_token_secret> configuration option below.

=head2 Mastodon parameters

Theses parameters specify credentials for C<spread-revolutionary-date> to spread on a Mastodon account. You have to get them from your L<Mastodon instance API account|https://mstdn.fr/settings/applications> with C<write> scope. Note that Mastodon is a decentralized network with multiple instances, the previous link is for L<mstdn.fr|https://mstdn.fr> instance, please replace url with your preferred instance.

=head3 --mastodon-instance

Same as L</instance> configuration option below.

=head3 --mastodon-client_id

Same as L</client_id> configuration option below.

=head3 --mastodon-client_secret

Same as L</client_secret> configuration option below.

=head3 --mastodon-access_token

Same as L</access_token> configuration option below.

=head2 Freenode parameters

The first two parameters are credentials for C<spread-revolutionary-date> to spread on a Freenode account. See L<https://freenode.net/kb/answer/registration> to find out how to register an account on Freenode.

=head3 --freenode-nickname

Same as L</nickname> configuration option below.

=head3 --freenode-password

Same as L</password> configuration option below.

=head3 --freenode-channels

Same as L</channels> configuration option below.

=head3 --freenode-test_channels

Same as L</test_channels> configuration option below.

=head1 SEE ALSO

=over

=item L<App::SpreadRevolutionaryDate>

=item L<DateTime::Calendar::FrenchRevolutionary>

=item L<AppConfig>

=item L<Net::Twitter::Lite::WithAPIv1_1>

=item L<Mastodon::Client>

=item L<Bot::BasicBot>

=back

=head1 AUTHOR

Gérald Sédrati-Dinet <gibus@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2019 by Gérald Sédrati-Dinet.

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007

=cut
