/ 
CellFunc-1.0.0
/ CellFunc

NAME

CellFunc - Function that accepts a single value

SPECIFICATION VERSION

1.0

VERSION

This document describes version 1.0.0 of CellFunc (from Perl distribution CellFunc), released on 2024-12-10.

ABSTRACT

This document specifies "cell functions", a specific kind of Perl functions that accept a single value and return a transformed value.

STATUS

Early draft. The 1.0 series does not guarantee full backward compatibility between revisions, so caveat implementor. However, major incompatibility will bump the version to 1.1.

SPECIFICATION

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

  • Function must accept a hash argument %args

    This future-proofs the function when more and more arguments are added.

  • Function must return an enveloped result.

    For xample:

    [200, "OK", 42]

  • Arguments should be described in Rinci metadata

    See Rinci and Rinci::function for more details.

  • There is a required argument: value

    It can be specified with schema str, for example, but actually any kind of schema is allowed. It should also be specified with these properties:

    pos => 0
req => 1

    Default value is optional.

  • Other arguments are allowed and should have good defaults

  • When function fails (i.e. it cannot transform the input value) it should return an error result

    Examples:

    [404, "File not found"]
[400, "Cannot take square root of a negative number"]
[409, "File already exists"]

  • The function should ideally not have side effects. It should just produce a transformed value

  • The function should be named func under the CellFunc::* namespace

A well-written CellFunc function should be readily usable as a CLI or as a transformer in a CLI utility.

An example cell function:

use strict;
use warnings;

package CellFunc::Math::sqrt;

our %SPEC;
$SPEC{'func'} = {
    v => 1.1,
    summary => 'Take square root of a number',
    args => {
        value => {schema => 'ufloat*', req=>1, pos=>0},
    },
};
sub func {
    my %args = @_;
    return [400, "Cannot take square root of a negative number"]
        unless $args{value} >= 0; # an additional check
    [200, "OK", $args{value} ** 0.5];
}
1;

NAMESPACE ORGANIZATION

CellFunc is the specification.

Actual cell functions are put in CellFunc::*, preferrably under suitable subnamespaces named using "CamelCase" style except the last element ("the name of the CellFunc") "lowercase_with_underscore" style.

CellFunc::gen_row::* is a subnamespace for cell functions that generate a "row" (a hashref of scalar values).

FAQ

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/CellFunc.

SOURCE

Source repository is at https://github.com/perlancar/perl-CellFunc.

SEE ALSO

Rinci and Rinci::function, the base specification upon which we built.

RowFunc, like CellFunc but for functions that accept a "row" value.

Unixish, which is a specification for function that consumes and produces "streams" instead of a single value.

Data::Sah::Filter, which lets you define cell function by returning a Perl (or JavaScript, etc) expression to define the function. Used in code generation like in schema generation. Part of the Data::Sah framework.

Utility modules

App::cellfunc lets you call specified a cell function and feed it data.

App::dux for Unixish.

Bridges between us and Data::Sah::Filter: CellFunc::Sah::from_sah_filter and Data::Sah::Filter::perl::CellFunc::from_cellfunc.

Some applications let you specify cell functions or Data::Sah::Filter functions by name to transform data, e.g. orgadb-sel from App::orgadb.

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

% prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2024 by perlancar <perlancar@cpan.org>.

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

BUGS

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

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.