=begin pod

=head1 NAME

B<Mi6::Helper> - An aid for converting Raku modules to use B<App::Mi6>

=head1 SYNOPSIS

=begin code
use Mi6::Helper

$ mi6-helper new=Foo::Bar provides=Bar-description.txt
=end code

=head1 DESCRIPTION

Note this is API 2 and its approach has changed significantly since
the author has had much more experience using B<App::Mi6>.  For
example, accidentally using C<mi6 test> in a non-mi6 module's base
directory will corrupt an existing README.md file!

B<CAUTION>: Before using this tool on a real module repository, the
user should ensure all contents have been comitted with Git to enable
recovery from any unwanted changes.

This module installs a Raku executable named C<mi6-helper> which is
designed for two major modes of operation:

=begin item
new

Creates a new module using B<mi6> and then changes some of the
contents to satisfy the 'docs' option and, optionally, substitute
'blah...' with the user's short description.
=end item

=begin item
old  ***NOT YET IMPLEMENTED***

Inspects an existing Git repository of a Raku module to help convert
it to one that uses the C<App::Mi6> module with the Zef
repository. Essentially all it does is add or mofify the following
files:

    =item Changes
    =item dist.ini
    =item README.md

See more details below.
=end item

=head2 Modified files for mode B<new>

Z<===================================================================>
=head3 Files with replaced, modified, or added lines:

=begin item
B<dist.ini> (in the base directory)

This file, if found existing, will cause an abort. No changes can be
made to an existing file. You may use the C<force> option at your own
risk.

The default file does B<NOT> create any Markdown files from any source
unless you use the C<docs> option. In those cases a
B<docs/README.rakudoc> file is created and this file is modified
appropriately.

=end item

Z<===================================================================>
=head3 New directory and file:

=begin item
B<README.md> (in the base directory)

This file, if it exists, is copied to a file named
B<README.md.original> for safety. The original file is not modified by
this program.

=end item

=begin item
B<Changes> (in the base directory)

If a B<Changes> file happens to exist, it will be copied to a
B<Changes.original> file and the original will be overwritten with one
in the correct format.

=end item

=begin item
B<docs/README.rakudoc> (in the base/docs directory)

If such a file exists, it will be left unchanged.
=end item

The default changes to the C<dist.ini> file are those the author
likes, but a future update will allow the user to customize those
actions in his or her own C<$HOME/.mi6helper-ini> file.

The contents of the two files are shown below.

=head2 B<Changes> file

=head2 B<dist.ini> file (benign version for non-mi6 repositories)

=begin code
=end code

=head2 B<dist.ini> file (version for newly created mi6 repositories)

=begin code
=end code

=head1 DESCRIPTION

=begin code
sub get-mod-name
  - determine the base module name
    - check any dist.ini file
    - check the META6.json file
    - throw if not found or there are conflicts
=end code

=head1 AUTHOR

Tom Browder <tbrowder@acm.org>

=head1 CREDITS

The very useful Raku modules used herein:

=item C<App::Mi6>     by B<github:skaji>
=item C<File::Find>   by B<github:tadzik>
=item C<JSON::Fast>   by B<github:timo>
=item C<Config::INI>  by B<gitbub:tadzik>

=head1 COPYRIGHT AND LICENSE

Copyright &#x00A9; 2020-2022 Tom Browder

This library is free software; you may redistribute it or modify it under the Artistic License 2.0.

=end pod
