SYNOPSIS
In list_countries.pl:
#!perl
use strict;
use warnings;
use Perinci::CmdLine;
use Perinci::Sub::Gen::AccessTable qw(gen_read_table_func);
our %SPEC;
my $countries = [
['cn', 'China', 'Cina', [qw/panda/]],
['id', 'Indonesia', 'Indonesia', [qw/bali tropical/]],
['sg', 'Singapore', 'Singapura', [qw/tropical/]],
['us', 'United States of America', 'Amerika Serikat', [qw//]],
];
my $res = gen_read_table_func(
name => 'list_countries',
summary => 'func summary', # opt
description => 'func description', # opt
table_data => $countries,
table_spec => {
summary => 'List of countries',
fields => {
id => {
schema => 'str*',
summary => 'ISO 2-letter code for the country',
pos => 0,
sortable => 1,
},
eng_name => {
schema => 'str*',
summary => 'English name',
pos => 1,
sortable => 1,
},
ind_name => {
schema => 'str*',
summary => 'Indonesian name',
pos => 2,
sortable => 1,
},
tags => {
schema => 'array*',
summary => 'Keywords/tags',
pos => 3,
sortable => 0,
},
},
pk => 'id',
},
);
die "Can't generate function: $res->[0] - $res->[1]" unless $res->[0] == 200;
Perinci::CmdLine->new(url=>'/main/list_countries')->run;
Now you can do:
# list all countries, by default only PK field is shown
$ list_countries.pl --format=text-simple
cn
id
sg
us
# show as json, randomize order
$ list_countries.pl --format=json --random
["id","us","sg","cn"]
# only list countries which are tagged as 'tropical', sort by ind_name field in
# descending order, show all fields (--detail)
$ list_countries.pl --detail --sort -ind_name --tags-has '[tropical]'
.---------------------------------------------.
| eng_name | id | ind_name | tags |
+-----------+----+-----------+----------------+
| Singapore | sg | Singapura | tropical |
| Indonesia | id | Indonesia | bali, tropical |
'-----------+----+-----------+----------------'
# show only certain fields, limit number of records, return in YAML format
$ list_countries.pl --fields '[id, eng_name]' --result-limit 2 --format=yaml
- 200
- OK
-
- id: cn
eng_name: China
- id: id
eng_name: Indonesia
DESCRIPTION
This module is useful when you want to expose a table data (an array of
hashrefs, an array of arrays, or external data like a SQL table) as an
API function. This module will generate a function (along with its
Rinci metadata) that accepts arguments for specifying fields,
filtering, sorting, and paging. The resulting function can then be run
via command-line using Perinci::CmdLine (as demonstrated in Synopsis),
or served via HTTP using Perinci::Access::HTTP::Server, or consumed
normally by Perl programs.
CAVEATS
It is often not a good idea to expose your database schema directly as
API.
FAQ
I want my function to accept additional arguments.
You can use the extra_args argument:
gen_read_table_func(
name => 'myfunc',
extra_args => {
foo => {schema=>'int*'},
bar => {summary => 'Yet another arg for myfunc', schema=>'str*'},
},
);
As for the implementation, you can specify hooks to do things with the
extra arguments.
SEE ALSO
Rinci
Perinci::CmdLine