NAME

Synapse::CLI::Config - configure and manage your application objects in a terminal

About Synapse's Open Telephony Toolkit

Synapse::CLI::Config is a part of Synapse's Wholesale Open Telephony Toolkit.

As we are refactoring our codebase, we at Synapse have decided to release a substantial portion of our code under the GPL. We hope that as a developer, you will find it as useful as we have found open source and CPAN to be of use to us.

What is Synapse::CLI::Config all about

We strongly believe that prior to building graphical front ends, it is necessary to build a robust and reliable command line interface in order to configure software packages.

The goal of this module is to provide something that will allow you to interact with your application objects and classes using the command line, and make object changes persistent on disk.

SYNOPSIS

Say you create a MyAPP::User object.

Step 1

Make MyAPP::User inherit from Synapse::CLI::Config::Object:

    use base qw /Synapse::CLI::Config::Object/;

Doing this means that your class will inherit Synapse::CLI::Config::Object methods.

Step 2

Write your own methods, for example in MyAPP::User, these could be something in the lines of:

    sub password {
        my $self = shift;
        @_ and $self->{password} = shift;
        return $self->{password};
    }
    
    sub email {
        my $self = shift;
        @_ and $self->{email} = shift;
        return $self->{email};
    }

Create a simple script, say myapp-cli, which declares aliases for your objects and calls the Synapse::CLI::Config::execute() method.

    #!/usr/bin/perl
    # this is myapp-cli. It should be installed in /usr/local/bin/myapp-cli
    use Synapse::CLI::Config;
    use YAML::XS;
    use warning;
    use strict;
    $Synapse::CLI::Config::BASE_DIR = "/etc/myapp";
    $Synapse::CLI::Config::ALIAS->{type} = 'Synapse::CLI::Config::Type';
    $Synapse::CLI::Config::ALIAS->{user} = 'MyAPP::User';
    print Dump (Synapse::CLI::Config::execute (@ARGV));

Step 3, congrats, you've built your own CLI interface!

Now let's create a user and use these fancy methods.

    # create user 'foo' with label 'Foo Bar'
    myapp-cli type user create foo "Foo Bar"
    
    # change password and email
    myapp-cli user foo email example@example.com
    myapp-cli user foo password "very hard to remember"
    
    # view result
    myapp-cli user foo show
    
    # rename foo
    myapp-cli user foo rename bar
    
    # get rid of it now
    myapp-cli user bar remove 
    

API

GLOBALS

$Synapse::CLI::Config::VERSION - library version number

$Synapse::CLI::Config::BASE_DIR - points to the directory where object configuration files live.

$Synapse::CLI::Config::ALIAS - alias => package name mapping.

@Synapse::CLI::Config::BUFFER - where execute() commands are logged prior to flushing() everything to disk.

Synapse::CLI::Config::base_dir()

Returns $BASE_DIR

Synapse::CLI::Config::debug($msg)

Debug hook. Sends messages to STDERR.

Synapse::CLI::Config::parse($file)

Turns a YAML file into a Perl structure and returns it.

Synapse::CLI::Config::dump($file, $scalar)

Turns Perl $scalar (which will most often be a reference) into a YAML file.

Synapse::CLI::Config::execute (@args)

Executes command, and saves it in the corresponding file if object is changed.

For instance:

    $Synapse::CLI::Config::ALIASES->{foo} = "My::Foo";
    Synapse::CLI::Config::execute ("My::Foo", "bar", "baz");

Is like saying:

    My::Foo->new ('bar')->baz();

On the cli it should look like this:

    myapp-cli foo bar baz

EXPORTS

none.

BUGS

Please report them to me. Patches always welcome...

AUTHOR

Jean-Michel Hiver, jhiver (at) synapse (dash) telecom (dot) com

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

cpanm Synapse::CLI::Config

perl -MCPAN -e shell
install Synapse::CLI::Config