The Command-Line Parser

The Command-Line Parser – parsing data source with CLI

Switches and options

The Command-Line Parser can be invoked through the pci command.

Let's take a look at the command-line parser switches:

Usage: pci [options]

  -d   --dir (optional)value                      Parse DIR to get its
                                                  compatibility info ()
  -f   --file (optional)value                     Parse FILE to get its
                                                  compatibility info ()
  -s   --string (optional)value                   Parse STRING to get its
                                                  compatibility info ()
  -v   --verbose (optional)value                  Set the verbose level (1)
  -n   --no-recurse                               Do not recursively parse files

                                                  when using --dir
  -if  --ignore-files (optional)value             Data file name which contains
                                                  a list of file to ignore
                                                  (files.txt)
  -id  --ignore-dirs (optional)value              Data file name which contains
                                                  a list of directory to ignore
                                                  (dirs.txt)
  -in  --ignore-functions (optional)value         Data file name which contains
                                                  a list of php function to
                                                  ignore (functions.txt)
  -ic  --ignore-constants (optional)value         Data file name which contains
                                                  a list of php constant to
                                                  ignore (constants.txt)
  -ie  --ignore-extensions (optional)value        Data file name which contains
                                                  a list of php extension to
                                                  ignore (extensions.txt)
  -iv  --ignore-versions values(optional)         PHP versions - functions to
                                                  exclude when parsing source
                                                  code (5.0.0)
  -inm --ignore-functions-match (optional)value   Data file name which contains
                                                  a list of php function pattern

                                                  to ignore
                                                  (functions-match.txt)
  -iem --ignore-extensions-match (optional)value  Data file name which contains
                                                  a list of php extension
                                                  pattern to ignore
                                                  (extensions-match.txt)
  -icm --ignore-constants-match (optional)value   Data file name which contains
                                                  a list of php constant pattern

                                                  to ignore
                                                  (constants-match.txt)
  -fe  --file-ext (optional)value                 A comma separated list of file

                                                  extensions to parse (only
                                                  valid if parsing a directory)
                                                  (php, php4, inc, phtml)
  -r   --report (optional)value                   Print either "xml" or "csv"
                                                  report (text)
  -o   --output-level (optional)value             Print Path/File + Version with

                                                  additional data (31)
  -t   --tab (optional)value                      Columns width (29,12,20)
  -p   --progress (optional)value                 Show a wait message [text] or
                                                  a progress bar [bar] (bar)
  -S   --summarize                                Print only summary when
                                                  parsing directory
  -V   --version                                  Print version information
  -h   --help                                     Show this help
  

-d | --dir

pci -d directory

Runs the parser with all default options, and try to analyze content of files into directory identified by switch -d or --dir

-f | --file

pci -f file

Runs the parser with all default options, and try to analyze content of a single file identified by switch -f or --file

-s | --string

pci -s string

Runs the parser with all default options, and try to analyze content of a chunk of code (string) designed by switch -s or --string

-v | --verbose

pci -v number -d directory

Runs the parser with all default options, and try to analyze content of files into directory identified by switch -d or --dir with the level of detail given by number and switch -v or --verbose

