WWWWWW

Current Directory: /home/.cpanm/work/1729881454.851640/HDB-1.05/blib/man3
Viewing File: /home/.cpanm/work/1729881454.851640/HDB-1.05/blib/man3/HDB::CMDS.3pm
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "HDB::CMDS 3"
.TH HDB::CMDS 3 "2004-12-14" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HDB::CMDS \- Hybrid DataBase Commands
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This are the commands/methods to access/manage the databases.
.SH "select"
.IX Header "select"
Make a \s-1SQL\s0 select query.
.PP
Example:
.PP
.Vb 1
\&  my @sel = $HDB\->select(\*(Aqusers\*(Aq , \*(Aqname =~ joe\*(Aq , \*(Aq@%\*(Aq) ; ## table , where , return
\&  
\&  ## ... or ...
\&  
\&  my @sel = $HDB\->select(\*(Aqusers\*(Aq , \*(Aqname =~ joe\*(Aq , cols => \*(Aqname,user,id\*(Aq , limit => 1 , \*(Aq@%\*(Aq) ;
\&  
\&  ## ... or ...
\&  
\&  my @sel = $HDB\->select(
\&  table  => \*(Aqusers\*(Aq ,           ## Need to start with \*(Aqtable\*(Aq to paste a full HASH of arguments!
\&  where  => \*(Aqname == joe\*(Aq ,
\&  col    => \*(Aqname, user , id\*(Aq ,
\&  limit  => \*(Aq1\*(Aq ,
\&  sort   => \*(Aqid\*(Aq ,
\&  group  => \*(Aqname\*(Aq ,
\&  cache  => \*(Aq0\*(Aq ,
\&  return => \*(Aq@%\*(Aq ,  
\&  ) ;
.Ve
.PP
\&\fBArguments:\fR
.IP "\s-1TABLE\s0" 10
.IX Item "TABLE"
The table name.
.IP "\s-1WHERE\s0" 10
.IX Item "WHERE"
Where condintion. See the topic '\s-1WHERE\s0' for format.
.IP "\s-1COL\s0" 10
.IX Item "COL"
Columns to return and order, separated by ','.
.Sp
Example:
.Sp
.Vb 4
\&  col => \*(Aqcity\*(Aq        # Return only the column city.
\&  col => \*(Aqcity,state\*(Aq  # Return the column city and state in this order.
\&  col => \*(Aq>ID\*(Aq         # Return the max ID.
\&  col => \*(Aq<ID\*(Aq         # Return the min ID.
.Ve
.IP "\s-1LIMIT\s0" 10
.IX Item "LIMIT"
Limit of return or/and start of returns.
.Sp
Example:
.Sp
.Vb 3
\&  limit => \*(Aq10\*(Aq    # Make the limit of returns to 10.
\&  limit => \*(Aq10,2\*(Aq  # Make the limit of returns to 10 and the returns will start from 2.
\&  limit => \*(Aq0,2\*(Aq   # Returns will start from 2.
.Ve
.IP "\s-1SORT\s0" 10
.IX Item "SORT"
Column to use for sort (order). If > or < is used in the beggin set the ascending or descending sort.
.Sp
Example:
.Sp
.Vb 3
\&  sort => \*(AqID\*(Aq   # Sort by ID in the ascending order.
\&  sort => \*(Aq>ID\*(Aq  # Sort by ID in the ascending order.
\&  sort => \*(Aq<ID\*(Aq  # Sort by ID in the *descending order.
.Ve
.IP "\s-1GROUP\s0" 10
.IX Item "GROUP"
Column(s) to group.
.Sp
Example:
.Sp
.Vb 2
\&  group => \*(Aqcity\*(Aq          # Group only the col city
\&  group => \*(Aqcity , state\*(Aq  # Group the col city and state.
.Ve
.IP "\s-1CACHE\s0" 10
.IX Item "CACHE"
Turn on/off the cache of sth and col names.
.IP "\s-1RETURN\s0" 10
.IX Item "RETURN"
The return type. See the topic \*(L"\s-1RETURN\*(R"\s0 for format.
.SH "insert ( table , data )"
.IX Header "insert ( table , data )"
Insert data inside a table.
.PP
You can call it sending the data by column order or hash (by column name):
.PP
.Vb 1
\&  # Cols of table users: name , email , id
\&
\&  $HDB\->insert( \*(Aqusers\*(Aq , \*(Aqjoe\*(Aq , \*(Aqjoe@mail.com\*(Aq , 1 );
\&  
\&  # Or with a hash:
\&  
\&  $HDB\->insert( \*(Aqusers\*(Aq , {
\&  \*(Aqname\*(Aq => \*(Aqjoe\*(Aq ,
\&  \*(Aqemail\*(Aq => \*(Aqjoe@mail.com\*(Aq ,
\&  \*(Aqid\*(Aq => 1 ,
\&  } );
.Ve
.SH "update ( table , where , data )"
.IX Header "update ( table , where , data )"
Update a table. The data need to be a \s-1HASH\s0 or a ref to a \s-1HASH:\s0
.PP
.Vb 4
\&  $HDB\->update( \*(Aqusers\*(Aq , \*(Aquser == joe\*(Aq , {
\&  name => \*(AqJoe Tribiany\*(Aq ,
\&  email => \*(Aqfoo@mail.com\*(Aq ,
\&  } );
\&  
\&  # Or:
\&  
\&  $HDB\->update( \*(Aqusers\*(Aq , \*(Aquser == joe\*(Aq , name => \*(AqJoe Tribiany\*(Aq , email => \*(Aqfoo@mail.com\*(Aq );
.Ve
.SH "delete ( table , where )"
.IX Header "delete ( table , where )"
Delete entrys of a table:
.PP
.Vb 1
\&  $HDB\->delete( \*(Aqusers\*(Aq , \*(Aquser == joe\*(Aq );
.Ve
.SH "create ( table , columns )"
.IX Header "create ( table , columns )"
Create a new tables. You send the columns in the order that they will be in the table, and the \s-1TYPES\s0 are based in the size:
.PP
.Vb 10
\&  $HDB\->create( \*(Aqusers\*(Aq ,
\&  user  => 100 ,            # A col for strings, with the max size 100.
\&  name  => 150 ,            # A col for strings, with the max size 150.
\&  more  => 4096 ,           # A col for strings, with the max size 4Kb.
\&  more2 => 1048576          # A col for strings, with the max size 1Mb.
\&  more3 => \*(Aq*\*(Aq              # A col for strings.
\&  age   => \*(Aqint(200)\*(Aq ,     # A col for numbers, with the max number 200.
\&  numb  => \*(Aqfloat\*(Aq ,        # A floating point with normal precision.
\&  numb1 => \*(Aqdouble\*(Aq ,       # A floating point with big precision.
\&  numb2 => \*(Aqfloat(10)\*(Aq ,    # A floating point with precision 10.
\&  numb3 => \*(Aq+float(10,4)\*(Aq , # for floating points. This will be unsigned (only positive values).
\&                            # 10 is the max digit size (including decimal).
\&                            # 4 is the precision (number digits after decimal point).
\&  adm   => bool ,           # For boolean entrys.
\&  );
\&  
\&  ** FLOAT is not enable in any database, and can be changed to INTEGER. The precision and UNSIGNED options are not enabled for all too.
\&  ** Use FLOAT for normal precision, and DOUBLE for big precision for portable way.
.Ve
.PP
In MySQL the cols type will be:
.PP
.Vb 10
\&  $HDB\->create( \*(Aqusers\*(Aq ,
\&  user  => 100 ,            # VARCHAR(100)
\&  name  => 150 ,            # VARCHAR(150)
\&  more  => 4096 ,           # TEXT
\&  more2 => 1048576          # MEDIUMTEXT
\&  more3 => \*(Aq*\*(Aq              # TEXT
\&  age   => \*(Aqint(200)\*(Aq ,     # SMALLINT
\&  numb  => \*(Aqfloat\*(Aq ,        # FLOAT
\&  numb1 => \*(Aqdouble\*(Aq ,       # DOUBLE
\&  numb2 => \*(Aqfloat(10)\*(Aq ,    # FLOAT(10)
\&  numb3 => \*(Aq+float(10,4)\*(Aq , # FLOAT(10,4) UNSIGNED
\&  adm   => bool ,           # BOOLEAN
\&  );
.Ve
.PP
In SQLite the cols type will be:
.PP
.Vb 10
\&  $HDB\->create( \*(Aqusers\*(Aq ,
\&  user  => 100 ,            # VARCHAR(100)
\&  name  => 150 ,            # VARCHAR(150)
\&  more  => 4096 ,           # TEXT
\&  more2 => 1048576          # TEXT
\&  more3 => \*(Aq*\*(Aq              # TEXT
\&  age   => \*(Aqint(200)\*(Aq ,     # INTEGER
\&  numb  => \*(Aqfloat\*(Aq ,        # FLOAT
\&  numb1 => \*(Aqdouble\*(Aq ,       # FLOAT
\&  numb2 => \*(Aqfloat(10)\*(Aq ,    # FLOAT
\&  numb3 => \*(Aq+float(10,4)\*(Aq , # FLOAT
\&  adm   => bool ,           # BOOLEAN  
\&  );
.Ve
.PP
\&\fB** Note that the column \s-1ID\s0 will be always created and will be \s-1AUTOINCREMENT,\s0 unless you set the type by your self.\fR
.PP
You can use predefined col names (templates) for the columns. This is good if you don't want to think in the size that the type of data can have:
.PP
.Vb 5
\&  $HDB\->create( \*(Aqusers\*(Aq ,
\&  user  => 100 ,
\&  [\*(Aqemail\*(Aq] ,      # The predefined col name. Same as:   email => 50
\&  name  => 150 ,
\&  );
.Ve
.SH "drop ( table )"
.IX Header "drop ( table )"
Drop (remove) a table:
.PP
.Vb 1
\&  $HDB\->drop( \*(Aqusers\*(Aq );
.Ve
.SH "cmd ( SQL , RETURN )"
.IX Header "cmd ( SQL , RETURN )"
Send a \s-1SQL\s0 query to the database. The return will be in the format of the argument \s-1RETURN:\s0
.PP
.Vb 1
\&  my @sel = $HDB\->cmd(\*(Aqselect * from users\*(Aq,\*(Aq@%\*(Aq);
.Ve
.SH "dump_table"
.IX Header "dump_table"
Return a string with the table dumped.
.SH "tables"
.IX Header "tables"
Return an \s-1ARRAY\s0 with tables of the database.
.SH "table_exists ( TABLE )"
.IX Header "table_exists ( TABLE )"
Return \s-1TRUE\s0 if \s-1TABLE\s0 exists.
.SH "tables_hash"
.IX Header "tables_hash"
Same as \fBtables()\fR, but return a \s-1HASH,\s0 with the tables as keys and 1 as values.
Good if you want to make: if ($tables{users}) {...}
.SH "table_columns"
.IX Header "table_columns"
Return a \s-1HASH\s0 with the columns and respective type (based in the \s-1DB\s0 type).
.SH "names"
.IX Header "names"
Return an \s-1ARRAY\s0 with the names of the columns in the table, with the respective order.
.SH "sql"
.IX Header "sql"
Return the last \s-1SQL\s0 command sent to the \s-1DB.\s0
.SH "flush_cache"
.IX Header "flush_cache"
Clean the \s-1HDB\s0 cache (in the \s-1HDB\s0 object, not in the database).
.SH "flush_table_cache"
.IX Header "flush_table_cache"
Clean the \s-1HDB\s0 cache of a table (in the \s-1HDB\s0 object, not in the database).
.SH "get_type"
.IX Header "get_type"
Convert the \s-1HDB\s0 type to the database type:
.PP
.Vb 1
\&  my $db_col_type = $HDB\->get_type( 1000 );
\&  
\&  ...
\&  
\&  my $db_col_type = $HDB\->get_type( \*(Aqint(200)\*(Aq );
.Ve
.SH "default_types"
.IX Header "default_types"
Return a list of the default types of \s-1HDB.\s0
.SH "predefined_columns"
.IX Header "predefined_columns"
Return a \s-1HASH\s0 with the predefined columns and sets.
.SH "default_mod"
.IX Header "default_mod"
Return a \s-1HASH\s0 with the \s-1HDB::MOD\s0 installed by default in this version.
.PP
The \s-1HASH:\s0
.PP
.Vb 2
\&  keys   => full name.
\&  values => id for HDB.
.Ve
.SH "RETURN"
.IX Header "RETURN"
Commands like select has a return argument, that will tell how to format the results and the type of the variable.
.PP
The return has 2 parts.
.PP
First, the type of the variable (@|$):
.PP
.Vb 2
\&  @ >> Will return an array.
\&  $ >> Will return the first line of the results (row), or the parsed reference of the 2nd part.
\&  
\&  ** If the first part is omitted, @ will be used.
.Ve
.PP
Second, the format ($|@|%):
.PP
.Vb 3
\&  $ >> The rows will have the columns separated by \*(Aq::\*(Aq, like:  joe::joe@mail.com::1
\&  @ >> The cols of each row will be inside an ARRAY.
\&  % >> The cols of each row will be inside a HASH.
.Ve
.PP
Examples:
.PP
.Vb 3
\&  return => \*(Aq@$\*(Aq   # Will return an ARRAY, with the cols in each line of the array separated by \*(Aq::\*(Aq.
\&  return => \*(Aq@@\*(Aq   # Will return an ARRAY of ARRAYS (with the cols in the SUB\-ARRAY).
\&  return => \*(Aq@%\*(Aq   # Will return an ARRAY of HASHES (with the cols in the HASH).
\&
\&  return => \*(Aq$$\*(Aq   # Will return the cols of the first result (row) separated by \*(Aq::\*(Aq. (return a sinlge SCALAR)
\&  return => \*(Aq$@\*(Aq   # Will return the cols of the first result (row) inside an ARRAY. (return a sinlge ARRAY)
\&  return => \*(Aq$%\*(Aq   # Will return the cols of the first result (row) inside a HASH. (return a sinlge HASH)
\&  
\&  return => \*(Aq$$@\*(Aq  # Special case: Parse the encoded ref of the first col in the first row. See HDB::Encode.
\&  return => \*(Aq$$%\*(Aq  # Same as $$@.
\&
\&  return => \*(Aq<$>\*(Aq  # Special: Parse sth row by row, returning a SCALAR, with the columns separated by \*(Aq::\*(Aq.
\&  return => \*(Aq<@>\*(Aq  # Special: Parse sth row by row, returning a ARRAY with the values of the columns.
\&  return => \*(Aq<%>\*(Aq  # Special: Parse sth row by row, returning a HASH of columns and values.
\&  
\&  return => \*(Aq$\*(Aq    # Like @$
\&  return => \*(Aq@\*(Aq    # Like @@
\&  return => \*(Aq%\*(Aq    # Like @%
\&
\&  return => \*(Aq%%\*(Aq   # Like $%
.Ve
.PP
If you want the list of columns returned, put \s-1NAMES\s0 in the begin of return:
.PP
.Vb 1
\&  return => \*(AqNAMES,@@\*(Aq  # Will return the reference to an ARRAY with the columns names and the ARRAY of ARRAYS.
\&  
\&  ## USAGE:
\&  my ($cols_names , @sel) = $HDB\->select(\*(Aqusers\*(Aq,\*(AqNAMES,@%\*(Aq) ;
\&  my @cols_names = @$cols_names ;
.Ve
.PP
The best way to think in the \fI\s-1RETURN\s0\fR type is to think in what variable type will receive the result,
and in what type you want the informations inside the result.
.PP
.Vb 3
\&  ## For an ARRAY receiveing and for informations in HASH type: @%
\&  my @sel = $HDB\->select(\*(Aqusers\*(Aq,\*(Aq@%\*(Aq) ;
\&  print "$sel[0]{name}\en" ;
\&  
\&  ## For a SCALAR receiveing and for informations in ARRAY type: $@
\&  my $name = $HDB\->select(\*(Aqusers\*(Aq, col => \*(Aqname\*(Aq , \*(Aq$@\*(Aq) ;
\&  
\&  ## For a HASH receiveing and for informations in HASH type: %%
\&  my %user = $HDB\->select(\*(Aqusers\*(Aq, "id == 1" \*(Aq%%\*(Aq) ; ## return only 1 row!
\&  print "$user{name}\en" ;
.Ve
.SS "\s-1RETURN USAGE\s0 (Code Examples):"
.IX Subsection "RETURN USAGE (Code Examples):"
.Vb 1
\&  my @sel = $HDB\->select( table => users , return => \*(Aq@$\*(Aq );
\&  
\&  foreach my $sel_i ( @sel ) {
\&    my @cols = split("::" , $sel_i) ;
\&    ...
\&  }
\&  
\&  ##########################################################
\&
\&  my @sel = $HDB\->select( table => users , return => \*(Aq@@\*(Aq );
\&  
\&  foreach my $sel_i ( @sel ) {
\&    my @cols = @$sel_i ;
\&    ...
\&  }
\&  
\&  ##########################################################
\&
\&  my @sel = $HDB\->select( table => users , return => \*(Aq@%\*(Aq );
\&  
\&  foreach my $sel_i ( @sel ) {
\&    my %cols = %$sel_i ;
\&    ...
\&  }
\&  
\&  ##########################################################
\&
\&  my ($names,@sel) = $HDB\->select( table => users , return => \*(AqNAMES,@%\*(Aq );
\&  my @names = @$names ;
\&
\&  foreach my $sel_i ( @sel ) {
\&    my %cols = %$sel_i ;
\&    ...
\&  }
\&  
\&  ##########################################################
\&
\&  my %hash = $HDB\->select( table => users , col => \*(Aqencoded\*(Aq , return => \*(Aq$$@\*(Aq );
\&  
\&  foreach my $Key ( keys %hash ) {
\&    my $Value = $hash{$Key} ;
\&    print "$Key = $Value\en" ;
\&  }
\&  
\&  ##########################################################
\&  
\&  my $hdbhandle = $HDB\->select( table => users , return => \*(Aq<$>\*(Aq );
\&  
\&  while( my $row = <$hdbhandle> ) {
\&    my @cols = split("::" , $row) ;
\&    ...
\&  }
\&  
\&  ##########################################################
\&  
\&  my $hdbhandle = $HDB\->select( table => users , return => \*(Aq<@>\*(Aq );
\&  
\&  while( my @cols = <$hdbhandle> ) {
\&    ...
\&  }
\&  
\&  ##########################################################
\&  
\&  my $hdbhandle = $HDB\->select( table => users , return => \*(Aq<%>\*(Aq );
\&  
\&  while( my %cols = <$hdbhandle> ) {
\&    foreach my $Key ( keys %cols ) { print "$Key = $cols{$Key}\en" ;}
\&    ...
\&  }
\&  
\&  ##########################################################
\&
\&  my $sel_row_0 = $HDB\->select( table => users , return => \*(Aq$$\*(Aq );
\&  my @cols = split("::" , $sel_row_0) ;
\&  
\&  ##########################################################
\&
\&  my @cols = $HDB\->select( table => users , return => \*(Aq$@\*(Aq ); ## Return ROW 0.
\&  
\&  ##########################################################
\&
\&  my %cols = $HDB\->select( table => users , return => \*(Aq$%\*(Aq ); ## Return ROW 0.
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1HDB\s0, HDB::Encode, HDB::sqlite, HDB::mysql.
.SH "AUTHOR"
.IX Header "AUTHOR"
Graciliano M. P. <gm@virtuasites.com.br>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
F1l3 Manager
