/ 
Database-Format-Text-1.03
River stage zero No dependents
/ Database::Format::Text

NAME

Database::Format::Text - Local database in text format.

VERSION

Version 1.03

SYNOPSIS

Database::Format::Text module is handy tool to create a text based database on local machine. This module will create database in text format, so user can any time open the text file and look at the data. User will be able to do following manipulation on the data base using this module.

  • Add data

  • Delete data

  • Append data

  • Get titles

  • Get data

  • Get whole data base

  • Count entries

To modify the existing entry, delete the existing entry and re-enter the modified entry. Following is the example to use Database::Format::Text

use Database::Format::Text;
my @titles = qw(Number Title Status Comments);

# Create database
my $foo_data_table = Database::Format::Text->new('file_name' => "foo_data", 
						 'fields' => \@titles);
# Add entry
my $status = $foo_data_table->add_entry("1", "Test1", "Pass", "Applicable");

# Delete entry
$status = $foo_data_table->delete_entry("Status", "Pass");

# Get entry
my @data = foo_data_table->get_entry("Number", 7);
# or
$status = foo_data_table->get_entry("Number", 7, "Status");

# Get database
my @database = $foo_data_table->get_table();

# Count entries
$status = $foo_data_table->count_entry("Status", "Pass");

# Get titles
@database = $foo_data_table->get_titles();

You can use this module at many places. Example : If you are a test engineer and you need to perform some test cases on your product this data base will help to store your records. It is in text based format so you can copy this data base in your archive for future reference.

SUBROUTINES

new

Creates and returns a new Database::Format::Text object.

my @titles = qw(Number Title Status Comments [ . . .]);
					# User can add N number of columns here.
my $foo_data_table = Database::Format::Text->new('file_name' => "foo_data", 
						 'fields' => \@titles);

Constructor needs 2 parameters. Without above 2 parameters program will die. 2 parameters are file name and titles for database. File name is required to store the database. Fields are titles of the column of your database. In above example user will create a database in text format in file "foo_data". Which will have 4 columns. Columns would be Number, Title, Status and Comments.

Here are the parameters that Database::Format::Text recognizes. These are optional.

  • 'location' => '/your/folder/to/store/database'

    This variable will store the folder location. Database::Format::Text module will create a database in text format in above mentioned location or if above parameter is not defined then it will store database in current working directory.

  • 'delimiter' => '|'

    Database will have many fields. Each field is divided by delimiter. Use this variable to specify the delimiter of your database. If this is not supplied, Database::Format::Text will use ':' as the delimiter.

  • 'append' => [0|1]

    If you want to create a single database and run your perl program multiple times on the same database then use this variable. If it is enabled the database will append the new records. If this is disabled Database::Format::Text will delete old database and and create a new database.

  • 'column_width' => 20

    Based on your data select this variable. Above example will create 20 width column for each of the entry.

  • 'die' => [0|1]

    During many sanity tests Database::Format::Text will die your program if any failure. If you want to continue without dyeing, enable this variable.

$foo_data_table->add_entry(@data_records)

This method will create an actual data entry into your database. This method takes list of data. In our example we have 4 columns; Number, Title, Status and Comments. Therefore our data to be entered is 4. For example it is 1, Test1, Pass and Applicable.

my @data_records = ("1", "Test1", "Pass", "Applicable");
$foo_data_table->add_entry(@data_records);

This database will have an entry with above data. If this method creates the entry, it will return 0.

$foo_data_table->delete_entry($title, $record)

After creating database, if you need to remove one entry from your database, use this method to remove entry. It takes 2 arguments. One is title. You can remove entry using any title. In our example I will remove entry using title "Status". 2nd argument is actual record itself. In our example I would like remove entries with record as Pass. I will use below code as my example.

my $status = $foo_data_table->delete_entry("Status", "Pass");

This code will search pattern "Pass" under "Status" in your database and remove all matched entries. This method will return number of removed entries. If it did not find above pattern in your database, it will return 0. If it finds multiple entries, this method will erase all matched entries. In above example if this method finds 5 data as "Passing" under column "Status", method will delete all 5 entries and return 5.

$foo_data_table->count_entry($title, $record)

After creating database, if you need to count number of entries for specific record, use this method. In above example if you want to count how many test are passed use this method. It takes 2 arguments. One is title. You can find entry using any title. In our example I will count entry using title "Status". 2ns argument is actual record. In our example I would like count entries with record as Pass. I will use below code as my example.

my $status = $foo_data_table->count_entry("Status", "Pass");

This code will search pattern "Pass" under "Status" in your database and count all matched entries. This method will return number of matched entries. If it did not find above pattern in your database, it will return 0.

$foo_data_table->get_entry($title, $record, [$title_of_needed_data])

After creating database, if you need to get a particular entry from the database use this method. This method will take 3 arguments. 1st argument is title. For example you want to get entry for column "Number". Use "Number as your 1st arguement. 2nd arguement will be record. For example you want to get entry for Column "Number" with "7". Use "7" as your 2nd arguement. In our example this method will go to database and get complete entry for the column "Number" == "7". This will return as a list. List will contain all the record of column "Number" with 7. If it finds multiple entries, this method will fetch all and return to you as a list.

my @data = foo_data_table->get_entry("Number", 7);

If we need only specific data then also specify 3rd arguement, which is title to be needed. For example If you want "Status" of "Number" == "7". Use title "Status as your 3rd arguement. This will retun a scalar value. This will be 1st matched pattern. If you have multiple entries pass only 2 arguments as above.

my $status = foo_data_table->get_entry("Number", 7, "Status");

This will return value stored under "Status" whose "Number" is 7.

$foo_data_table->get_table()

This method does not take any arguments. This method will return complete database in list.

my @database = $foo_data_table->get_table();

$foo_data_table->get_titles()

This method does not take any arguments. This method will return all the titles of the database.

my @database = $foo_data_table->get_titles();

AUTHOR

Devang Doshi, <devdos at cpan.org>

BUGS

Please report any bugs or feature requests to bug-database-format-text at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Database-Format-Text. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Database::Format::Text

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2013 Devang Doshi.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.