Lots of documentation updates
[ganeti-local] / Ganeti / HTools / Utils.hs
1 {-| Utility functions -}
2
3 module Ganeti.HTools.Utils
4     (
5       debug
6     , sepSplit
7     , varianceCoeff
8     , readData
9     , commaJoin
10     , readEitherString
11     , loadJSArray
12     , fromObj
13     , asJSObject
14     , asObjectList
15     , fromJResult
16     ) where
17
18 import Data.List
19 import Control.Monad
20 import System
21 import System.IO
22 import qualified Text.JSON as J
23 import Text.Printf (printf)
24
25 import Ganeti.HTools.Types
26
27 import Debug.Trace
28
29 -- * Debug functions
30
31 -- | To be used only for debugging, breaks referential integrity.
32 debug :: Show a => a -> a
33 debug x = trace (show x) x
34
35 -- * Miscelaneous
36
37 -- | Comma-join a string list.
38 commaJoin :: [String] -> String
39 commaJoin = intercalate ","
40
41 -- | Split a string on a separator and return an array.
42 sepSplit :: Char -> String -> [String]
43 sepSplit sep s
44     | x == "" && xs == [] = []
45     | xs == []            = [x]
46     | ys == []            = x:"":[]
47     | otherwise           = x:(sepSplit sep ys)
48     where (x, xs) = break (== sep) s
49           ys = drop 1 xs
50
51 -- | Partial application of sepSplit to @'.'@
52 commaSplit :: String -> [String]
53 commaSplit = sepSplit ','
54
55 -- * Mathematical functions
56
57 -- Simple and slow statistical functions, please replace with better versions
58
59 -- | Mean value of a list.
60 meanValue :: Floating a => [a] -> a
61 meanValue lst = (sum lst) / (fromIntegral $ length lst)
62
63 -- | Standard deviation.
64 stdDev :: Floating a => [a] -> a
65 stdDev lst =
66     let mv = meanValue lst
67         square = (^ (2::Int)) -- silences "defaulting the constraint..."
68         av = sum $ map square $ map (\e -> e - mv) lst
69         bv = sqrt (av / (fromIntegral $ length lst))
70     in bv
71
72 -- | Coefficient of variation.
73 varianceCoeff :: Floating a => [a] -> a
74 varianceCoeff lst = (stdDev lst) / (fromIntegral $ length lst)
75
76 -- | Get an Ok result or print the error and exit.
77 readData :: Result a -> IO a
78 readData nd =
79     (case nd of
80        Bad x -> do
81          putStrLn x
82          exitWith $ ExitFailure 1
83        Ok x -> return x)
84
85 -- * JSON-related functions
86
87 -- | Converts a JSON Result into a monadic value.
88 fromJResult :: Monad m => J.Result a -> m a
89 fromJResult (J.Error x) = fail x
90 fromJResult (J.Ok x) = return x
91
92 -- | Tries to read a string from a JSON value.
93 --
94 -- In case the value was not a string, we fail the read (in the
95 -- context of the current monad.
96 readEitherString :: (Monad m) => J.JSValue -> m String
97 readEitherString v =
98     case v of
99       J.JSString s -> return $ J.fromJSString s
100       _ -> fail "Wrong JSON type"
101
102 -- | Converts a JSON message into an array of JSON objects.
103 loadJSArray :: (Monad m) => String -> m [J.JSObject J.JSValue]
104 loadJSArray s = fromJResult $ J.decodeStrict s
105
106 -- | Reads a the value of a key in a JSON object.
107 fromObj :: (J.JSON a, Monad m) => String -> J.JSObject J.JSValue -> m a
108 fromObj k o =
109     case lookup k (J.fromJSObject o) of
110       Nothing -> fail $ printf "key '%s' not found in %s" k (show o)
111       Just val -> fromJResult $ J.readJSON val
112
113 -- | Converts a JSON value into a JSON object.
114 asJSObject :: (Monad m) => J.JSValue -> m (J.JSObject J.JSValue)
115 asJSObject (J.JSObject a) = return a
116 asJSObject _ = fail "not an object"
117
118 -- | Coneverts a list of JSON values into a list of JSON objects.
119 asObjectList :: (Monad m) => [J.JSValue] -> m [J.JSObject J.JSValue]
120 asObjectList = sequence . map asJSObject