Add format feature

- Add --format option (custom report format)
- Add --perms option (report file permissions)
- Add --full option
- Add --version option
- Change namespace from Finalclap to Vincepare
- Disable shortopts on legacy

Author: vincepare

README.md

@@ -10,35 +10,60 @@ Example :
 dirscan --deep --same-device / > "drive-content.txt"
 ```
 
-DirScan is bundled with a text reporter, but you can customize its output by creating a custom reporting class, allowing to save data to, say, CSV, XML or an SQLite database.
+DirScan is bundled with a text reporter, but you can customize its output by creating your own reporting class, allowing to save data to, say, CSV, XML or an SQLite database.
 
-### Download ###
+### Download
 Download dirscan.phar, make it executable (chmod +x dirscan.phar) and rename it if you want. On Linux, store it to `/usr/local/bin` to make it available everywhere :
 
 ```
-wget -O dirscan https://github.com/finalclap/DirScan/releases/download/1.0.0/dirscan.phar
+wget -O dirscan https://github.com/vincepare/DirScan/releases/download/1.1.0/dirscan.phar
 chmod +x dirscan
 sudo mv dirscan /usr/local/bin/dirscan
 ```
 
-### Requirement ###
-Tested on PHP 5.3, 5.4, 5.5 & 5.6. There is also a [legacy release](https://raw.githubusercontent.com/finalclap/DirScan/master/src/legacy/dirscan) that works on PHP 5.2 with some limitations.
+### Requirement
+Tested on PHP 5.3, 5.4, 5.5 & 5.6. There is also a [legacy release](https://raw.githubusercontent.com/vincepare/DirScan/master/src/legacy/dirscan) that works on PHP 5.2 with some limitations.
 
-### Usage ###
+### Usage
 ```
 Usage :
   dirscan [OPTIONS] TARGET
 
 Options :
   --help, -h        This help message
+  --version, -v     Print software version
   --deep, -d        Explore symbolic links (default : skip)
   --flat, -f        Do not explore subdirectories
-  --access, -a      Report access time
-  --htime           Report user friendly date nearby unix timestamps
   --same-device     Explore only directories on the same device as the start directory
                     Useful on Linux, to ignore special mount points like /sys or /proc
