[Pkg-haskell-commits] [SCM] haskell-testpack branch, master, updated. debian/1.0.2-1-4-gb0d6b36
John Goerzen
jgoerzen at complete.org
Fri Apr 23 14:47:06 UTC 2010
The following commit has been merged in the master branch:
commit ae22966595497babc8d74c417143d6a6cdcc5850
Author: John Goerzen <jgoerzen at complete.org>
Date: Mon Nov 15 22:48:48 2004 +0100
Added more examples, docs for printf
Keywords:
(jgoerzen at complete.org--projects/missingh--head--0.5--patch-59)
diff --git a/ChangeLog b/ChangeLog
index dd75e70..473e45d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -2,6 +2,18 @@
# arch-tag: automatic-ChangeLog--jgoerzen at complete.org--projects/missingh--head--0.5
#
+2004-11-15 15:48:48 GMT John Goerzen <jgoerzen at complete.org> patch-59
+
+ Summary:
+ Added more examples, docs for printf
+ Revision:
+ missingh--head--0.5--patch-59
+
+
+ modified files:
+ ChangeLog TODO libsrc/MissingH/Printf.hs testsrc/Printftest.hs
+
+
2004-11-15 14:52:03 GMT John Goerzen <jgoerzen at complete.org> patch-58
Summary:
diff --git a/TODO b/TODO
index 792de17..09b6085 100644
--- a/TODO
+++ b/TODO
@@ -1,10 +1,5 @@
arch-tag: TODO file
Printf:
- document sub-modules
- make tests for all the examples
- show some functions in the examples
- make %H work -- probably just need a showValue function
- just make showValue :: Value -> String
- should be an easy "case" statement
+ make %H work
diff --git a/libsrc/MissingH/Printf.hs b/libsrc/MissingH/Printf.hs
index e28a7b8..8b1519d 100644
--- a/libsrc/MissingH/Printf.hs
+++ b/libsrc/MissingH/Printf.hs
@@ -34,73 +34,45 @@ Some code in sub-modules written by Ian Lynagh
Inspiration and ideas from haskell-xml-rpc by Bjorn Bringert
-Welcome to the Haskell printf support. This module is designed to emulate the
-C printf(3) family of functions. Here are some examples:
-
-
->> vsprintf "Hello"
-> "Hello"
->> vsprintf "Hello, %s\n" "John"
-> "Hello, John\n"
->> vsprintf "%s, your age is %d\n" "John" (10::Integer)
-> "John, your age is 10\n"
-
-Or, using the list-passing method:
-
->> sprintf "Hello" ([]::[Value])
-> "Hello"
->> sprintf "Hello, %s\n" [v "John"]
-> "Hello, John\n"
->> sprintf "%s, your age is %d\n" [v "John", v (10::Integer)]
-> "John, your age is 10\n"
-
-You can also work with I\/O with these:
-
-> let printer = do
-> printf "Line1\n"
-> printf "Line2: %s\n" "blah"
-
-This will print @Line1\\nLine2: blah\\n@ to standard output.
+Please scroll down to read the detailed documentation.
-As you can see, there are two different ways to access the printf functions:
-via the variable argument count support (the functions beginning with v)
-or via the list argument support. There is a utility function, 'v', that
-is simply a shortcut for 'toValue'.
-
-These functions are very similar to the C functions, with the following caveats:
+-}
-* There is no support for the length specifiers (l, etc.) since these make no
-sense in Haskell. Haskell's type system provides all the info we need.
+module MissingH.Printf(-- * Introduction
+ -- $introduction
-* If the type system cannot determine the type if an argument (as in the
-numeric literals above), you may have to explicitly cast it to something.
-In practice, this is only a problem in interactive situations like ghci or
-hugs.
+ -- * Methods of Use
+ -- $methodsofuse
-* If you are running in an interact situation, or something where the
-compiler cannot deduce the expected return type, you will need to cast it
-to @String at . For instance, at the ghci prompt, you would have to say
-@(sprintf \"foo\")::String@ to make things work. If you are using one of the
-I\/O variants, you will have to instead cast it to @IO ()@.
-
--}
-
-module MissingH.Printf(-- * Variable-Argument Ouptut
+ -- ** Variable-Argument Ouptut
vsprintf,
vprintf,
vfprintf,
- -- * List-Argument Output
+ -- *** Casting Notes
+ -- $castingnotes
+ ps, pio,
+
+ -- ** List-Argument Output
sprintf,
printf,
fprintf,
- -- * Utility Function
+ -- ** Utility Function
v,
+ -- * Differences from C
+ -- $differencesfromc
+
+ -- * Important Haskell Notes
+ -- $haskellnotes
+
+ -- * Full Example Programs
+ -- $fullexamples
+
-- * Underlying Types
Value(..),
PFRun,
PFType(..),
- IOPFRun,
- get_conversion_func
+ IOPFRun
+
) where
import MissingH.Str
@@ -197,3 +169,207 @@ vfprintf h f = iopfrun h $ sprintf f
an explicit Handle. -}
vprintf :: IOPFRun a => String -> a
vprintf f = vfprintf stdout f
+
+{- | Utility to force something to a string -}
+ps :: String -> String
+ps = id
+
+{- | Utility to force something to an IO () -}
+pio :: IO () -> IO ()
+pio = id
+
+----------------------------------------------------------------------
+-- Documentation for this module
+----------------------------------------------------------------------
+
+{- $introduction
+Welcome to the Haskell printf support. This module is designed to emulate the
+C printf(3) family of functions. Here are some quick introductory examples:
+
+#examples#
+
+>vsprintf "Hello"
+>> "Hello"
+>vsprintf "Hello, %s\n" "John"
+>> "Hello, John\n"
+>vsprintf "%s, your age is %d\n" "John" (10::Integer)
+>> "John, your age is 10\n"
+
+Or, using the list-passing method:
+
+>sprintf "Hello" []
+>> "Hello"
+>sprintf "Hello, %s\n" [v "John"]
+>> "Hello, John\n"
+>sprintf "%s, your age is %d\n" [v "John", v (10::Integer)]
+>> "John, your age is 10\n"
+
+You can also work with I\/O with these:
+
+>main :: IO ()
+>main = do
+> pio $ vprintf "Line1\n"
+> pio $ vprintf "Line2: %s\n" "blah"
+> vprintf "Line3: done\n"
+
+This will print @Line1\\nLine2: blah\\nLine3: done\\n@ to standard output.
+You can also use the list form:
+
+>main :: IO ()
+>main = do
+> printf "Line1\n" []
+> printf "Line2: %s\n" [v "blah"]
+> printf "Line3: done\n" []
+
+-}
+
+{- $methodsofuse
+As you can see, there are two different ways to access the printf functions:
+via the variable argument count support (the functions beginning with v)
+or via the list argument support. There is a utility function, 'v', that
+is simply a shortcut for 'toValue'.
+-}
+
+{- $castingnotes
+If you are running in an interactive situation, or something where the
+compiler cannot deduce the expected return type, you will need to cast it
+to @String at . For instance, at the ghci prompt, you would have to say
+@(sprintf \"foo\")::String@ to make things work. If you are using one of the
+I\/O variants, you will have to instead cast it to @IO ()@.
+
+To make this easier, there are two functions: 'ps' and 'pio'. They
+simply provide an easy idiom to force things to the proper type. Examples:
+
+>main :: IO ()
+>main = do
+> pio $ vprintf "Line1\n"
+> pio $ vprintf "Line2: %s\n" "blah"
+> vprintf "Line3: done\n"
+
+Note that in this case, no 'pio' was necessary for the third line.
+That's because @main@ was declared to return @IO ()@ already, so the type
+system knows what to do. If that declaration was missing, the 'pio'
+would have been required there as well.
+
+These special cases apply only to the \"v\" functions.
+-}
+
+
+{- $differencesfromc
+These functions are very similar to the C functions. Here is a list of the
+known differences:
+
+* There is a new conversion type %H. This will take any type of data
+already converted to a value and display it in its native representation from
+show. This may not be what you expect for integers, and is likely to be
+altered in the future, so use with caution.
+
+* There is no support for the length specifiers (l, ll, etc.) since Haskell's
+type system provides all the information we need.
+
+* There is no support for the %n, %*, %\$ forms that the C printf() supports.
+These make less sense in Haskell.
+
+-}
+
+{- $haskellnotes
+Please be aware of the following as you use this module:
+
+If the type system cannot determine the type of an argument (as in the
+numeric literals in the examples at "MissingH.Printf#examples"), you may have to explicitly cast it to something.
+In practice, this is only a problem in interactive situations like ghci or
+hugs.
+
+Floating-point values are converted to a Double for display. If you are
+using some floating-point value with an extremely high precision (such
+as a Rational), be aware that some of this precision may be lost for display.x
+
+When run with Hugs, you must use @-98 +o@ on your command line.
+
+-}
+
+{- $fullexamples
+
+Here are some full example programs. You can compile and run these directly.
+
+This example acts as a filter that adds a line number and length to each
+line from input:
+
+>import MissingH.Printf
+>
+>convlines :: Int -> [String] -> [String]
+>convlines _ [] = []
+>convlines count (line:xs) =
+> vsprintf "%6d, len %03d: %s" count (length line) line :
+> convlines (count + 1) xs
+>
+>main = interact $ unlines . convlines 1 . lines
+
+If you have a sample file like this:
+
+>Hello,
+>
+>This is a test.
+>Haskell is really neat.
+
+Then running @.\/test < file.txt@ will produce:
+
+> 1, len 006: Hello,
+> 2, len 000:
+> 3, len 015: This is a test.
+> 4, len 023: Haskell is really neat.
+
+And so on -- and everything will be nicely lined up since the line numbers
+will grow to the left.
+
+Here's another example of a little bit of interaction:
+
+>import MissingH.Printf
+>import System.IO
+>
+>main = do
+> hSetBuffering stdout NoBuffering
+> printf "Welcome. Please enter your name: " []
+> name <- getLine
+> printf "Hello, %s. Please enter your age: " [v name]
+> agestr <- getLine
+> let age = (read agestr)::Int
+> printf "%s, you are at least %d months old.\n" [v name, v $ age * 12]
+
+Here's a sample session:
+
+>Welcome. Please enter your name: Bill
+>Hello, Bill. Please enter your age: 53
+>Bill, you are at least 636 months old.
+
+The printf functions are also great for creating reports nicely lined up
+by column. Here's an example:
+
+>import MissingH.Printf
+>import MissingH.IO
+>import Data.List
+>
+>fmt = "%-10d %010d %010X"
+>
+>fmtlines :: Int -> [String] -> [String]
+>fmtlines _ [] = []
+>fmtlines count (x:xs) =
+> let l = length x in
+> vsprintf fmt count l l : fmtlines (count + 1) xs
+>
+>main = do
+> pio $ vprintf ("%-10s %-10s %s\n") "Line #" "Length Dec" "Length Hex"
+> putStrLn $ (replicate 10 '-') ++ " " ++ (replicate 10 '-') ++
+> " " ++ (replicate 10 '-')
+> lineInteract $ fmtlines 1
+
+When applied to the same example file as before, the output will be:
+
+>Line # Length Dec Length Hex
+>---------- ---------- ----------
+>1 0000000006 0000000006
+>2 0000000000 0000000000
+>3 0000000015 000000000F
+>4 0000000023 0000000017
+
+-}
\ No newline at end of file
diff --git a/testsrc/Printftest.hs b/testsrc/Printftest.hs
index 5f6bd27..b4a58ee 100644
--- a/testsrc/Printftest.hs
+++ b/testsrc/Printftest.hs
@@ -32,6 +32,13 @@ test_vsprintf =
"fe" @=? vsprintf "%x" (254::Integer)
"FE" @=? vsprintf "%X" (254::Integer)
"10" @=? vsprintf "%o" (8::Integer)
+ "Hello" @=? vsprintf "Hello"
+ "Hello, John\n" @=? vsprintf "Hello, %s\n" "John"
+ "John, your age is 10\n" @=? vsprintf "%s, your age is %d\n" "John" (10::Integer)
+ "Hello" @=? sprintf "Hello" []
+ "Hello, John\n" @=? sprintf "Hello, %s\n" [v "John"]
+ "John, your age is 10\n" @=? sprintf "%s, your age is %d\n" [v "John",
+ v (10::Integer)]
test_vsprintf_generics =
do
--
haskell-testpack
More information about the Pkg-haskell-commits
mailing list