line filter docco example

096-line-filter.go

@@ -1,49 +1,56 @@
-package main                                // A line-filter program reads input on stdin,
-                                            // processes it, and prints results to stdout.
-                                            // Here is an example line filter that writes a
-                                            // a captialized version of all text it reads.
+// ## Line Filter
 
-import "bufio"                              // Package `bufio` will help us read line-by-line.
+// A line filter program reads input on stdin,
+// processes it, and prints results to stdout.
+// Here's an example line filter that writes
+// a capitalized version of all text it reads.
+package main
+
+// Package `bufio` will help us read line-by-line.
+import "bufio"                              
 import "bytes"
 import "os"
 import "io"
 
-func main() {
-    newline := []byte("\n")                 // We'll need to add our own newlines
-                                            // between processed lines.
+// We'll need to add our own newlines between
+// processed lines.
+func main() {                               
+    newline := []byte("\n")                
 
-    in  := bufio.NewReader(os.Stdin)        // The buffered reader gives us `ReadLine`.
+    // The buffered reader gives us `ReadLine`.
+    in  := bufio.NewReader(os.Stdin)        
     out := os.Stdout
 
-    for {                                   // If succesful, each `ReadLine` returns bytes and a
-        inBytes, pfx, err := in.ReadLine()  // boolean indicating if don't have the whole line yet.
+    // If successful, each `ReadLine` returns bytes and a
+    // boolean indicating if don't have the whole line yet.
+    for {                                   
+        inBytes, pfx, err := in.ReadLine()  
         
-        if err == io.EOF {                  // The `EOF` error is expected when we reach the end
-            return                          // of the input, so exit gracefully in that case.
-        }                                   // Otherwise there is a problem.
+        // The `EOF` error is expected when we reach the end
+        // of the input, so exit gracefully in that case.
+        // Otherwise there is a problem.
+        if err == io.EOF {                  
+            return                          
+        }                                   
         if err != nil {
             panic (err)
         }       
 
-        outBytes := bytes.ToUpper(inBytes)  // `bytes.ToUpper` works directly on bytes, so we don't
-                                            // need to convert to a string for `strings.ToUpper`.
-
-        _, err = out.Write(outBytes)        // Write out the upercased bytes, checking for an error
-        if err != nil {                     // here as well.
+        // `bytes.ToUpper` works directly on bytes, so we don't
+        // need to convert to a string for `strings.ToUpper`.
+        outBytes := bytes.ToUpper(inBytes)  
+                                            
+        // Write out the upercased bytes, checking for an error
+        // here as well.
+        _, err = out.Write(outBytes)        
+        if err != nil {                    
             panic(err)
         }
 
-        if !pfx {                           // Unless this read was for a prefix (not the full
-            out.Write(newline)              // line), we need to add our own newline.
+        // Unless this read was for a prefix (not the full
+        // line), we need to add our own newline.
+        if !pfx {                           
+            out.Write(newline)              
         }        
     }
 }
-
-/*
-$ cat > lines                               // Make a file with a few lowercase lines.
-hello
-filter
-$ cat lines | go run line-filter.go         // Use the line filter to get upercase lines.
-HELLO
-FILTER
-*/

096-line-filter.sh

@@ -0,0 +1,9 @@
+# Make a file with a few lowercase lines.
+$ cat > lines                               
+hello
+filter
+
+# Use the line filter to get uppercase lines.
+$ cat lines | go run line-filter.go
+HELLO
+FILTER