# ==================================================================
# Links SQL - enhanced directory management system
#
#	Website  : http://gossamer-threads.com/
#	Support  : http://gossamer-threads.com/scripts/support/
#	Revision : $Id: Text.pm,v 1.14 2004/05/04 00:50:09 jagerman Exp $
#
# Copyright (c) 2001 Gossamer Threads Inc.  All Rights Reserved.
# Redistribution in part or in whole strictly prohibited. Please
# see LICENSE file for full details.
# ==================================================================

package Links::Import::Interface::Text;
# ==================================================================

use vars qw/%IMPORT_OPT_MAP/;

use strict;
use Getopt::Long;

%IMPORT_OPT_MAP = (
    LINKSSQL1 => 'S1S2',
    LINKSQL1  => 'S1S2',
    LINKS1    => 'L1S2',
    LINKS2    => 'L2S2',
    S1        => 'S1S2',
    L2        => 'L2S2',
    L1        => 'L1S2',
    LINKS     => 'L2S2',
    RDF       => 'RDFS2',
    DMOZ      => 'RDFS2'
);

sub new {
    my $this = shift;
    my $class = ref($this) || $this;
    my $self = { };
    bless $self, $class;
    return $self;
    $self->_init();
}

sub get_options {
    my $self = shift;
    my %option = ();
    my ($backup,$restore,$import);
    GetOptions(
        "backup" => \$backup,
        "restore" => \$restore,
        "import=s" => \$import,
        "source=s" => \$option{source},
        "destination=s" => \$option{destination},
        "help" => \$option{help},
        "error-file=s" => \$option{error_file},
        "critical-warnings" => \$option{critical_warnings},
        "mild-warnings" => \$option{show_mild_warnings},
        "data-integrity" => \$option{data_integrity},
        "create-columns" => \$option{create_columns},
        "create-missing-categories" => \$option{create_missing_categories},
        "clear-tables" => \$option{clear_tables},
        "straight-import" => \$option{straight_import},
        "rdf-category=s" => \$option{rdf_category},
        "rdf-destination=s" => \$option{rdf_destination},
        "rdf-add-date=s" => \$option{rdf_add_date},
        "with-gzip=s" => \$option{with_gzip},
        "rdf-update" => \$option{rdf_update},
        "rdf-user=s" => \$option{rdf_user},
        "xml-parser!" => \$option{xml_parser}
    );
    $option{transfer} = $IMPORT_OPT_MAP{uc $import} || "";
    unless ($option{from} or $option{to} or $option{source} or $option{destination}) {
        return wantarray ? () : {};
    }
    if (($backup and $restore) or ($backup and $option{transfer}) or ($restore and $option{transfer})) {
        delete $option{transfer}; # Two options provided!
    }
    elsif ($backup) {
        $option{transfer} = "S2BK";
    }
    elsif ($restore) {
        $option{transfer} = "BKS2";
    }
    return wantarray ? %option : \%option;
}

sub start_page {
    show_help(@_);
}

