Permalink
Browse files

Added readme syntax command description.

  • Loading branch information...
1 parent b80b5f5 commit e38d49ba6d79371a23dedab290a02034d07cbd36 @briannesbitt committed Sep 12, 2012
Showing with 69 additions and 12 deletions.
  1. +29 −0 readme.md
  2. +11 −12 readme.php
  3. +29 −0 readme.src.md
View
@@ -556,6 +556,35 @@ I hate reading a readme.md file that has code errors and/or sample output that i
Change the `readme.src.md` and then use the `readme.php` to generate the new `readme.md` file. It can be run at the command line using `php readme.php` from the project root. Maybe someday I'll extract this out to another project or at least run it with a post receive hook, but for now its just a local tool, deal with it.
+The commands are quickly explained below. To see some examples you can view the raw `readme.src.md` file in this repo.
+
+`{{::lint()}}`
+
+The `lint` command is meant for confirming the code is valid and will `eval()` the code passed into the function. Assuming there were no errors, the executed source code will then be injected back into the text replacing out the `{{::lint()}}`. When you look at the raw `readme.src.md` you will see that the code can span several lines. Remember the code is executed in the context of the running script so any variables will be availalbe for the rest of the file.
+
+ {{::lint($var = 'brian nesbitt';)}} => $var = 'brian nesbitt';
+
+> As mentioned the `$var` can later be echo'd and you would get 'brian nesbitt' as all of the source is executed in the same scope.
+
+`{{varName::exec()}}` and `{{varName_eval}}`
+
+The `exec` command begins by performing an `eval()` on the code passed into the function. The executed source code will then be injected back into the text replacing out the `{{varName::exec()}}`. This will also create a variable named `varName_eval` that you can then place anywhere in the file and it will get replaced with the output of the `eval()`. You can use any type of output (`echo`, `printf`, `var_dump` etc) statement to return the result value as an output buffer is setup to capture the output.
+
+ {{exVarName::exec(echo $var;)}} => echo $var;
+ {{exVarName_eval}} => brian nesbitt // $var is still set from above
+
+`/*pad()*/`
+
+The `pad()` is a special source modifier. This will pad the code block to the indicated number of characters using spaces. Its particularly handy for aligning `//` comments when showing results.
+
+ {{exVarName1::exec(echo 12345;/*pad(20)*/)}} // {{exVarName1_eval}}
+ {{exVarName2::exec(echo 6;/*pad(20)*/)}} // {{exVarName2_eval}}
+
+... would generate to:
+
+ echo 12345; // 12345
+ echo 6; // 6
+
Apart from the readme the typical steps can be used to contribute your own improvements.
* Fork
View
@@ -32,25 +32,21 @@
$ob = ob_get_clean();
if ($result === false) {
- echo "Failed lint check.";
-
- echo $src;
+ echo "Failed lint check.". PHP_EOL . PHP_EOL;
$error = error_get_last();
if ($error != null) {
- var_dump($error);
+ echo $error['message'] . ' on line ' . $error['line'] . PHP_EOL . PHP_EOL;
}
- exit(1);
- }
+ echo "---- eval'd source ---- " . PHP_EOL . PHP_EOL;
- // If something was just returned get that and remove the 'return' statement
- // since its probably not relevant to the sample
- if ($result !== null) {
- $ob .= $result;
- if (strpos($src, 'return ') === 0) {
- $src = str_replace('return ', '', $src);
+ $i = 1;
+ foreach (preg_split("/$[\n\r]^/m", $src) as $ln) {
+ printf('%3s : %s%s', $i++, $ln, PHP_EOL);
}
+
+ exit(1);
}
// remove the extra newline from a var_dump
@@ -73,4 +69,7 @@
}
}
+// allow for escaping a command
+$readme = str_replace('\{\{', '{{', $readme);
+
file_put_contents('readme.md', $readme);
View
@@ -572,6 +572,35 @@ I hate reading a readme.md file that has code errors and/or sample output that i
Change the `readme.src.md` and then use the `readme.php` to generate the new `readme.md` file. It can be run at the command line using `php readme.php` from the project root. Maybe someday I'll extract this out to another project or at least run it with a post receive hook, but for now its just a local tool, deal with it.
+The commands are quickly explained below. To see some examples you can view the raw `readme.src.md` file in this repo.
+
+`\{\{::lint()}}`
+
+The `lint` command is meant for confirming the code is valid and will `eval()` the code passed into the function. Assuming there were no errors, the executed source code will then be injected back into the text replacing out the `\{\{::lint()}}`. When you look at the raw `readme.src.md` you will see that the code can span several lines. Remember the code is executed in the context of the running script so any variables will be availalbe for the rest of the file.
+
+ \{\{::lint($var = 'brian nesbitt';)}} => {{::lint($var = 'brian nesbitt';)}}
+
+> As mentioned the `$var` can later be echo'd and you would get 'brian nesbitt' as all of the source is executed in the same scope.
+
+`\{\{varName::exec()}}` and `{{varName_eval}}`
+
+The `exec` command begins by performing an `eval()` on the code passed into the function. The executed source code will then be injected back into the text replacing out the `\{\{varName::exec()}}`. This will also create a variable named `varName_eval` that you can then place anywhere in the file and it will get replaced with the output of the `eval()`. You can use any type of output (`echo`, `printf`, `var_dump` etc) statement to return the result value as an output buffer is setup to capture the output.
+
+ \{\{exVarName::exec(echo $var;)}} => {{exVarName::exec(echo $var;)}}
+ \{\{exVarName_eval}} => {{exVarName_eval}} // $var is still set from above
+
+`/*pad()*/`
+
+The `pad()` is a special source modifier. This will pad the code block to the indicated number of characters using spaces. Its particularly handy for aligning `//` comments when showing results.
+
+ \{\{exVarName1::exec(echo 12345;/*pad(20)*/)}} // \{\{exVarName1_eval}}
+ \{\{exVarName2::exec(echo 6;/*pad(20)*/)}} // \{\{exVarName2_eval}}
+
+... would generate to:
+
+ {{exVarName1::exec(echo 12345;/*pad(20)*/)}} // {{exVarName1_eval}}
+ {{exVarName2::exec(echo 6;/*pad(20)*/)}} // {{exVarName2_eval}}
+
Apart from the readme the typical steps can be used to contribute your own improvements.
* Fork

0 comments on commit e38d49b

Please sign in to comment.