The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-riap-0.34
River stage one • 1 direct dependent • 1 total dependent
1 ++
/ riap

NAME

riap - Riap command-line client shell

VERSION

version 0.34

SYNOPSIS

 % riap --help
 % riap [opts] <uri>

Invoking:

 # URI defaults to 'pl:/', which is the local Perl realm
 % riap

 # ditto, but specify initial "pwd"
 % riap /Calendar/Indonesia/Holiday
 % riap pl:/Calendar/Indonesia/Holiday

 # access remote API starting point
 % riap https://cpanlists.org/api/
 % riap http://gudangapi.com/ga/

An example session:

 riap> pwd
 /

 riap> cd /spanel/api

 riap> ls
 account/
 disk_usage/
 mysql/
 pgsql/
 plan/
 ...

 riap> cd account/shared/query

 riap> pwd
 /spanel/api/account/shared/query

 riap> ls -l
 create_account     function
 delete_accounts    function
 suspend_account    function
 unsuspend_account  function

 # execute a Riap function like it is an executable program
 riap> list_accounts --nodisabled --nomigrated
 andi
 budi
 jamal
 titin
 ujang

 riap> ../modify/delete_account --help

 riap> exit

DESCRIPTION

A Riap client in the form of a simple interactive command-line shell (as opposed to Perinci::Access which is a Perl library, or peri-run and peri-access which are non-interactive command-line interface). Provides a convenient way to explore API services which use the Riap protocol or explore Perl modules which have Rinci metadata.

Example API services that you can (or will be able to) test this with:

Example Perl libraries you can test this with (you need to install them first): Text::sprintfn, Git::Bunch, Calendar::Indonesia::Holiday, Perinci::Examples. Try to search for CPAN distributions which specify Rinci as their prerequisites.

Within the shell, you can browse packages and functions as if they were directories and executable files (using commands like cd, ls, pwd). You can call functions like they were command-line programs, by passing command-line parameters for function arguments.

See "COMMANDS" for list of known commands.

OPTIONS

  • --help

    Show short help message.

  • --user=S

    Supply HTTP authentication user. You can also set this via environment PERINCI_HTTP_USER (see Perinci::Access for more details) or from inside the shell via set user <S>.

  • --password=S

    Supply HTTP authentication password. You can also set this via environment PERINCI_HTTP_PASSWORD (see Perinci::Access for more details) or from inside the shell via set password <S>.

    Using the command-line option is not recommended because of security issue (command-line commands/arguments are usually visible to all users on the system via commands like ps).

COMMANDS

help [command]

Display help message.

exit

pwd

Print the current directory (package). When you first enter the shell, current directory is set to /.

cd [path]

Change directory (package). You can use relative notation (../foo) like in a Unix filesystem.

doc <path>

Perform meta Riap request and format the result as text.

ls [options] [path ...]

List of content of directory (package) or other code entities by performing list Riap request. If path is not specified, will list the current directory (package).

Options:

  • --long (-l)

    Add detail => 1 to the Riap request, which will return more details.

list

Alias for ls.

info [path]

Perform info Riap request on an entity at path.

request [options] <action> <path> [extra]

Perform Riap request to a code entity at path. Extra request keys can be specified in extra.

Examples:

 riap> request call /Package/Sub/somefunc '{"args":{"a":1, "b":2}}'
 riap> request list /Package/Sub/somefunc '{"detail":1}'

call [options] <path> [args]

Perform call Riap request. Note that call command is actually optional: the shell performs call requests by default on paths.

Examples:

 riap> call /Package/Sub/somefunc '{"foo":1, "bar":2}'

which is equivalent to:

 riap> /Package/Sub/somefunc --foo 1 --bar 2

set <name> <value>

If invoked without any argument, will list all known settings. If name is specified but value is not, will show value for that particular setting. If name and value is both specified, will set a setting's value.

SETTINGS

Settings are configuration and regulate how the shell behaves.

user => str

For HTTP authentication.

password => str

For HTTP authentication.

output_format => str (default: text)

Set output format for command results. The same formatting is used by Perinci::CmdLine. See that module or Perinci::Result::Format for more details.

debug_riap => bool (default: 0)

Whether to show raw Riap requests and responses being sent to/received from the server.

debug_completion => bool (default: 0)

Whether to show debugging information when doing tab completion.

debug_time_command => bool (default: 0)

Whether to show how long a command takes.

cache_period => int (default: 300)

Number of seconds to cache Riap results from server, to speed up things like tab completion.

FAQ

The prompt looks rather garbled (e.g. extra " m >" character)!

It looks to be an issue with Term::ReadLine::Perl. Try installing Term::ReadLine::Gnu instead.

How do I redirect output to files?

riap is meant to be a simple shell, not a full-blown Unix shell. Besides, a syntax like this:

 riap> call /Package/Sub/somefunc > /path/to/file

will be confusing since paths map to code entity URIs in riap, not filesystem paths.

But something like a setting might be implemented if this is a popular feature request.

What about variables, aliases, looping, or $other_Unix_shell_feature?

Again, riap is meant to be a simple shell, not a full-blown Unix shell. To do those things, you are better off using peri-run or peri-access and incorporate them in a Unix shell script. For example you can write these two short scripts:

 # list-accounts
 #!/bin/sh
 peri-access call https://yourservice.com/api/Account/list

 # delete-account (input sanitizing is left as exercise for the readers)
 #!/bin/sh
 peri-access call "https://yourservice.com/api/Account/delete?account=$1"

and then write:

 # delete all accounts
 for a in `list-accounts`; do
     delete-account "$a"
 done

ENVIRONMENT

PERINCI_HTTP_USER => str

If set, can be used to set user setting (but priority lower than command-line option --user).

PERINCI_HTTP_PASSWORD => str

If set, can be used to set password setting (but priority lower than command-line option --password). This is usually more secure to use than command-line option, because command-line option is usually visible from all users on the system via commands like ps.

RIAP_HISTFILE => str (default: ~/.riap_history)

Specify location of command history file. Like in shells, can be set to empty string to disable history loading/saving.

RIAPRC => str (default: ~/.riaprc)

Specify location of settings file.

FILES

~/.riap_history

Command history file.

~/.riaprc

Settings file (IOD format).

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by 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.