Verbose level goes from 0 (no extra information) to 7 (full extra details).

  • Level 0 give only parsing results of data source (directory, file, string).

    For example: pci -v 0 -d /tmp/Services_W3C_CSSValidator-0.1.0 give

    +-----------------------------+---------+---+------------+--------------------+
    | Files                       | Version | C | Extensions | Constants/Tokens   |
    +-----------------------------+---------+---+------------+--------------------+
    | ...W3C_CSSValidator-0.1.0/* | 5.1.0   | 4 | dom        | ...CTORY_SEPARATOR |
    |                             |         |   |            | E_ALL              |
    |                             |         |   |            | FALSE              |
    |                             |         |   |            | NULL               |
    |                             |         |   |            | TRUE               |
    |                             |         |   |            | __FILE__           |
    |                             |         |   |            | instanceof         |
    |                             |         |   |            | protected          |
    |                             |         |   |            | public             |
    +-----------------------------+---------+---+------------+--------------------+
    | ...r-0.1.0/CSSValidator.php | 5.1.0   | 0 | dom        | FALSE              |
    |                             |         |   |            | NULL               |
    |                             |         |   |            | TRUE               |
    |                             |         |   |            | protected          |
    |                             |         |   |            | public             |
    +-----------------------------+---------+---+------------+--------------------+
    | ...0.1.0/tests/AllTests.php | 5.0.0   | 4 |            | __FILE__           |
    |                             |         |   |            | public             |
    +-----------------------------+---------+---+------------+--------------------+
    | ...W3C_CSSValidatorTest.php | 5.0.0   | 4 |            | ...CTORY_SEPARATOR |
    |                             |         |   |            | __FILE__           |
    |                             |         |   |            | protected          |
    |                             |         |   |            | public             |
    +-----------------------------+---------+---+------------+--------------------+
    | ...les/validate_atrules.php | 4.0.0   | 0 |            | E_ALL              |
    |                             |         |   |            | TRUE               |
    +-----------------------------+---------+---+------------+--------------------+
    | ...ples/validate_byfile.php | 4.0.0   | 0 |            | E_ALL              |
    |                             |         |   |            | TRUE               |
    +-----------------------------+---------+---+------------+--------------------+
    | ...mples/validate_byuri.php | 4.0.0   | 0 |            | E_ALL              |
    |                             |         |   |            | TRUE               |
    +-----------------------------+---------+---+------------+--------------------+
    | ...es/validate_fragment.php | 4.0.0   | 0 |            | E_ALL              |
    |                             |         |   |            | TRUE               |
    +-----------------------------+---------+---+------------+--------------------+
    | ...0/CSSValidator/Error.php | 5.0.0   | 0 |            | public             |
    +-----------------------------+---------+---+------------+--------------------+
    | ...CSSValidator/Message.php | 5.0.0   | 0 |            | NULL               |
    |                             |         |   |            | public             |
    +-----------------------------+---------+---+------------+--------------------+
    | ...SSValidator/Response.php | 5.0.0   | 0 |            | instanceof         |
    |                             |         |   |            | public             |
    +-----------------------------+---------+---+------------+--------------------+
    | ...CSSValidator/Warning.php | 4.0.0   | 0 |            |                    |
    +-----------------------------+---------+---+------------+--------------------+
             
  • Level 1 give same details as level 0, plus command line resume.

    For example: pci -v 1 -d /tmp/Services_W3C_CSSValidator-0.1.0 give

    Command Line resume :
    
    +-------------------------+---------------------------------------------------+
    | Option                  | Value                                             |
    +-------------------------+---------------------------------------------------+
    | summarize               | FALSE                                             |
    | output-level            | 31                                                |
    | verbose                 | 1                                                 |
    | dir                     | /tmp/Services_W3C_CSSValidator-0.1.0              |
    +-------------------------+---------------------------------------------------+
             
  • Level 2 give same details as level 0, plus parser options used.

    For example: pci -v 2 -d /tmp/Services_W3C_CSSValidator-0.1.0 give

    Parser options :
    
    +-------------------------+---------------------------------------------------+
    | Option                  | Value                                             |
    +-------------------------+---------------------------------------------------+
    | file_ext                | php                                               |
    |                         | php4                                              |
    |                         | inc                                               |
    |                         | phtml                                             |
    | recurse_dir             | TRUE                                              |
    | debug                   | FALSE                                             |
    | is_string               | FALSE                                             |
    | ignore_files            |                                                   |
    | ignore_dirs             |                                                   |
    +-------------------------+---------------------------------------------------+
             
  • Level 3 is equivalent to level 2 + level 1 + level 0.

  • Level 4 give same details as level 0, plus list of php functions used with their version and source (extension PECL or standard).

    For example: pci -v 4 -d /tmp/Services_W3C_CSSValidator-0.1.0 give

    Debug:
    
    +---------+-----------------+-----------+------+
    | Version | Function        | Extension | PECL |
    +---------+-----------------+-----------+------+
    | 4.0.0   | in_array        |           | no   |
    | 4.0.0   | file_exists     |           | no   |
    | 4.0.0   | is_bool         |           | no   |
    | 4.0.0   | intval          |           | no   |
    | 4.0.0   | defined         |           | no   |
    | 4.0.0   | define          |           | no   |
    | 4.0.0   | chdir           |           | no   |
    | 4.0.0   | dirname         |           | no   |
    | 4.0.0   | realpath        |           | no   |
    | 4.0.0   | error_reporting |           | no   |
    | 4.0.0   | ini_set         |           | no   |
    | 4.0.0   | var_dump        |           | no   |
    | 4.0.0   | get_object_vars |           | no   |
    | 5.1.0   | property_exists |           | no   |
    +---------+-----------------+-----------+------+
             
  • Level 5 is equivalent to level 4 + level 1 + level 0.

  • Level 6 is equivalent to level 4 + level 2.

  • Level 7 is equivalent to level 4 + level 2 + level 1.

-n | --no-recurse

pci -n -d directory

Runs the parser and analyze only files in directory identified by -d or --dir. Default behavior will parse all directory childs recursively.

-if | --ignore-files

Identify the parameter text file that contains on each line the name of each file to ignore when parsing a directory/branch.

Default value used files.txt file in the same directory as pci script.

-id | --ignore-dirs

Identify the parameter text file that contains on each line the name of each sub-directory to ignore when parsing a directory/branch.

Default value used dirs.txt file in the same directory as pci script.

-in | --ignore-functions

Identify the parameter text file that contains on each line the name of each PHP function to ignore when parsing the data source.

Default value used functions.txt file in the same directory as pci script.

-ic | --ignore-constants

Identify the parameter text file that contains on each line the name of each PHP constant to ignore when parsing the data source

Default value used constants.txt file in the same directory as pci script.

-ie | --ignore-extensions

Identify the parameter text file that contains on each line the name of each PHP extension to ignore (all extension.functions) when parsing the data source

-iv | --ignore-versions

Expect one or two values that identify which PHP version (and all its related functions) to ignore.

For example: ignore all PHP 5 functions (minor releases 0 thru 2), or only PHP 5.0.0 functions. pci -f file -iv 5.0.0 5.2.0 pci -d directory -iv 5.0.0

-inm | --ignore-functions-match

Identify the parameter text file that contains on each line a pattern (match a regular expression) of PHP function to ignore when parsing the data source.

Default value used functions-match.txt file in the same directory as pci script.

Comments start with ";", as in php.ini, and blank lines are allowed.

If you want to use the preg_match compare function, put a "=", to start the line, follow by a regular expression.

-iem | --ignore-extensions-match

Identify the parameter text file that contains on each line a pattern (match a regular expression) of PHP extension to ignore when parsing the data source.

Default value used extensions-match.txt file in the same directory as pci script.

Comments start with ";", as in php.ini, and blank lines are allowed.

If you want to use the preg_match compare function, put a "=", to start the line, follow by a regular expression.

-icm | --ignore-constants-match

Identify the parameter text file that contains on each line a pattern (match a regular expression) of PHP constant to ignore when parsing a directory, a single file, or a string.

Default value used constants-match.txt file in the same directory as pci script.

Comments start with ";", as in php.ini, and blank lines are allowed.

If you want to use the preg_match compare function, put a "=", to start the line, follow by a regular expression.

-fe | --file-ext

Follow by a comma separated list of file extensions to parse (only valid if parsing a directory). Default is: php,php4,inc,phtml

-r | --report

Print either a text report (default), or any others render available (csv, xml, ...)

For example: pci -r xml -f /tmp/PHP_CodeSniffer-1.1.0/CodeSniffer.php give these results (when package XML_Beautifier is available)

       
<?xml version="1.0" encoding="UTF-8"?>
<pci version="1.9.0b2">
    <file name="/tmp/PHP_CodeSniffer-1.1.0/CodeSniffer.php">
    <version>5.1.2</version>
    <conditions level="0" />
    <extensions count="5">
        <extension>date</extension>
        <extension>pcre</extension>
        <extension>SPL</extension>
        <extension>tokenizer</extension>
        <extension>xml</extension>
    </extensions>
    <constants count="7">
        <constant>DIRECTORY_SEPARATOR</constant>
        <constant>FALSE</constant>
        <constant>NULL</constant>
        <constant>PHP_EOL</constant>
        <constant>TRUE</constant>
        <constant>T_STRING</constant>
        <constant>__FILE__</constant>
    </constants>
    <tokens count="5">
        <token>catch</token>
        <token>protected</token>
        <token>public</token>
        <token>throw</token>
        <token>try</token>
    </tokens>
    <ignored>
        <files count="0" />
        <functions count="0" />
        <extensions count="0" />
        <constants count="0" />
    </ignored>
</pci>
       

And with little debug option ( verbose level 4 ) pci -r xml -v 4 -f /tmp/PHP_CodeSniffer-1.1.0/CodeSniffer.php results became

       
<?xml version="1.0" encoding="UTF-8"?>
<pci version="1.9.0b2">
    <file>/tmp/PHP_CodeSniffer-1.1.0/CodeSniffer.php</file>
    <version>5.1.2</version>
    <conditions count="0" level="0" />
    <extensions count="5">
        <extension>date</extension>
        <extension>pcre</extension>
        <extension>SPL</extension>
        <extension>tokenizer</extension>
        <extension>xml</extension>
    </extensions>
    <constants count="7">
        <constant>DIRECTORY_SEPARATOR</constant>
        <constant>FALSE</constant>
        <constant>NULL</constant>
        <constant>PHP_EOL</constant>
        <constant>TRUE</constant>
        <constant>T_STRING</constant>
        <constant>__FILE__</constant>
    </constants>
    <tokens count="5">
        <token>catch</token>
        <token>protected</token>
        <token>public</token>
        <token>throw</token>
        <token>try</token>
    </tokens>
    <ignored>
        <files count="0" />
        <functions count="0" />
        <extensions count="0" />
        <constants count="0" />
    </ignored>
    <functions count="41">
        <function version="4.0.0">class_exists</function>
        <function version="4.0.0">define</function>
        <function version="4.0.0">chdir</function>
        <function version="4.0.0">dirname</function>
        <function version="4.0.0">substr</function>
        <function version="4.0.0">str_replace</function>
        <function version="4.0.0">is_file</function>
        <function version="4.0.0">is_array</function>
        <function version="4.0.0">is_string</function>
        <function version="4.0.0">count</function>
        <function version="4.0.0">is_dir</function>
        <function version="4.0.0">basename</function>
        <function version="4.0.0">realpath</function>
        <function version="4.0.0">strtolower</function>
        <function version="4.0.0">strrpos</function>
        <function version="4.0.0">in_array</function>
        <function version="4.0.0">explode</function>
        <function version="4.0.0">array_pop</function>
        <function version="4.0.0">array_merge</function>
        <function version="4.0.0">file_exists</function>
        <function version="4.0.0">strtr</function>
        <function extension="pcre" pecl="false" version="4.0.0">preg_match</function>
        <function extension="date" pecl="false" version="4.0.0">time</function>
        <function version="4.0.0">ksort</function>
        <function version="4.0.0">htmlspecialchars</function>
        <function extension="xml" pecl="false" version="4.0.0">utf8_encode</function>
        <function version="4.0.0">strlen</function>
        <function version="4.0.0">str_repeat</function>
        <function version="4.0.0">ord</function>
        <function version="4.0.0">strtoupper</function>
        <function version="4.0.0">strpos</function>
        <function version="4.0.0">rtrim</function>
        <function version="4.0.0">is_writable</function>
        <function version="4.0.2">wordwrap</function>
        <function version="4.0.4">is_null</function>
        <function version="4.0.4">constant</function>
        <function extension="tokenizer" pecl="false" version="4.2.0">token_name</function>
        <function version="4.2.0">var_export</function>
        <function version="5.0.0">file_put_contents</function>
        <function version="5.0.2">interface_exists</function>
        <function extension="SPL" pecl="false" version="5.1.2">spl_autoload_register</function>
    </functions>
</pci>
       
-o | --output-level

Allow to filter data type (column) you want on standard output (console). From all details (31=default) to only file name (=0)

  • 0: file name

  • 1: conditional code

  • 2: extensions

  • 4: constants

  • 8: tokens

  • 16: version

output_level is binary value. So to have, for example, only file name (always mandatory) with version and extensions, you have to give value 18 (16 + 2).

-t | --tab

Sets the Files, Etensions and Constants/Tokens columns width. Default values are: 29 char. for Files colum, 12 char. for Extentions column, and 20 char. for Constants/Tokens column.

Here are the best values optimized by output-level for a 80 columns screen width, to almost always see extensions and constants/tokens without name truncated: first value is always for Files column (f), second value is always for Extensions column (e), and third value is always for Constants/Tokens column (c)

If a (f,e,c) value is missing then the corresponding default value (f=29,e=12,c=20) is used.

For example: 56,,20 is equivalent to 56,12,20

  • output-level 0: 77

  • output-level 1: 73

  • output-level 2: 59,17

  • output-level 3: 55,17

  • output-level 4, 8, 12: 55,,21

  • output-level 5, 9, 13: 51,,21

  • output-level 6, 10, 14: 37,17,21

  • output-level 7, 11, 15: 33,17,21

  • output-level 16: 67

  • output-level 17: 63

  • output-level 18: 49,17

  • output-level 19: 45,17

  • output-level 20, 24: 45,,21

  • output-level 21, 25, 29: 41,,21

  • output-level 22, 26, 30: 27,17,21

  • output-level 23, 27, 31: 23,17,21

  • output-level 24, 28: 45,17,21

-p | --progress [ bar | text ]

Show a progress bar (if PEAR::Console_ProgressBar is installed) or a simple text wait message when parsing a directory.

If you specify --progress bar and PEAR::Console_ProgressBar is not available, then default display will be text wait message (without giving an error), as if you have specified --progress text instead

-S | --summarize

Print only the summary of parsing result for a directory, rather than full details file by file (default).

-V | --version

Print only the current version information

-h | --help

Show help panel (as described in beginning of this section)

Display results

Let's take a look now at the result displayed : the main table

+-----------------------------+---------+---+------------+--------------------+
| Files                       | Version | C | Extensions | Constants/Tokens   |
+-----------------------------+---------+---+------------+--------------------+

+-----------------------------+---------+---+------------+--------------------+
  

We have, by default (output-level = 31) 5 columns

For Files, Extensions, Constants/Tokens columns, if content is larger than cell width, then the content if truncated by left, and replaced by ...

  • Files Identify each file of data source parsed.

  • Version Give the minimum version to run the file. And if there is a second number, give the max version to run source file.

  • C Show the level of conditional code found in your source file(s). From 0=none, 1=function_exists, 2=extension_loaded, 4=defined and more (its binary value). This C column is the same information given by cond_code in final hash result of Array Renderer.

  • Extensions List the PHP standard or PECL extensions required to run the source file.

  • Constants/Tokens List the PHP standard or user defined constants and PHP5+ tokens (such as: private, public, final, ...)

When verbose mode is set to level 1, you have an additional table displayed, that resume the command line arguments

Command Line resume :

+-------------------------+---------------------------------------------------+
| Option                  | Value                                             |
+-------------------------+---------------------------------------------------+

+-------------------------+---------------------------------------------------+
  

When verbose mode is set to level 2, you have an additional table displayed, that resume the parser options used

Parser options :

+-------------------------+---------------------------------------------------+
| Option                  | Value                                             |
+-------------------------+---------------------------------------------------+

+-------------------------+---------------------------------------------------+
  

When verbose mode is set to level 4, you have an additional table displayed, that show each PHP standard or PECL functions with their version

Debug:

+---------+-----------------+-----------+------+
| Version | Function        | Extension | PECL |
+---------+-----------------+-----------+------+

+---------+-----------------+-----------+------+