PEAR Archive_Tar类的中文文档

类别:编程语言 点击:0 评论:0 推荐:

PEAR Archive_Tar类中文文档
===================================
最后更新(译注:英文文档) : 2001-08-15

 

总览 :
----------

  Archive_Tar类帮助创建和管理由GNU ZIP压缩或者非GNU ZIP压缩的GNU TAR格式文件.
  该类提供了一些基本函数,象创建压缩包,在压缩包里加入文件,从压缩包中解出文件,以及列出压缩包内容.
  它也提供了一些先进的函数允许用路径操作的方式添加和解压文件(译注:就是可以在添加和解压过程中,设定路径). 

样例 :
--------

  // ----- 创建对象(解压缩)
  $tar_object = new Archive_Tar("tarname.tar");
  $tar_object->setErrorHandling(PEAR_ERROR_PRINT);

  // ----- 创建压缩包
  $v_list[0]="file.txt";
  $v_list[1]="data/";
  $v_list[2]="file.log";
  $tar_object->create($v_list);

  // ----- 加入文件
  $v_list[0]="dev/file.txt";
  $v_list[1]="dev/data/";
  $v_list[2]="log/file.log";
  $tar_object->add($v_list);

  // ----- 加入更多的文件
  $tar_object->add("release/newfile.log release/readme.txt");

  // ----- 列出内容
  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>";
    }

  // ----- 解压缩到目录"install"
  $tar_object->extract("install");


公共参数 :
------------------


公共方法 :
----------------

方法 : Archive_Tar($p_tarname, $p_compress = null)
描述 :
  Archive_Tar类构造器.这个构造器的作用只是声明一个新的Archive_Tar对象,以tar文件的名称与之关联.
  如果设置了compress参数,tar文件就会被读取或者被创建一个gzip或bz2压缩TAR文件.
参数 :
  $p_tarname : A valid filename for the tar archive file.
  $p_compress : 可以为null, 'gz' 或者 'bz2',出于兼容性上的原因,它也可以为true.该参数指明是否需要gzip或者bz2压缩.
返回值 :
  Archive_Tar对象.
样例 :
  $tar_object = new Archive_Tar("tarname.tar");
  $tar_object_compressed = new Archive_Tar("tarname.tgz", true);
如何工作 :
  初始化对象.

方法 : create($p_filelist)
描述 :
  该方法创建压缩文件并加入$p_filelist所列的文件和目录.
  如果文件是存在且可写的,那么将会被新的tar文件所替代.毕竟这是一个创建动作而不是添加动作.反之,如果文件存在且为只读或者是一个目录,那么它将不会被替代.该方法即返回false和一个PEAR错误文本.
  $p_filelist参数可以是一组字符串,每个字符串代表一个文件名或者目录名,如果需要,则要带上它们的路径.该参数也可以是以空格分割开的文件或目录名组成的字符串.
  参阅createModify()方法得到更多的细节.
参数 :
  $p_filelist : 一组文件名和目录名,或者以单个空格分割开的文件或目录名组成的字符串.
返回值 :
  成功返回true,错误返回false.
样例 1 :
  $tar_object = new Archive_Tar("tarname.tar");
  $tar_object->setErrorHandling(PEAR_ERROR_PRINT);  // 可选的错误处理
  $v_list[0]="file.txt";
  $v_list[1]="data/"; (末尾'/'为可选)
  $v_list[2]="file.log";
  $tar_object->create($v_list);
?> 样例 2 : <?php
  $tar_object = new Archive_Tar("tarname.tar");
  $tar_object->setErrorHandling(PEAR_ERROR_PRINT);  // 可选的错误处理
  $tar_object->create("file.txt data/ file.log");
如何工作 :
  用正确的参数调用createModify()方法.

