Skip to content
This repository
Browse code

Added readme syntax command description.

  • Loading branch information...
commit e38d49ba6d79371a23dedab290a02034d07cbd36 1 parent b80b5f5
Brian Nesbitt authored September 12, 2012
29  readme.md
Source Rendered
@@ -556,6 +556,35 @@ I hate reading a readme.md file that has code errors and/or sample output that i
556 556
 
557 557
 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.
558 558
 
  559
+The commands are quickly explained below.  To see some examples you can view the raw `readme.src.md` file in this repo.
  560
+
  561
+`{{::lint()}}`
  562
+
  563
+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.
  564
+
  565
+    {{::lint($var = 'brian nesbitt';)}} => $var = 'brian nesbitt';
  566
+
  567
+> 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.
  568
+
  569
+`{{varName::exec()}}` and `{{varName_eval}}`
  570
+
  571
+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.
  572
+
  573
+    {{exVarName::exec(echo $var;)}} => echo $var;
  574
+    {{exVarName_eval}} => brian nesbitt  // $var is still set from above
  575
+
  576
+`/*pad()*/`
  577
+
  578
+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.
  579
+
  580
+    {{exVarName1::exec(echo 12345;/*pad(20)*/)}} // {{exVarName1_eval}}
  581
+    {{exVarName2::exec(echo 6;/*pad(20)*/)}} // {{exVarName2_eval}}
  582
+
  583
+... would generate to:
  584
+
  585
+    echo 12345;          // 12345
  586
+    echo 6;              // 6
  587
+
559 588
 Apart from the readme the typical steps can be used to contribute your own improvements.
560 589
 
561 590
 * Fork
23  readme.php
@@ -32,25 +32,21 @@
32 32
     $ob = ob_get_clean();
33 33
 
34 34
     if ($result === false) {
35  
-        echo "Failed lint check.";
36  
-
37  
-        echo $src;
  35
+        echo "Failed lint check.". PHP_EOL . PHP_EOL;
38 36
 
39 37
         $error = error_get_last();
40 38
         if ($error != null) {
41  
-            var_dump($error);
  39
+            echo $error['message'] . ' on line ' . $error['line'] . PHP_EOL . PHP_EOL;
42 40
         }
43 41
 
44  
-        exit(1);
45  
-    }
  42
+        echo "---- eval'd source ---- " . PHP_EOL . PHP_EOL;
46 43
 
47  
-    // If something was just returned get that and remove the 'return' statement
48  
-    //  since its probably not relevant to the sample
49  
-    if ($result !== null) {
50  
-        $ob .= $result;
51  
-        if (strpos($src, 'return ') === 0) {
52  
-            $src = str_replace('return ', '', $src);
  44
+        $i = 1;
  45
+        foreach (preg_split("/$[\n\r]^/m", $src) as $ln) {
  46
+            printf('%3s : %s%s', $i++, $ln, PHP_EOL);
53 47
         }
  48
+
  49
+        exit(1);
54 50
     }
55 51
 
56 52
     // remove the extra newline from a var_dump
@@ -73,4 +69,7 @@
73 69
     }
74 70
 }
75 71
 
  72
+// allow for escaping a command
  73
+$readme = str_replace('\{\{', '{{', $readme);
  74
+
76 75
 file_put_contents('readme.md', $readme);
29  readme.src.md
Source Rendered
@@ -572,6 +572,35 @@ I hate reading a readme.md file that has code errors and/or sample output that i
572 572
 
573 573
 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.
574 574
 
  575
+The commands are quickly explained below.  To see some examples you can view the raw `readme.src.md` file in this repo.
  576
+
  577
+`\{\{::lint()}}`
  578
+
  579
+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.
  580
+
  581
+    \{\{::lint($var = 'brian nesbitt';)}} => {{::lint($var = 'brian nesbitt';)}}
  582
+
  583
+> 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.
  584
+
  585
+`\{\{varName::exec()}}` and `{{varName_eval}}`
  586
+
  587
+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.
  588
+
  589
+    \{\{exVarName::exec(echo $var;)}} => {{exVarName::exec(echo $var;)}}
  590
+    \{\{exVarName_eval}} => {{exVarName_eval}}  // $var is still set from above
  591
+
  592
+`/*pad()*/`
  593
+
  594
+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.
  595
+
  596
+    \{\{exVarName1::exec(echo 12345;/*pad(20)*/)}} // \{\{exVarName1_eval}}
  597
+    \{\{exVarName2::exec(echo 6;/*pad(20)*/)}} // \{\{exVarName2_eval}}
  598
+
  599
+... would generate to:
  600
+
  601
+    {{exVarName1::exec(echo 12345;/*pad(20)*/)}} // {{exVarName1_eval}}
  602
+    {{exVarName2::exec(echo 6;/*pad(20)*/)}} // {{exVarName2_eval}}
  603
+
575 604
 Apart from the readme the typical steps can be used to contribute your own improvements.
576 605
 
577 606
 * Fork

0 notes on commit e38d49b

Please sign in to comment.
Something went wrong with that request. Please try again.