sub show_help {
    my $self = shift;
    print <<HELP;

Links SQL 2 Importer/Exporter

Usage:

perl $0 {--backup|--restore|--import type} --source=<source>
        --destination=<destination> [any others of the following options]

Options are (options may be simplified to uniqueness):

(One of the following three is required)
    --import Links1|Links2|LinksSQL1|RDF
        Will do an import from the chosen source.

    --backup
        This option will perform a Links SQL 2 backup.

    --restore
        This option will return from a Links SQL 2 backup file created
        with --backup.

    --source=<input_source> (required)
        Sets according to the following:
        --import Links1|Links2
            the path of the def and db files
        --import LinksSQL1
            the path of the def files
        --import RDF
            the path and filename of the RDF file to import from.
            Note that if the file ends in .gz, the import will attempt to run
            it through gzip decompression trying several standard locations for
            gzip. You may specify a location for gzip using the --with-gzip
            option.
        --restore
            the path and filename of the backup file created with --backup
        --backup
            the path of the Links SQL 2 def files

    --destination=<output_dest> (required)
        Sets according to the following:
        --import Links1|Links2|LinksSQL1|RDF
        --restore
            the path of the Links SQL 2 def files
        --backup
            the path and filename of a file to use for the Links SQL 2 backup.

    --error-file="./error/errors.txt" (not required)
        Sets a file to which all import errors will be written. If you set it
        to STDOUT, or if it is not set, it will write all errors to standard
        output (STDOUT) prepended with "IMPORT ERROR: ".
    
    --critical-warnings
        Makes import warnings become fatal errors. Note that relatively minor
        warnings such as not having enough information to create a new user for
        a link (therefore setting the link to be owned by admin) are not
        promoted to fatal errors.

    --mild-warnings
        Displays mild import warnings. Mild warnings are those that affect a
        relatively minor portion of the script. Note that mild warnings will
        NOT cause the script to abort, even if the --critical-warnings option
        has been enabled.
    
    --data-integrity
        Makes the import check every category before inserting it to insure
        that there are no duplicates. Note that this option will make the
        import take much longer to complete as each and every category will
        have to be checked to see if it exists. This option is only recommended
        if you suspect that your data might contain duplicate categories. It
        only works when importing data to a Links SQL 2 database from Links
        1.x, Links 2.x, or Links SQL 1.x (NOT when backing up, restoring, or
        importing from an RDF).

    --create-columns
        Makes the import attempt to create any columns which are in the source
        tables, but NOT in the destination tables. That is, custom tables will
        be imported into the new Links database. Without this option, existing
        tables that do not exist in the destination format will cause a
        warning. If this feature is enabled, a mild warning will occur whenever
        a table does not exist and is being created.

    --clear-tables
        (This option is required to use --restore, but optional for --backup
         and all imports)
        Makes the current Links SQL tables be cleared (except for the admin
        user in the Users table) before doing the import. Only takes effect
        when importing to Links SQL 2. This option allows you to use the
        --straight-import option below.

    --straight-import
        (This option can only be used with --clear-tables).
        Makes the import not recalculate Category/Link ID numbers. That is, a
        link with ID number 12 in the source will be inserted into the Links
        SQL 2 database with an ID number of 12. Note that this can leave a
        fairly large gap in the Links ID fields depending on the usage of the
        source import. This option does nothing with --backup and --restore

    --create-missing-categories
        Used with an import. Categories are "missing" when they are required
        for the database to be complete but do not exist. For example, if 
        category A/B/C existed in the database but A and A/B did not, then both
        A and A/B would be considered "missing" and would be automatically
        created if this option is enabled. For Links 1.x and 2.x imports, this
        will also make the import attempt to create categories that are
        required for links. For example, if a link exists and thinks it is in
        category A/B/C but A/B does no exist, A/B and A/B/C will be created to
        allow the link to be imported.

    --rdf-category="Top/Category/Name"
        (This option can only be and must be used with `--import RDF')
        Specifies the RDF category to import such as "Top/Business".

    --rdf-destination="Links SQL2/Category/Name"
        (This option can only be used with `--import RDF')
        Specifies a Links SQL 2 category to import the data to. For example,
        "My Business Links" would import the RDF category specified with
        --rdf-category into the "My Business Links" category. If this is not
        specified (or specified as "/" or "") the import will be done into the
        Links SQL category root.

    --with-gzip="/path/to/gzip"
        (This option can only be used with `--import RDF')
        Specifies the location of gzip. This option is only needed if the RDF
        file has been compressed with gzip (the file will end with ".gz") and
        the import is unable to locate gzip on its own.

    --rdf-update
        (This option can only be used with `--import RDF')
        Specifies that the import should check to see that categories and links
        do not already exist. For an initial RDF import, this option is not
        needed, however to update a previous RDF import you MUST use this
        option; failing to do so would result in duplicate categories and links
        appearing. It is not recommended that you use this option when
        performing an initial import from an RDF as it will increase the import
        time considerably.

    --rdf-user="Username"
        (This option can only be used with `--import RDF')
        Specifies a user who all new links should belong to. The user MUST
        already exist in the Links SQL Users table. If not specified, all links
        will have `admin' as the LinkOwner. Note that if the --clear-tables
        option is specified, this user will also be preserved when all tables
        are wiped.

    --rdf-add-date="2001-01-05"
        (This option can only be used with `--import RDF' and is required)
        This sets the date that new link links should have their `Add_Date' and
        `Mod_Date' fields set to. This should be in the format `YYYY-MM-DD'.
        NOTE: You should NOT set this to a very recent date as all links would
        then show up as "New" links.

    --help
        Displays this screen

HELP

# Understood, but often fails as RDF files are commonly malformed:
#
#    --xml-parser
#        (This option can only be used with `--import RDF')
#        Attempts to use the new XML::Parser-based code for importing the RDF
#        file.  Although much faster, it requires that the XML::Parser module be
#        installed, and should be considered an experimental feature.
}

sub pre_import () { }

sub usage ($$;$) {
    my $self = shift;
    $self->{usage_list} = [ ] unless exists $self->{usage_list};
    my $message = "";
    if (@_) {
        $message = shift() . ".";
        $message .= " See " . shift() . " and --help" if @_;
    }
    push @{$self->{usage_list}}, $message if $message;
}

sub has_usage {
    my $self = shift;
    return ref($self->{usage_list}) ? scalar @{$self->{usage_list}} : undef;
}

sub show_usage {
    my $self = shift;
    for (@{$self->{usage_list}}) { print <<USAGE }


Incorrect usage.

$_

USAGE
}

sub finished () {
    my $self = shift;
    print "\n\nImport completed successfully\n";
    exit;
}

"Apparently, I'm true";
