* sync up

1 files changed, 424 insertions, 0 deletions

diff --git a/pear/docs/Archive_Tar.txt b/pear/docs/Archive_Tar.txt
new file mode 100644
index 0000000000..73bee0d786
--- /dev/null
+++ b/pear/docs/Archive_Tar.txt
@@ -0,0 +1,424 @@
+Documentation for class Archive_Tar
+===================================
+Last update : 2001-08-15
+
+
+
+Overview :
+----------
+
+  The Archive_Tar class helps in creating and managing GNU TAR format
+  files compressed by GNU ZIP or not. 
+  The class offers basic functions like creating an archive, adding
+  files in the archive, extracting files from the archive and listing
+  the archive content. 
+  It also provide advanced functions that allow the adding and
+  extraction of files with path manipulation. 
+
+
+Sample :
+--------
+
+  // ----- Creating the object (uncompressed archive)
+  $tar_object = new Archive_Tar("tarname.tar");
+  $tar_object->setErrorHandling(PEAR_ERROR_PRINT);
+
+  // ----- Creating the archive
+  $v_list[0]="file.txt";
+  $v_list[1]="data/";
+  $v_list[2]="file.log";
+  $tar_object->create($v_list);
+
+  // ----- Adding files
+  $v_list[0]="dev/file.txt";
+  $v_list[1]="dev/data/";
+  $v_list[2]="log/file.log";
+  $tar_object->add($v_list);
+
+  // ----- Adding more files
+  $tar_object->add("release/newfile.log release/readme.txt");
+
+  // ----- Listing the content
+  if (($v_list  =  $tar_object->listContent()) != 0)
+    for ($i=0; $i<sizeof($v_list); $i++)
+    {
+      echo "Filename :'".$v_list[$i][filename]."'<br>";
+      echo " .size :'".$v_list[$i][size]."'<br>";
+      echo " .mtime :'".$v_list[$i][mtime]."' (".date("l dS of F Y h:i:s A", $v_list[$i][mtime]).")<br>";
+      echo " .mode :'".$v_list[$i][mode]."'<br>";
+      echo " .uid :'".$v_list[$i][uid]."'<br>";
+      echo " .gid :'".$v_list[$i][gid]."'<br>";
+      echo " .typeflag :'".$v_list[$i][typeflag]."'<br>";
+    }
+
+  // ----- Extracting the archive in directory "install"
+  $tar_object->extract("install");
+
+
+Public arguments :
+------------------
+
+None
+
+
+Public Methods :
+----------------
+
+Method : Archive_Tar($p_tarname, $compress = false)
+Description :
+  Archive_Tar Class constructor. This flavour of the constructor only
+  declare a new Archive_Tar object, identifying it by the name of the
+  tar file. 
+  If the compress argument is set the tar will be read or created as a
+  gzip compressed TAR file. 
+Arguments :
+  $p_tarname : A valid filename for the tar archive file.
+  $p_compress : true/false. Indicate if the archive need to be
+                compressed or not. 
+Return value :
+  The Archive_Tar object.
+Sample :
+  $tar_object = new Archive_Tar("tarname.tar");
+  $tar_object_compressed = new Archive_Tar("tarname.tgz", true);
+How it works :
+  Initialize the object.
+
+Method : create($p_filelist)
+Description :
+  This method creates the archive file and add the files / directories
+  that are listed in $p_filelist. 
+  If the file already exists and is writable, it is replaced by the
+  new tar. It is a create and not an add. If the file exists and is
+  read-only or is a directory it is not replaced. The method return
+  false and a PEAR error text. 
+  The $p_filelist parameter can be an array of string, each string
+  representing a filename or a directory name with their path if
+  needed. It can also be a single string with names separated by a
+  single blank. 
+  See also createModify() method for more details.
+Arguments :
+  $p_filelist : An array of filenames and directory names, or a single
+  string with names separated by a single blank space. 
+Return value :
+  true on success, false on error.
+Sample 1 :
+  $tar_object = new Archive_Tar("tarname.tar");
+  $tar_object->setErrorHandling(PEAR_ERROR_PRINT);  // Optional error handling
+  $v_list[0]="file.txt";
+  $v_list[1]="data/"; (Optional '/' at the end)
+  $v_list[2]="file.log";
+  $tar_object->create($v_list);
+Sample 2 :
+  $tar_object = new Archive_Tar("tarname.tar");
+  $tar_object->setErrorHandling(PEAR_ERROR_PRINT);  // Optional error handling
+  $tar_object->create("file.txt data/ file.log");
+How it works :
+  Just calling the createModify() method with the right parameters.
+
+Method : createModify($p_filelist, $p_add_dir, $p_remove_dir = "")
+Description :
+  This method creates the archive file and add the files / directories
+  that are listed in $p_filelist. 
+  If the file already exists and is writable, it is replaced by the
+  new tar. It is a create and not an add. If the file exists and is
+  read-only or is a directory it is not replaced. The method return
+  false and a PEAR error text. 
+  The $p_filelist parameter can be an array of string, each string
+  representing a filename or a directory name with their path if
+  needed. It can also be a single string with names separated by a
+  single blank. 
+  The path indicated in $p_remove_dir will be removed from the
+  memorized path of each file / directory listed when this path
+  exists. By default nothing is removed (empty path "") 
+  The path indicated in $p_add_dir will be added at the beginning of
+  the memorized path of each file / directory listed. However it can
+  be set to empty "". The adding of a path is done after the removing
+  of path. 
+  The path add/remove ability enables the user to prepare an archive
+  for extraction in a different path than the origin files are. 
+  See also addModify() method for file adding properties.
+Arguments :
+  $p_filelist : An array of filenames and directory names, or a single
+                string with names separated by a single blank space.
+  $p_add_dir : A string which contains a path to be added to the
+               memorized path of each element in the list. 
+  $p_remove_dir : A string which contains a path to be removed from
+                  the memorized path of each element in the list, when
+		  relevant.
+Return value :
+  true on success, false on error.
+Sample 1 :
+  $tar_object = new Archive_Tar("tarname.tar");
+  $tar_object->setErrorHandling(PEAR_ERROR_PRINT);  // Optional error handling
+  $v_list[0]="file.txt";
+  $v_list[1]="data/"; (Optional '/' at the end)
+  $v_list[2]="file.log";
+  $tar_object->createModify($v_list, "install");
+  // files are stored in the archive as :
+  //   install/file.txt
+  //   install/data
+  //   install/data/file1.txt
+  //   install/data/... all the files and sub-dirs of data/
+  //   install/file.log
+Sample 2 :
+  $tar_object = new Archive_Tar("tarname.tar");
+  $tar_object->setErrorHandling(PEAR_ERROR_PRINT);  // Optional error handling
+  $v_list[0]="dev/file.txt";
+  $v_list[1]="dev/data/"; (Optional '/' at the end)
+  $v_list[2]="log/file.log";
+  $tar_object->createModify($v_list, "install", "dev");
+  // files are stored in the archive as :
+  //   install/file.txt
+  //   install/data
+  //   install/data/file1.txt
+  //   install/data/... all the files and sub-dirs of data/
+  //   install/log/file.log
+How it works :
+  Open the file in write mode (erasing the existing one if one),
+  call the _addList() method for adding the files in an empty archive,
+  add the tar footer (512 bytes block), close the tar file.
+
+
+Method : addModify($p_filelist, $p_add_dir, $p_remove_dir="")
+Description :
+  This method add the files / directories listed in $p_filelist at the
+  end of the existing archive. If the archive does not yet exists it
+  is created.
+  The $p_filelist parameter can be an array of string, each string
+  representing a filename or a directory name with their path if
+  needed. It can also be a single string with names separated by a
+  single blank. 
+  The path indicated in $p_remove_dir will be removed from the
+  memorized path of each file / directory listed when this path
+  exists. By default nothing is removed (empty path "") 
+  The path indicated in $p_add_dir will be added at the beginning of
+  the memorized path of each file / directory listed. However it can
+  be set to empty "". The adding of a path is done after the removing
+  of path. 
+  The path add/remove ability enables the user to prepare an archive
+  for extraction in a different path than the origin files are. 
+  If a file/dir is already in the archive it will only be added at the
+  end of the archive. There is no update of the existing archived
+  file/dir. However while extracting the archive, the last file will
+  replace the first one. This results in a none optimization of the
+  archive size. 
+  If a file/dir does not exist the file/dir is ignored. However an
+  error text is send to PEAR error. 
+  If a file/dir is not readable the file/dir is ignored. However an
+  error text is send to PEAR error. 
+  If the resulting filename/dirname (after the add/remove option or
+  not) string is greater than 99 char, the file/dir is
+  ignored. However an error text is send to PEAR error. 
+Arguments :
+  $p_filelist : An array of filenames and directory names, or a single
+                string with names separated by a single blank space. 
+  $p_add_dir : A string which contains a path to be added to the
+               memorized path of each element in the list. 
+  $p_remove_dir : A string which contains a path to be removed from
+                  the memorized path of each element in the list, when
+		  relevant.
+Return value :
+  true on success, false on error.
+Sample 1 :
+  $tar_object = new Archive_Tar("tarname.tar");
+  [...]
+  $v_list[0]="dev/file.txt";
+  $v_list[1]="dev/data/"; (Optional '/' at the end)
+  $v_list[2]="log/file.log";
+  $tar_object->addModify($v_list, "install");
+  // files are stored in the archive as :
+  //   install/file.txt
+  //   install/data
+  //   install/data/file1.txt
+  //   install/data/... all the files and sub-dirs of data/
+  //   install/file.log
+Sample 2 :
+  $tar_object = new Archive_Tar("tarname.tar");
+  [...]
+  $v_list[0]="dev/file.txt";
+  $v_list[1]="dev/data/"; (Optional '/' at the end)
+  $v_list[2]="log/file.log";
+  $tar_object->addModify($v_list, "install", "dev");
+  // files are stored in the archive as :
+  //   install/file.txt
+  //   install/data
+  //   install/data/file1.txt
+  //   install/data/... all the files and sub-dirs of data/
+  //   install/log/file.log
+How it works :
+  If the archive does not exists it create it and add the files.
+  If the archive does exists and is not compressed, it open it, jump
+  before the last empty 512 bytes block (tar footer) and add the files
+  at this point.
+  If the archive does exists and is compressed, a temporary copy file
+  is created. This temporary file is then 'gzip' read block by block
+  until the last empty block. The new files are then added in the
+  compressed file.
+  The adding of files is done by going through the file/dir list,
+  adding files per files, in a recursive way through the
+  directory. Each time a path need to be added/removed it is done
+  before writing the file header in the archive.
+
+Method : add($p_filelist)
+Description :
+  This method add the files / directories listed in $p_filelist at the
+  end of the existing archive. If the archive does not yet exists it
+  is created. 
+  The $p_filelist parameter can be an array of string, each string
+  representing a filename or a directory name with their path if
+  needed. It can also be a single string with names separated by a
+  single blank. 
+  See addModify() method for details and limitations.
+Arguments :
+  $p_filelist : An array of filenames and directory names, or a single
+  string with names separated by a single blank space. 
+Return value :
+  true on success, false on error.
+Sample 1 :
+  $tar_object = new Archive_Tar("tarname.tar");
+  [...]
+  $v_list[0]="dev/file.txt";
+  $v_list[1]="dev/data/"; (Optional '/' at the end)
+  $v_list[2]="log/file.log";
+  $tar_object->add($v_list);
+Sample 2 :
+  $tar_object = new Archive_Tar("tarname.tgz", true);
+  [...]
+  $v_list[0]="dev/file.txt";
+  $v_list[1]="dev/data/"; (Optional '/' at the end)
+  $v_list[2]="log/file.log";
+  $tar_object->add($v_list);
+How it works :
+  Simply call the addModify() method with the right parameters.
+
+Method : extract($p_path = "")
+Description :
+  This method extract all the content of the archive in the directory
+  indicated by $p_path.If $p_path is optional, if not set the archive
+  is extracted in the current directory. 
+  While extracting a file, if the directory path does not exists it is
+  created. 
+  See extractModify() for details and limitations.
+Arguments :
+  $p_path : Optional path where the files/dir need to by extracted.
+Return value :
+  true on success, false on error.
+Sample :
+  $tar_object = new Archive_Tar("tarname.tar");
+  $tar_object->extract();
+How it works :
+  Simply call the extractModify() method with appropriate parameters.
+
+Method : extractModify($p_path, $p_remove_path)
+Description :
+  This method extract all the content of the archive in the directory
+  indicated by $p_path. When relevant the memorized path of the
+  files/dir can be modified by removing the $p_remove_path path at the
+  beginning of the file/dir path. 
+  While extracting a file, if the directory path does not exists it is
+  created. 
+  While extracting a file, if the file already exists it is replaced
+  without looking for last modification date. 
+  While extracting a file, if the file already exists and is write
+  protected, the extraction is aborted. 
+  While extracting a file, if a directory with the same name already
+  exists, the extraction is aborted. 
+  While extracting a directory, if a file with the same name already
+  exists, the extraction is aborted. 
+  While extracting a file/directory if the destination directory exist
+  and is write protected, or does not exist but can not be created,
+  the extraction is aborted. 
+  If after extraction an extracted file does not show the correct
+  stored file size, the extraction is aborted. 
+  When the extraction is aborted, a PEAR error text is set and false
+  is returned. However the result can be a partial extraction that may
+  need to be manually cleaned. 
+Arguments :
+  $p_path : The path of the directory where the files/dir need to by
+            extracted. 
+  $p_remove_path : Part of the memorized path that can be removed if
+                   present at the beginning of the file/dir path. 
+Return value :
+  true on success, false on error.
+Sample :
+  // Imagine tarname.tar with files :
+  //   dev/data/file.txt
+  //   dev/data/log.txt
+  //   readme.txt
+  $tar_object = new Archive_Tar("tarname.tar");
+  $tar_object->extractModify("install", "dev");
+  // Files will be extracted there :
+  //   install/data/file.txt
+  //   install/data/log.txt
+  //   install/readme.txt
+How it works :
+  Open the archive and call a more generic function that can extract
+  only a part of the archive or all the archive. 
+  See extractList() method for more details.
+
+Method : listContent()
+Description :
+  This method returns an array of arrays that describe each
+  file/directory present in the archive. 
+  The array is not sorted, so it show the position of the file in the
+  archive. 
+  The file informations are :
+    $file[filename] : Name and path of the file/dir.
+    $file[mode] : File permissions (result of fileperms())
+    $file[uid] : user id
+    $file[gid] : group id
+    $file[size] : filesize
+    $file[mtime] : Last modification time (result of filemtime())
+    $file[typeflag] : "" for file, "5" for directory
+Arguments :
+Return value :
+  An array of arrays or 0 on error.
+Sample :
+  $tar_object = new Archive_Tar("tarname.tar");
+  if (($v_list  =  $tar_object->listContent()) != 0)
+    for ($i=0; $i<sizeof($v_list); $i++)
+    {
+      echo "Filename :'".$v_list[$i][filename]."'<br>";
+      echo " .size :'".$v_list[$i][size]."'<br>";
+      echo " .mtime :'".$v_list[$i][mtime]."' (".
+           date("l dS of F Y h:i:s A", $v_list[$i][mtime]).")<br>";
+      echo " .mode :'".$v_list[$i][mode]."'<br>";
+      echo " .uid :'".$v_list[$i][uid]."'<br>";
+      echo " .gid :'".$v_list[$i][gid]."'<br>";
+      echo " .typeflag :'".$v_list[$i][typeflag]."'<br>";
+    }
+How it works :
+  Call the same function as an extract however with a flag to only go
+  through the archive without extracting the files. 
+
+Method : extractList($p_filelist, $p_path = "", $p_remove_path = "")
+Description :
+  This method extract from the archive only the files indicated in the
+  $p_filelist. These files are extracted in the current directory or
+  in the directory indicated by the optional $p_path parameter. 
+  If indicated the $p_remove_path can be used in the same way as it is
+  used in extractModify() method. 
+Arguments :
+  $p_filelist : An array of filenames and directory names, or a single
+                string with names separated by a single blank space. 
+  $p_path : The path of the directory where the files/dir need to by
+            extracted. 
+  $p_remove_path : Part of the memorized path that can be removed if
+                   present at the beginning of the file/dir path. 
+Return value :
+  true on success, false on error.
+Sample :
+  // Imagine tarname.tar with files :
+  //   dev/data/file.txt
+  //   dev/data/log.txt
+  //   readme.txt
+  $tar_object = new Archive_Tar("tarname.tar");
+  $tar_object->extractList("dev/data/file.txt readme.txt", "install",
+                           "dev");
+  // Files will be extracted there :
+  //   install/data/file.txt
+  //   install/readme.txt
+How it works :
+  Go through the archive and extract only the files present in the
+  list. 
+