view release on metacpan or  search on metacpan

Appgen.pm  view on Meta::CPAN

# Moving to the given record. Creating it if "create" argument given.
#
sub seek ($%)
{ my $self=shift;
  my $args=get_args(\@_);
  my $key=$args->{key} || '';
  my $rc;
  if($args->{create})
   { $rc=ag_db_newrec($$self,$key,$args->{size} || 0);
   }
  else
   { $rc=ag_db_read($$self,$key,$args->{lock} || 0);
   }
  $rc==-1 ? 0 : 1;
}

##
# Commiting changes to the record
#
sub commit ($)
{ my $self=shift;
  my $rc=ag_db_write($$self);
  $rc==0 || throw Error::Simple ref($self)."::commit - $!";
  1;
}

##
# Releasing current record and its lock.
#
sub release ($)
{ my $self=shift;
  my $rc=ag_db_release($$self);
  $rc==0 || throw Error::Simple ref($self)."::release - $!";
  1;
}

##
# Deleting current record.
#
sub drop ($)
{ my $self=shift;
  my $rc=ag_db_delrec($$self);
  $rc==0 || throw Error::Simple ref($self)."::drop - $!";
  1;
}

##
# Moving to next record
#
sub next ($%)
{ my $self=shift;
  my $args=get_args(\@_);
  ag_readnext($$self,$args->{lock} || 0);
}

##
# Number of attributes
#
sub attributes_number ($)
{ my $self=shift;
  ag_db_stat($$self,-1,-1);
}

##
# Number of values
#
sub values_number($%)
{ my $self=shift;
  my $args=get_args(\@_);
  my $attr=$args->{attribute} || $args->{attr} || 0;
  ag_db_stat($$self,$attr,-1);
}

##
# Length of field
#
sub value_length ($%)
{ my $self=shift;
  my $args=get_args(\@_);
  my $attr=$args->{attribute} || $args->{attr} || 0;
  my $value=$args->{value} || $args->{val} || 0;
  ag_db_stat($$self,$attr,$value);
}

##
# Deletes value
#
sub delete ($%)
{ my $self=shift;
  my $args=get_args(\@_);
  my $attr=$args->{attribute} || $args->{attr} || 0;
  my $value=$args->{value} || $args->{val} || 0;
  my $rc=ag_delete($$self,$attr,$value);
  $rc==0 || throw Error::Simple ref($self)."::delete - $!";
  1;
}

##
# Extracts value
#
sub extract ($%)
{ my $self=shift;
  my $args=get_args(\@_);
  my $attr=$args->{attribute} || $args->{attr} || 0;
  my $value=$args->{value} || $args->{val} || 0;
  ag_extract($$self,$attr,$value,$args->{size} || 0);
}

##
# Inserts value
#
sub insert ($%)
{ my $self=shift;
  my $args=get_args(\@_);
  my $attr=$args->{attribute} || $args->{attr} || 0;
  my $value=$args->{value} || $args->{val} || 0;
  my $rc=ag_insert($$self,$attr,$value,$args->{text} || '');
  $rc==0 || throw Error::Simple ref($self)."::insert - $!";
  1;
}

##
# Inserts value
#
sub replace ($%)
{ my $self=shift;
  my $args=get_args(\@_);
  my $attr=$args->{attribute} || $args->{attr} || 0;
  my $value=$args->{value} || $args->{val} || 0;
  my $rc=ag_replace($$self,$attr,$value,$args->{text} || '');
  $rc==0 || throw Error::Simple ref($self)."::replace - $!";
  1;
}

##
# Reads entire attribute returning array of all values even if only one
# exists. Values are numbered from 0, not form 1, be careful!
#
# Returns array reference or array itself in array context.
#
sub attribute ($%)
{ my $self=shift;

Appgen.pm  view on Meta::CPAN

=head2 $db->rewind;

=head2 ag_db_rewind(*db);

Re-positions I<current record> pointer to the first record in file.

=head2 $db->unlock;

=head2 ag_db_unlock($db);

Unlocks database.

=head1 RECORD LEVEL METHODS

=head2 $db->seek(key => "key", lock => 1);

=head2 ag_db_read($db, "key", $lock);

Attempts to find and, if specified, lock the record by given key. Moves
I<current record> on success. In case of of error current record is not
defined.

=head2 $db->commit;

=head2 ag_db_write($db)

Writes changes made to the current record to the database.

=head2 $db->release;

=head2 ag_db_release($db);

Unlocks I<current record> if it is locked; I<current record> becomes
undefined.

=head2 $db->seek(key => "key", create => 1, size => $size);

=head2 ag_db_newrec($db, "key", $size);

Finds and locks existing records or creates new one. Size can be set to
the total record size in bytes if you know it, otherwise do not supply
it at all.

=head2 $db->drop;

=head2 ag_db_delrec

Deletes I<current record> which must be locked.

=head2 $db->next(lock => 1);

=head2 ag_readnext($db);

Moves I<current record> to the next record in the database in random
order locking it if required. Returns key text or undef if no more
records exist.

=head1 FIELD LEVEL METHODS

=head2 ag_db_stat($db, $attr, $value);

This method determines the size and composition of a field in the
I<current record>. Consult appgen documentation for details.

A number of methods exists to get the same functionality in more
straight forward way:

=over

=item $db->attributes_number;

Returns number of attributes in the I<current record>.

=item $db->values_number(attribute => $attr);

Returns number of values in the given attribute of the I<current record>.

=item $db->value_length(attribute => $attr, value => $value).

Returns length of the given value in the given attribute of the
I<current record>. If value is not set or is zero then length of entire
attribute is returned (for multi-valued attributes this includes value
separators).

=back

=head2 $db->delete(attribute => $attr, value => $value);

=head2 ag_delete($db,$attr,$value);

Deletes given value or attribute in its entirety if no value number is
given. Attributes or values after deleted one are renumbered to fill the
gap, be careful.

=head2 $db->extract(attribute => $attr, value => $value, size => $size);

=head2 ag_extract($db,$attr,$value,$size);

Returns the content of the given value or the given attribute if value
is zero. Size is not required, by default entire string is returned.

=head2 $db->insert(attribute => $attr, value => $value, text => $text);

=head2 ag_insert($db,$attr,$value,$text);

Inserts new field into the I<current record>. If there is already a
field at $attr/$value it is renumbered one higher.

=head2 $db->replace(attribute => $attr, value => $value, text => $text);

=head2 ag_replace($db, $attr, $value, $text);

Replaces the field pointed to by attribute and value. Any fields between
the end of the I<current record> and the specified field will be created
if required.

=head1 SUPPORTING METHODS

=head2 $db->attribute(attribute => $attr);