方法 : createModify($p_filelist, $p_add_dir, $p_remove_dir = "")
描述 :
  该方法创建一个压缩文件,并加入$p_filelist所列出的文件/目录.
  如果文件是存在且可写的,那么将会被新的tar文件所替代.毕竟这是一个创建动作而不是添加动作.反之,如果文件存在且为只读或者是一个目录,那么它将不会被替代.该方法即返回false和一个PEAR错误文本.
  $p_filelist参数可以是一组字符串,每个字符串代表一个文件名或者目录名,如果需要,则要带上它们的路径.该参数也可以是以空格分割开的文件或目录名组成的字符串.
  如果存在的话,在$p_remove_dir中声明的路径将从每个列出来的文件/目录已记录路径中删除.默认没有任何东西被删除(空路径"").
  在$p_add_dir中声明的路径将会加在每一个列出来的文件/目录的已记录路径的开始.但是它也可设为空"".路径的添加将会在路径的删除之前(译注:即先去掉$p_remove_dir,再加上$p_add_dir).
  这种路径的添加/删除能力使得用户可以在一个不同的路径中准备好解压用的压缩包,而不是源文件所在.
  参阅addModify()方法查看文件添加的特性.
参数 :
  $p_filelist : 一组文件名和目录名,或者以单个空格分割开的文件或目录名组成的字符串.
  $p_add_dir : 一个字符串,包含欲加到列表中每一个元素的已记录路路径中的一个路径.
  $p_remove_dir : 一个字符串,包含一个路径,如果关联的话,则从列表中每一个元素的已记录路径删除.
返回值 :
  成功返回true,错误返回false.
样例 1 :
  $tar_object = new Archive_Tar("tarname.tar");
  $tar_object->setErrorHandling(PEAR_ERROR_PRINT);  // 可选的错误处理
  $v_list[0]="file.txt";
  $v_list[1]="data/"; (末尾'/'为可选)
  $v_list[2]="file.log";
  $tar_object->createModify($v_list, "install");
  // 存储在压缩包中的文件形如 :
  //   install/file.txt
  //   install/data
  //   install/data/file1.txt
  //   install/data/... 所有data下的文件和子目录/
  //   install/file.log
样例 2 :
  $tar_object = new Archive_Tar("tarname.tar");
  $tar_object->setErrorHandling(PEAR_ERROR_PRINT);  // 可选的错误处理
  $v_list[0]="dev/file.txt";
  $v_list[1]="dev/data/"; (末尾'/'为可选)
  $v_list[2]="log/file.log";
  $tar_object->createModify($v_list, "install", "dev");
  // 存储在压缩包中的文件形如 :
  //   install/file.txt
  //   install/data
  //   install/data/file1.txt
  //   install/data/... 所有data下的文件和子目录/
  //   install/log/file.log
如何工作 :
  以可写的模式打开文件(如果已经存在,则擦除),调用_addList()方法,在一个空压缩包加入文件,加入尾部(512字节的区块),关闭tar文件.


方法 : addModify($p_filelist, $p_add_dir, $p_remove_dir="")
描述 :
  该方法在已存在的压缩包的末尾加入$p_filelist所列的文件/目录.如果压缩包尚未存在,那么就被创建.
 
  $p_filelist参数可以是一组字符串,每个字符串代表一个文件名或者目录名,如果需要,则要带上它们的路径.该参数也可以是以空格分割开的文件或目录名组成的字符串.
  如果存在的话,在$p_remove_dir中声明的路径将从每个列出来的文件/目录已记录路径中删除.默认没有任何东西被删除(空路径"").
 
  在$p_add_dir中声明的路径将会加在每一个列出来的文件/目录的已记录路径的开始.但是它也可设为空"".路径的添加将会在路径的删除之前(译注:即先去掉$p_remove_dir,再加上$p_add_dir).
  这种路径的添加/删除能力使得用户可以在一个不同的路径中准备好解压用的压缩包,而不是源文件所在.
  如果文件/目录已经存在于压缩包,它将只被加在压缩包的末尾.已存在的压缩的文件和路径并没有任何更新.但是,当解压时,最后的文件将会替代第一个.结果是压缩尺寸的未优化.
  如果文件/目录不存在,该文件/目录就被忽略.但一个错误文本将会发送到PEAR错误里.
  如果文件/目录不可读,该文件/目录就被忽略.但一个错误文件将会发送到PEAR错误里.
  如果结果文件名/路径名(在添加/删除之后或者没有这些动作)字符串多于99个字符,该文件/目录将被忽略.但一个错误文本将会发送到PEAR错误里.
 参数 :
  $p_filelist : 一组文件名和目录名,或者以单个空格分割开的文件或目录名组成的字符串.
  $p_add_dir : 一个字符串,包含欲加到列表中每一个元素的已记录路路径中的一个路径.
  $p_remove_dir : 一个字符串,包含一个路径,如果关联的话,则从列表中每一个元素的已记录路径删除.
