Rand Stats

Mi6::Helper

zef:tbrowder

Actions Status Actions Status Actions Status

NAME

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

WARNING

There is a serious bug in the current version: it is unable to to correctly handle a desired module name with mixed '::' and hyphens ('-'). An issue has been filed, but, unless a user needs it soon, a fix will be delayed. A work-around is to manually make the necessary changes after the failure message. Please comment in the issue entry (#11) if a fix is important for your current project.

SYNOPSIS

use Mi6::Helper
$ mi6-helper new=Foo::Bar  # uses the 'provides' text in hidden file 
                           # '.Foo-Bar' (recommended method)

Easily create the template for a new Raku module repository for management by App::Mi6 with modifications including:

Special installation requirements

The user must install and have an account with fez to use this module.

DESCRIPTION

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

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 mi6-helper which is designed for two major modes of operation:

new

NOTE: If one of the non-Linux OS tests fail, you can eliminate that test by doing the following two steps (for example, remove the macos test):

old

Modified files for mode new

Files with replaced, modified, or added lines:

  dist.ini:
    # The line that reads:
    filename = lib/Foo/Bar.rakumod
    # is changed to:
    filename = docs/README.rakudoc
    # the following App::Mi6 optional sections are added
    # if not found:
    #   PruneFiles
    #   MetaNoIndex
    #   AutoScanPackages
    #   RunBeforeBuild
    #   RunAfterBuild


  META6.json:
    # The line that begins:
    "description": "blah blah blah",
    # is changed to:
    "description": "[text entered per the 'provides=X' option]

  lib/Foo/Bar.rakumod:
    # Move all lines following the first non-blank line
    # thus leaving:
    unit class Foo::Bar;

  .github/workflows/test.yml:
    # Create three new files to provide three separate test badges
    .github/workflows/linux.yml
    .github/workflows/windows.yml
    .github/workflows/macos.yml
    # Remove the original test.yml file

New directory and file:

  # new directory
  docs/
    # new file:
    README.rakudoc
    # This new file first gets all the lines removed from
    # 'lib/Foo/Bar.rakumod' resulting in a complete pod
    # document:
    =begin pod
       ...
    =end pod
    # Then, four lines are changed:

    # 1. The line that begins:
    Foo::Bar - blah blah blah
    # is changed to either:
    B<Foo::Bar> - [Foo::Bar is bolded, text entered per the 'provides=X' option]
    # or:
    B<Foo::Bar> - blah blah blah [Foo::Bar is bolded]

    # 2. The line that begins:
    Foo::Bar is ...
    # is changed to:
    B<Foo::Bar> is ...

    # 3. The line that begins:
    Copyright {current year} ...
    # is changed to:
    <copyright symbol> {current year} ...

    # 4. The line that reads:
    This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.

AUTHOR

Tom Browder tbrowder@acm.org

CREDITS

The very useful Raku modules used herein:

COPYRIGHT AND LICENSE

© 2020-2023 Tom Browder

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