/ 
Dist-Zilla-Plugin-Rinci-ScriptFromFunc-0.01
/ Dist::Zilla::Plugin::Rinci::ScriptFromFunc

NAME

Dist::Zilla::Plugin::Rinci::ScriptFromFunc - Create or fill out script details from Riap function metadata

VERSION

This document describes version 0.01 of Dist::Zilla::Plugin::Rinci::ScriptFromFunc (from Perl distribution Dist-Zilla-Plugin-Rinci-ScriptFromFunc), released on 2014-08-16.

SYNOPSIS

In dist.ini:

[Rinci::ScriptFromFunc]
script= func=/My/Palindrome/check_palindrome,
script= name=lssrv, func=/My/App/list_servers

After build, bin/check-palindrome and bin/lssrv will be created.

DESCRIPTION

After you add Rinci metadata to your function, e.g.:

package My::Palindrome;
$SPEC{check_palindrome} = {
    v => 1.1,
    args => {
        text => { schema=>'str*', req=>1, pos=>0 },
        ci   => { schema=>'bool*', cmdline_aliases=>{i=>{}} },
    },
    result_naked => 1,
};
sub check_palindrome {
    my %args = @_;
    my $text = $args{ci} ? lc($args{text}) : $args{text};
    $text eq reverse($text);
}

you can create a command-line script for that function that basically is not much more than:

#!perl
use Perinci::CmdLine::Any;
Perinci::CmdLine::Any->new(url => '/My/Palindrome/check_palindrome');

This Dist::Zilla plugin lets you automate the creation of such scripts.

Creating scripts. To create a script, put this in dist.ini:

[Rinci::ScriptFromFunc]
script= func=/My/Palindrome/check_palindrome, abstract=Check if a text is a palindrome

To create more scripts, add more script=... lines. Each script=... line is a script specification, containing comma-separated key=value items. Known keys:

  • func => str

    Riap function URL.

  • name => str

    Name of script to create. Default will be taken from function name, with _ replaced to -.

  • cmdline => str

    Select module to use. Default is Perinci::CmdLine::Any, but you can set this to classic (equals to Perinci::CmdLine), any (Perinci::CmdLine::Any), or lite (Perinci::CmdLine::Lite) or module name.

  • prefer_lite => bool

    If set to 1 and you are using Perinci::CmdLine::Any, -prefer_lite option will be passed in the code.

  • default_log_level => str

    If set, will add this code to the generated script:

    BEGIN { no warnings; $main::Log_Level = "..." }

    This can be used if you want your script to be verbose by default, for example.

  • log_any_app => bool

    Set value in the Perinci::CmdLine object construction code.

  • ssl_verify_hostname => bool (default: 1)

    If set to 0, will add this code to the generated script:

    $ENV{PERL_LWP_SSL_VERIFY_HOSTNAME} = 0;

    This can be used if the Riap function URL is https and you don't want to verify.

Filling out script details. (NOT YET IMPLEMENTED.) You can also create the script manually in bin/, but put this marker at the top of the script:

C<# FROMFUNC: ...>

Where ... contains the same comma-separated key=value items, for example:

C<# FROMFUNC: func=/My/Palindrome/check-palindrome>

What are put in the script. Below are the things put in the script by this plugin:

  • shebang line

    #!perl

    Not added when not creating.

  • # DATE line

    See Dist::Zilla::Plugin::OurDate. Not added if already there.

  • # VERSION line

    See Dist::Zilla::Plugin::OurVersion. Not added if already there.

  • # ABSTRACT line

    Value will be taken from summary property of the Rinci metadata. Not added if already there.

  • # PODNAME line

    Value will be taken from function name, with underscore (_) replaced with dash (-). Not added if already there.

  • Perl code to use the function as a CLI script

    By default it's something like this (some aspects customizable):

    use 5.010001;
use strict;
use warnings;

use Perinci::CmdLine::Any;
Perinci::CmdLine::Any->new(
    url => '/My/Palindrome/check_palindrome',
);

  • Synopsis POD section

    Will display script's usage as well as examples from the examples property in the Rinci metadata, if any. Not added if already there.

  • Description POD section

    Value taken from description property of the Rinci metadata. Not added if already there.

  • Options POD section

    List all the command-line options that the script accepts. Not added if already there.

CONFIGURATION

script => str (multiple allowed)

Specify script to be generated (name, source function, etc). See "DESCRIPTION" for more details.

snippet_* => str

Insert code snippet in various places, for some customization in the process of code generation.

snippet_before_instantiate_cmdline

TODO

  • fatpacker-friendly

    Add 'use MODULE' (if function URL points to local module) so dependencies can be detected more easily (more fatpacker-friendly).

  • logging

    In Synopsis, add an example on how to enable debugging/tracing.

  • completion

    If completion=1, add instruction on how to enable bash completion in Synopsis.

  • link to corresponding module

    Link to corresponding Perl module in See Also (the Version POD section already mentions the dist name though).

  • customize See Also

    Allow specifying links

SEE ALSO

Rinci

Other Dist::Zilla::Plugin::Rinci::* for plugins that utilize Rinci metadata.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Dist-Zilla-Plugin-Rinci-ScriptFromFunc.

SOURCE

Source repository is at https://github.com/sharyanto/perl-Dist-Zilla-Plugin-Rinci-ScriptFromFunc.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Dist-Zilla-Plugin-Rinci-ScriptFromFunc

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Steven Haryanto.

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