clean up docs, better variable naming, document --debug

1 files changed, 20 insertions, 20 deletions

diff --git a/it.class b/it.class
index 4e37fde..660f1c9 100644
--- a/it.class
+++ b/it.class
@@ -694,25 +694,25 @@ static function imageconvert($p)
 
 
 /**
- * Parse command line options with Usage given as template and return assoc array. Example: (like grep --help)
- * Usage: myprogram.php [OPTIONS] PATTERN
+ * Parse command line options with Usage given as template and return assoc array.
+ * @param $usage Usage parsed to determine options, example see below.
+ * @param $p['optbeforearg'] Stop parsing options when first argument is encountered
+ * @return Associative array of options, key 'args' for optional non-option args
+ *
+ * Usage: myprogram.php [OPTIONS] PATTERN [MOREARGS]
  *  -s, --short      Use short ouput
  *  -f, --file=FILE  Use FILE for input [foo.txt]
  *  -x EXTENSION     Ignore EXTENSION
  * Mandatory arguments from the Usage: line are returned under their (lowercased!) name.
- * All non-option arguments are returned in 'args'
  * Option text must be indented; if long and short option present, value is stored in long one.
- * For long opts with arguments, = is mandatory. Defaults in [ ] at end of line
- * Options without arguments store true or false under their key
- * Options -h and --help will be handled internally by printing usage and exiting
- * When printing, the usage will be de-indented so the first line starts in the first column
+ * For long opts with arguments, = is mandatory in usage. Defaults in [ ] at end of line
  * Two or more blanks must be in front of option explanation
- * If an option 'verbose' is set, it will be set as debug variable as well so EDC('verbose', $bar) works
- * @param $helplines Usage parsed to determine options
- * @param $p['optbeforearg'] Stop parsing options when first argument is encountered
- * @return Associative array of options
+ * Options without arguments store true or false under their key
+ * Option --help or -h prints de-indented usage and exits (needs not be in usage)
+ * Option --debug foo-bar will store bar in EDC('foo'). (needs not be in usage)
+ * Option --verbose sets debug variable verbose for EDC('verbose', $bar). (must be in usage)
  */
-static function getopt($helplines, $p = array())
+static function getopt($usage, $p = array())
 {
 	$GLOBALS['it_stdin'] = array(
 		'fd' => null,
@@ -723,13 +723,13 @@ static function getopt($helplines, $p = array())
 
 	$result = array('args' => array());
 
-	if ($indentation = it::match('^\s+', $helplines))
-		$helplines = it::replace(array($indentation => "\n"), $helplines);
+	if ($indentation = it::match('^\s+', $usage))
+		$usage = it::replace(array($indentation => "\n"), $usage);
 
-	foreach(explode("\n", trim($helplines)) as $helpline)
+	foreach(explode("\n", trim($usage)) as $usageline)
 	{
 		$shortoptname = $shortoptarg = $longoptname = $longoptarg = "";
-		foreach (explode(',', $helpline) as $optdesc)
+		foreach (explode(',', $usageline) as $optdesc)
 		{
 			$optdesc = trim($optdesc);
 			if ($matches = (array)it::match('^--(\w[\w-]*)(=[A-Z])?', $optdesc))
@@ -738,7 +738,7 @@ static function getopt($helplines, $p = array())
 				list($shortoptname, $shortoptarg) = $matches;
 		}	
 
-		if ($default = it::match('\[(.*)\]\s*$', $helpline))
+		if ($default = it::match('\[(.*)\]\s*$', $usageline))
 		{
 			if ($longoptarg || $shortoptarg)
 				$defaults[$longoptname ? $longoptname : $shortoptname] = it::replace(array('^default:?\s*' => ""), trim($default));
@@ -757,9 +757,9 @@ static function getopt($helplines, $p = array())
 	$witharg['debug'] = true;
 
 	$mandatoryargs = array();
-	if ($tmp = trim(it::replace(array("\n.*" => "", "^\S+\s+\S+\s*" => "", "\[.*?\]\s*" => ""), trim($helplines))))
+	if ($tmp = trim(it::replace(array("\n.*" => "", "^\S+\s+\S+\s*" => "", "\[.*?\]\s*" => ""), trim($usage))))
 		$mandatoryargs = preg_split('/\s+/', $tmp);
-	if ($mandatoryargs && !it::match("Usage:", $helplines))
+	if ($mandatoryargs && !it::match("Usage:", $usage))
 		it::error("Usage string must contain 'Usage:'");
 
 	foreach (array_slice($_SERVER['argv'], 1) as $arg)
@@ -809,7 +809,7 @@ static function getopt($helplines, $p = array())
 
 	if ($err || $eat || $result['h'] || $result['help'] || $mandatoryargs)
 	{
-		fputs(($result['h'] || $result['help'] ? STDOUT : STDERR), trim($helplines) . "\n");
+		fputs(($result['h'] || $result['help'] ? STDOUT : STDERR), trim($usage) . "\n");
 		exit(1);
 	}