#!/usr/bin/perl

# This is a program that generates Captrap's "view" information pages.

# Copyright 2009 Corey Hickey


# This file is part of Captrap.
#
# Captrap is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Captrap is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Captrap.  If not, see <http://www.gnu.org/licenses/>.


=head1 NAME

captrap_view - a command-line program for generating Captrap "view" pages

=head1 SYNOPSIS

captrap_view [OPTION] [OPTION-PARAMETERS]

=head1 DESCRIPTION

This program will generate an HTML page with tables from Captrap's database
and/or hyperlinks to graphs, and is primarily useful for testing. For general
use, captrap_recurse or Captrap's CGI programs may be better suited.

=head1 OPTIONS

=over

=item -help

Print brief usage text.

=item -list-parameters

Print a list of valid parameters.

=item -write FILE PARAMETERS

Write a view to a file, unless the file already exists. To write to stdout,
specify the file as '-' (if you really want to create a file named '-', specify
'./-'). The filename must be followed by a list of parameters in the usual URL
form (as in param1=value1&param2=value2). Be sure to surround the parameters
with single-quotes if necessary, to avoid having the shell interpret the
ampersands.

=back

=head1 EXIT STATUS

=over

=item 0Z<>

Everything is ok.

=item 1Z<>

No arguments given; usage information was shown.

=item 2Z<>

Invalid argument.

=item 3Z<>

There was a problem executing an action.

=back

=head1 FILES

=over

=item /etc/captrap/captrap.conf

The main Captrap configuration file.

=back

=head1 EXAMPLES

=over

=item Write a basic view to a file:

captrap_view -write basic.html "views=basic"

=item View the basic information (requires lynx):

captrap_view -write - "views=basic" | lynx -stdin

=back

=head1 AUTHOR

Corey Hickey <bugfood-c@fatooh.org>

This program is free software; you may redistribute and/or modify it under the
terms of the GNU General Public License, version 3. See the source file for the
usual GPL preamble and the COPYING file for a copy of the GPL.

=head1 SEE ALSO

captrap_graph, captrap_main, captrap_recurse

The documentation included in the Captrap source archive has more information
on setup and general usage.

=cut


use strict;
use warnings FATAL => 'all';

# for development using a different Captrap module
use lib "lib";
use Captrap qw(:cgi :misc :actions :args :config :db);
use Captrap::View qw(:view :param);

# -----------------------------------------------------------------------------
# printing
# -----------------------------------------------------------------------------

# print main help info
sub usage {
  my $common = shift; # unused
  my $actions = mk_actions();
  my $actions_text = describe_actions($actions);
  print "
This is a script for writing Captrap views to files. For full usage
information, see the man page and/or documentation provided in the Captrap
source archive.

captrap_view [ACTION] [[ACTION-PARAMETERS]] ...

ACTIONS

$actions_text
"
}


# list all parameters
sub list_params {
  my $common = shift;
  my $param_info = mk_param_info();
  arg_list_params($param_info);
}


# list all views
sub list_views {
  my $common = shift;
  my $views = mk_view_info();
  print STDERR "Supported Views\n\n";
  print STDERR "Multiple views can be retrieved in the same request by\n" .
      "joining them with a comma. For example: \"views=basic,adv\"\n\n\n";
  print STDERR "--- Regular Views ---\n\n";
  foreach my $view (keys %$views) {
    print STDERR "$view:\n";
    print STDERR "$views->{$view}->{txt}\n\n";
  }
  print STDERR "\n\n";
  print STDERR "--- Meta-views ---\n\n";
  print STDERR "all:\n";
  print STDERR "all supported views (slow, useful for debug)\n\n";
  print STDERR "list:\n";
  print STDERR "this list of views\n\n";
}


# -----------------------------------------------------------------------------
# view writing
# -----------------------------------------------------------------------------

# open a file and write views to it
sub do_write {
  my $common = shift;
  my $file = shift;
  my $params = shift;
  my $param_info = mk_param_info();
  arg_handle_params($common, $param_info, \&arg_mk_view, $params, $file);
  # If we get here, it worked; otherwise, we've already exited.
  # So, return 0 to signify an action that ran ok.
  return 0;
}


# use provided cgi parameters to call the view subroutine
sub arg_mk_view {
  my $common = shift; # hash ref
  my $params = shift; # hash ref
  my $file = shift;
  return write_output_to_file($common, $params, $file, \&mk_views, undef);
}

# -----------------------------------------------------------------------------
# actions info
# -----------------------------------------------------------------------------

# return a hash of action info
sub mk_actions {
  my $actions = mk_ixhash();
  %$actions = (
    "-help" => {
      func => \&usage,
      args => [],
      desc => "
          Print this usage text.
      ",
    },
    "-list-parameters" => {
      func => \&list_params,
      args => [],
      desc => "
          Print a list of valid parameters.
      ",
    },
    "-list-views" => {
      func => \&list_views,
      args => [],
      desc => "
          Print a list of supported views.
      ",
    },
    "-write" => {
      func => \&do_write,
      args => [ qw(FILE PARAMETERS) ],
      desc => "
          Write a view to a file, unless the file already exists.
      ",
    }
  );
  return $actions;
}

# ----------------------------------------------------------------------------
# parse the arguments and take actions
if (! @ARGV) {
  usage();
  exit(1);
}
my $actions = mk_actions();
check_args(\@ARGV, $actions);

my $config = parse_config();
my $common = {
  cgi => mk_cgi(),
  config => $config,
  dbh    => mk_dbh($config),
};

do_args($common, \@ARGV, $actions);

$common->{dbh}->disconnect();
exit(0);