返回值 :
  成功返回true,错误返回false.
样例 1 :
  $tar_object = new Archive_Tar("tarname.tar");
  [...]
  $v_list[0]="dev/file.txt";
  $v_list[1]="dev/data/"; (末尾'/'为可选)
  $v_list[2]="log/file.log";
  $tar_object->addModify($v_list, "install");
  // 存储在压缩包中的文件形如 :
  //   install/file.txt
  //   install/data
  //   install/data/file1.txt
  //   install/data/... 所有data下的文件和子目录/
  //   install/file.log
样例 2 :
  $tar_object = new Archive_Tar("tarname.tar");
  [...]
  $v_list[0]="dev/file.txt";
  $v_list[1]="dev/data/"; (末尾'/'为可选)
  $v_list[2]="log/file.log";
  $tar_object->addModify($v_list, "install", "dev");
  // 存储在压缩包中的文件形如 :
  //   install/file.txt
  //   install/data
  //   install/data/file1.txt
  //   install/data/... 所有data下的文件和子目录/
  //   install/log/file.log
如何工作 :
  如果压缩包不存在,则创建并加入文件.
  如果压缩包确实存在但未被压缩,则打开它,跳到组后512字节空区块(tar脚部),并在该点加入文件.
  如果压缩包确实存在且被压缩,将会创建一个临时拷贝文件.这个临时文件是以'gzip'方式一块接着一块直至最终空区块读取的结果.新的文件此时被加到压缩文件中.
  文件的添加是通过遍历文件/目录列表,然后加进每个文件,以一个递规的方式遍历目录.每一次一个路径都需要添加/删除,在在压缩包写入文件头部之前完成这项工作.
 

方法 : add($p_filelist)
描述 :
  该方法把$p_filelist里列出的文件/目录加入到已经存在的压缩包中去.如果压缩包尚未存在,则创建之.
  $p_filelist参数可以是一组字符串,每个字符串代表一个文件名或者目录名,如果需要,则要带上它们的路径.该参数也可以是以空格分割开的文件或目录名组成的字符串.
  参阅addModify()方法查看细节和限制.
参数 :
  $p_filelist : 一组文件名和目录名,或者以单个空格分割开的文件或目录名组成的字符串.
返回值 :
  成功返回true,错误返回false.
样例 1 :
  $tar_object = new Archive_Tar("tarname.tar");
  [...]
  $v_list[0]="dev/file.txt";
  $v_list[1]="dev/data/"; (末尾'/'为可选)
  $v_list[2]="log/file.log";
  $tar_object->add($v_list);
?> 样例 2 : <?php
  $tar_object = new Archive_Tar("tarname.tgz", true);
  [...]
  $v_list[0]="dev/file.txt";
  $v_list[1]="dev/data/"; (末尾'/'为可选)
  $v_list[2]="log/file.log";
  $tar_object->add($v_list);
如何工作 :
  用正确的参数简单地调用addModify()方法.

方法 : addString($p_filename, $p_string)
描述 :
  该方法在已存在压缩包末尾以文件的形式加入一单个字符串.如果压缩包尚未存在,则创建之.
参数 :
  $p_filename : 一个字符串,包含将与该字符串相关联的文件全部路径.
  $p_string :   加入到压缩包文件中的内容.
返回值 :
  成功返回true,错误返回false.
样例 1 :
  $v_archive = & new Archive_Tar($p_filename);
  $v_archive->setErrorHandling(PEAR_ERROR_PRINT);
  $v_result = $v_archive->addString('data/test.txt', '这是字符串文本');


方法 : extract($p_path = "")
描述 :
  该方法在一个由$p_path声明的目录中解出所有压缩包里的内容.$p_path是可选的,如果没有设置,压缩包就在当前目录被解压.
  当解压一个文件时,如果目录路径不存在,则该目录路径会被创建.
  查阅extractModify()查看细节和限制.
参数 :
  $p_path : 可选的路径,为文件/目录需要解压到的地方.
返回值 :
  成功返回true,错误返回false.
样例 :
  $tar_object = new Archive_Tar("tarname.tar");
  $tar_object->extract();
如何工作 :
  用恰当的参数简单的调用extractModify()方法.