+  --access, -a      Report access time
+  --htime, -t       Report user friendly date nearby unix timestamps
+  --perms, -p       Report file permissions
+  --full            Report all properties
+  --format=STRING   Custom reporting format, call with empty string to print format help
+```
+
+#### Formats
+Format tokens to customize output (`--format`) :
+```
+  %u   Unique path
+  %t   Type
+  %s   Size
+  %c   ctime
+  %C   Change time
+  %m   mtime
+  %M   Modify time
+  %a   atime
+  %A   Access time
+  %p   Permissions
+  %o   UID
+  %O   Owner
+  %g   GID
+  %G   Group
+  %i   Inode
+  %e   Extended
 ```
 
-### About windows ###
+### About windows
 
 DirScan is designed to work a Unix environment (Linux or Mac OS) but you can also use it on Windows. In this case, beware of NTFS junction points and symbolic links that are not handled properly by old php releases (see [readlink](http://php.net/manual/en/function.readlink.php) & [is_link](http://php.net/manual/en/function.is-link.php)). But you'd better use other tools like [WhereIsIt](http://www.whereisit-soft.com/).

src/CliReporter.php

@@ -6,13 +6,46 @@
  * @package DirScan
  */
 
-namespace Finalclap\DirScan;
+namespace Vincepare\DirScan;
 
 class CliReporter extends Reporter
 {
     protected $access; // bool Report node access time (default false)
-    protected $htime;  // bool Display human readble date/time beside unix timestamp (default false)
-    protected $typeMapping; // array Short name for file types
+    protected $htime;  // bool Print human readble date/time beside unix timestamp (default false)
+    protected $perms;  // bool Report file permissions (default false)
+    protected $format; // string Custom output format
+    protected $settings; // array Raw report settings
+    
+    /**
+     * Short name for file types
+     */
+    public static $typeMapping = array(
+        'dir' => 'd',
+        'file' => 'f',
+        'link' => 'l',
+    );
+    
+    /**
+     * Properties mapping for custom format
+     */
+    public static $propMapping = array(
+        '%u' => 'Unique path',
+        '%t' => 'Type',
+        '%s' => 'Size',
+        '%c' => 'ctime',
+        '%C' => 'Change time',
+        '%m' => 'mtime',
+        '%M' => 'Modify time',
+        '%a' => 'atime',
+        '%A' => 'Access time',
+        '%p' => 'Permissions',
+        '%o' => 'UID',
+        '%O' => 'Owner',
+        '%g' => 'GID',
+        '%G' => 'Group',
+        '%i' => 'Inode',
+        '%e' => 'Extended',
+    );
 
     /**
      * Set report settings
@@ -23,42 +56,102 @@ public function __construct($settings)
     {
         $this->access = isset($settings['access']) ? $settings['access'] : false;
         $this->htime  = isset($settings['htime'])  ? $settings['htime'] : false;
-        $this->typeMapping = array(
-            'dir' => 'd',
-            'file' => 'f',
-            'link' => 'l'
-        );
+        $this->perms  = isset($settings['perms'])  ? $settings['perms'] : false;
+        $this->format = isset($settings['format']) ? $settings['format'] : null;
+        $this->settings = $settings;
+        
+        // Use format for full report
+        if ($settings['full'] === true) {
+            $this->format = implode(' ', array_keys(self::$propMapping));
+        }
     }
 
     /**
      * Print report header
      *
      * @param string $target Target directory
-     * @param array $settings List of report settings
      * @param array $argv Command line arguments
      */
-    public function header($target, $settings, $argv)
+    public function header($target, $argv)
     {
         $targetStat = DirScan::stat($target);
-        
-        echo "time: ".time()."\n";
-        echo "date: ".date('r')."\n";
+        $header = !empty($this->format) ? $this->getRowFormatHeader($this->format) : $this->getRowHeader();
+        echo "date: ".date('r (U)')."\n";
         echo "getenv(TZ): ".getenv('TZ')."\n";
         echo "date_default_timezone_get: ".date_default_timezone_get()."\n";
+        if (defined('DIRSCAN_VERSION')) {
+            echo "dirscan version: ".DIRSCAN_VERSION."\n";
+        }
         echo "php version: ".phpversion()."\n";
+        echo "uname: ".php_uname()."\n";
         echo "cwd: ".getcwd()."\n";
         echo "target: ".$target." (realpath: ".$targetStat['realpath'].")\n";
         echo "start device: ".$targetStat['dev']."\n";
-        echo "settings: ".json_encode($settings)."\n";
+        echo "settings: ".json_encode($this->settings)."\n";
         echo "argv: ".json_encode($argv)."\n";
         echo "=====================================\n";
+        echo implode("\t", $header)."\n";
+    }
+    
+    /**
+     * Print node data
+     *
+     * @param array $node Data returned by DirScan::stat
+     * @param DirScan $scanner DirScan object
+     */
+    public function push($node, DirScan $scanner)
+    {
+        $meta = $this->getMetadata($node, $scanner);
+        $row = !empty($this->format) ? $this->getRowFormat($this->format, $node, $meta) : $this->getRow($node, $meta);
+        echo implode("\t", $row)."\n";
+    }
+    
+    /**
+     * Return metadata from a node
+     *
+     * @param array $node Data returned by DirScan::stat
+     * @param DirScan $scanner DirScan object
+     * @return array
+     */
+    protected function getMetadata($node, DirScan $scanner)
+    {
+        $meta = array(
+            'type' => isset(self::$typeMapping[$node['type']]) ? self::$typeMapping[$node['type']] : $node['type'],
+            'perms' => substr(sprintf('%o', $node['mode']), -4),
+            'hctime' => date('d/m/Y H:i:s', $node['ctime']),
+            'hmtime' => date('d/m/Y H:i:s', $node['mtime']),
+            'hatime' => date('d/m/Y H:i:s', $node['atime']),
+            'extended' => array(),
+        );
+        
+        if (isset($node['target'])) {
+            $meta['extended']['target'] = $node['target'];
+        }
 
+        if ($node['dev'] != $scanner->startDevice) {
+            $meta['extended']['device'] = $node['dev'];
+        }
+        
+        return $meta;
+    }
+    
+    /**
+     * Return the header row array
+     *
+     * @return array
+     */
+    protected function getRowHeader()
+    {
         $header = array(
             'Unique path',
             'Type',
             'Size',
         );
 
+        if ($this->perms) {
+            $header[] = 'Permissions';
+        }
+        
         $header[] = 'ctime';
         if ($this->htime) {
             $header[] = 'Change time';
@@ -77,72 +170,122 @@ public function header($target, $settings, $argv)
         }
 
         $header[] = 'Extended';
-        echo implode("\t", $header)."\n";
+        return $header;
     }
 
     /**
-     * Print node data
+     * Return the header row array, using custom format
      *
-     * @param array $node Data returned by DirScan::stat
-     * @param DirScan $scanner DirScan object
+     * @param string $format A format string used as row template
+     * @return array
      */
-    public function push($node, DirScan $scanner)
+    protected function getRowFormatHeader($format)
     {
-        $type = isset($this->typeMapping[$node['type']]) ? $this->typeMapping[$node['type']] : $node['type'];
-        $perms = substr(sprintf('%o', $node['mode']), -4);
-        if ($this->htime) {
-            $hctime = date('d/m/Y H:i:s', $node['ctime']);
-            $hmtime = date('d/m/Y H:i:s', $node['mtime']);
-            $hatime = date('d/m/Y H:i:s', $node['atime']);
-        }
-        
-        $extended = array();
-        if (isset($node['target'])) {
-            $extended['target'] = $node['target'];
-        }
-        $startDevice = $scanner->startDevice;
-        if ($node['dev'] != $startDevice) {
-            $extended['device'] = $node['dev'];
+        $header = preg_split('# #', $format);
+        foreach ($header as $key => $val) {
+            $header[$key] = strtr($val, self::$propMapping);
         }
-        
+        return $header;
+    }
+    
+    /**
+     * Return the row array for a node
+     *
+     * @param array $node Data returned by DirScan::stat
+     * @param array $meta Data returned by self::getMetadata
+     * @return array
+     */
+    protected function getRow($node, $meta)
+    {
         $row = array(
             $node['uniquepath'],
-            $type,
+            $meta['type'],
             $node['size'],
         );
 
+        if ($this->perms) {
+            $row[] = $meta['perms'];
+        }
+        
         $row[] = $node['ctime'];
         if ($this->htime) {
-            $row[] = $hctime;
+            $row[] = $meta['hctime'];
         }
 
         $row[] = $node['mtime'];
         if ($this->htime) {
-            $row[] = $hmtime;
+            $row[] = $meta['hmtime'];
         }
 
         if ($this->access) {
             $row[] = $node['atime'];
             if ($this->htime) {
-                $row[] = $hatime;
+                $row[] = $meta['hatime'];
             }
         }
 
-        if (!empty($extended)) {
-            $row[] = json_encode($extended);
+        if (!empty($meta['extended'])) {
+            $row[] = json_encode($meta['extended']);
         }
 
-        echo implode("\t", $row)."\n";
+        return $row;
+    }
+    
+    /**
+     * Return the row array for a node, using custom format
+     *
+     * @param string $format A format string used as row template
+     * @param array $node Data returned by DirScan::stat
+     * @param array $meta Data returned by self::getMetadata
+     * @return array
+     */
+    protected function getRowFormat($format, $node, $meta)
+    {
+        $statMapping = array(
+            '%u' => $node['uniquepath'],
+            '%t' => $meta['type'],
+            '%s' => $node['size'],
+            '%c' => $node['ctime'],
+            '%C' => $meta['hctime'],
+            '%m' => $node['mtime'],
+            '%M' => $meta['hmtime'],
+            '%a' => $node['atime'],
+            '%A' => $meta['hatime'],
+            '%p' => $meta['perms'],
+            '%o' => $node['uid'],
+            '%O' => $node['owner'],
+            '%g' => $node['gid'],
+            '%G' => $node['group'],
+            '%i' => $node['ino'],
+            '%e' => empty($meta['extended']) ? '' : json_encode($meta['extended']),
+        );
+        
+        $row = preg_split('# #', $format);
+        foreach ($row as $key => $val) {
+            $row[$key] = strtr($val, $statMapping);
+        }
+        
+        // Trim array
+        $keys = array_reverse(array_keys($row));
+        foreach ($keys as $key) {
+            if (empty($row[$key])) {
+                unset($row[$key]);
+                continue;
+            }
+            break;
+        }
+        
+        return $row;
     }
 
     /**
-     * Print error messages on stderr
+     * Print error messages to stderr
      *
      * @param string $msg Error message
      * @param int $code Error code
      */
     public function error($msg, $code = null)
     {
-        file_put_contents('php://stderr', $msg."\n");
+        fwrite(STDERR, $msg.PHP_EOL);
     }
 }

src/DirScan.php

@@ -6,7 +6,7 @@
  * @package DirScan
  */
 
-namespace Finalclap\DirScan;
+namespace Vincepare\DirScan;
 
 class DirScan
 {