方法 : extractModify($p_path, $p_remove_path)
描述 :
  该方法在由$p_path声明的目录里解出压缩包所有内容.如果是关联的,文件/目录的已记录路径可以在文件/路径开头因删除了$p_remove_path路径而改变.
  当解压一个文件时,如果目录路径不存在,则创建之.
  当解压一个文件时,如果文件已经存在,那么不必查看最后修改日期即会被替代.
  当解压一个文件时,如果一个文件已经存在且为写保护,则解压会被中止.
  当解压一个文件时,如果具有同样名称的目录已经存在,则解压会被中止.
  当解压一个目录时,如果具有同样名称的文件已经存在,则解压会被中止.
  当解压一个文件/目录时,如果目标目录存在且为写保护,或者不存在但不能创建,则解压会被中止.
  如果在解压之后,一个已解出文件与存储文件尺寸不一致,则解压会被中止.
  当解压被中止时,一个PEAR文本会被发送,并且返回false.但是结果可能时需要手工清理的一部分解出的东西.
参数 :
  $p_path : 为文件/目录需要解压到的地方.
  $p_remove_path : 已记录路径的一部分,如果出现在文件/目录路径的开头,就可以被删除.
返回值 :
  成功返回true,错误返回false.
样例 :
  // 设想一个含下列文件的tarname.tar :
  //   dev/data/file.txt
  //   dev/data/log.txt
  //   readme.txt
  $tar_object = new Archive_Tar("tarname.tar");
  $tar_object->extractModify("install", "dev");
  // 文件将被解压到那里(译注:install目录下) :
  //   install/data/file.txt
  //   install/data/log.txt
  //   install/readme.txt
如何工作 :
  打开压缩包,调用一个可以解压压缩包一部分或全部的更通用的函数.
  查阅extractList()方法查看更多细节.

方法 : extractInString($p_filename)
描述 :
  该方法从压缩包中解出一个由$p_filename声明的文件.
  返回一个含文件内容的字符串或者错误时返回NULL.
参数 :
  $p_filename : 要解出内容到一字符串的路径.
返回值 :
  一个含文件内容的字符串或者NULL.
样例 :
  // 设想一个含下列文件的tarname.tar :
  //   dev/data/file.txt
  //   dev/data/log.txt
  //   dev/readme.txt
  $v_archive = & new Archive_Tar('tarname.tar');
  $v_archive->setErrorHandling(PEAR_ERROR_PRINT);
  $v_string = $v_archive->extractInString('dev/readme.txt');
  echo $v_string;

方法 : listContent()
描述 :
  该方法返回一列数组(译注:即为二维数组),用来描述每一个在压缩包里的文件/目录.
  该数组没有被排序,所以它可以示意文件在压缩包中的位置.
  文件的信息有:
    $file[filename] : 文件/目录的名称和路径.
    $file[mode] : 文件权限(为fileperms()的结果)
    $file[uid] : 用户id
    $file[gid] : 用户组id
    $file[size] : 文件尺寸
    $file[mtime] : 最后修改时间(为filemtime()的结果)
    $file[typeflag] : 对文件来说为"", 对目录来说为"5"
参数 :
返回值 :
  一列数组或者错误返回0.
样例 :
  $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>";
    }
    如何工作 :
  和extract调用同样的函数,但是带一个标记只遍历压缩包,并不解出文件.


方法 : extractList($p_filelist, $p_path = "", $p_remove_path = "")
描述 :
  该方法只从压缩包中解出在$p_filelist声明的文件.这些文件被解到当前目录或者到一个由可选参数$p_path声明的目录里.
  如果声明了$p_remove_path,那么可以和它在extractModify()方法里的用法一样应用.
参数 :
  $p_filelist : 一组文件名和目录名,或者以单个空格分割开的文件或目录名组成的字符串.
  $p_path : 为文件/目录需要解压到的地方.
  $p_remove_path : 已记录路径的一部分,如果出现在文件/目录路径的开头,就可以被删除.
返回值 :
  成功返回true,错误返回false.
样例 :
  // 设想一个含下列文件的tarname.tar :
  //   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");
  // 文件将被解压到那里(译注:install目录下) :
  //   install/data/file.txt
  //   install/readme.txt
如何工作 :
  遍历压缩包,只解压出列表中出现的文件.

 

本文地址:http://com.8s8s.com/it/it26330.htm