@@ -38,11 +38,16 @@ module Data.Aeson
3838 , eitherDecode
3939 , eitherDecode'
4040 , encode
41+ , encodeFile
4142 -- ** Variants for strict bytestrings
4243 , decodeStrict
44+ , decodeFileStrict
4345 , decodeStrict'
46+ , decodeFileStrict'
4447 , eitherDecodeStrict
48+ , eitherDecodeFileStrict
4549 , eitherDecodeStrict'
50+ , eitherDecodeFileStrict'
4651 -- * Core JSON types
4752 , Value(..)
4853 , Encoding
@@ -143,6 +148,10 @@ import qualified Data.ByteString.Lazy as L
143148encode :: (ToJSON a) => a -> L.ByteString
144149encode = encodingToLazyByteString . toEncoding
145150
151+-- | Efficiently serialize a JSON value as a lazy 'L.ByteString' and write it to a file.
152+encodeFile :: (ToJSON a) => FilePath -> a -> IO ()
153+encodeFile fp = L.writeFile fp . encode
154+
146155-- | Efficiently deserialize a JSON value from a lazy 'L.ByteString'.
147156-- If this fails due to incomplete or invalid input, 'Nothing' is
148157-- returned.
@@ -169,6 +178,18 @@ decodeStrict :: (FromJSON a) => B.ByteString -> Maybe a
169178decodeStrict = decodeStrictWith jsonEOF fromJSON
170179{-# INLINE decodeStrict #-}
171180
181+-- | Efficiently deserialize a JSON value from a file.
182+-- If this fails due to incomplete or invalid input, 'Nothing' is
183+-- returned.
184+--
185+-- The input file's content must consist solely of a JSON document,
186+-- with no trailing data except for whitespace.
187+--
188+-- This function parses immediately, but defers conversion. See
189+-- 'json' for details.
190+decodeFileStrict :: (FromJSON a) => FilePath -> IO (Maybe a)
191+decodeFileStrict = fmap decodeStrict . B.readFile
192+
172193-- | Efficiently deserialize a JSON value from a lazy 'L.ByteString'.
173194-- If this fails due to incomplete or invalid input, 'Nothing' is
174195-- returned.
@@ -195,6 +216,18 @@ decodeStrict' :: (FromJSON a) => B.ByteString -> Maybe a
195216decodeStrict' = decodeStrictWith jsonEOF' fromJSON
196217{-# INLINE decodeStrict' #-}
197218
219+-- | Efficiently deserialize a JSON value from a file.
220+-- If this fails due to incomplete or invalid input, 'Nothing' is
221+-- returned.
222+--
223+-- The input file's content must consist solely of a JSON document,
224+-- with no trailing data except for whitespace.
225+--
226+-- This function parses and performs conversion immediately. See
227+-- 'json'' for details.
228+decodeFileStrict' :: (FromJSON a) => FilePath -> IO (Maybe a)
229+decodeFileStrict' = fmap decodeStrict' . B.readFile
230+
198231eitherFormatError :: Either (JSONPath, String) a -> Either String a
199232eitherFormatError = either (Left . uncurry formatError) Right
200233{-# INLINE eitherFormatError #-}
@@ -210,6 +243,12 @@ eitherDecodeStrict =
210243 eitherFormatError . eitherDecodeStrictWith jsonEOF ifromJSON
211244{-# INLINE eitherDecodeStrict #-}
212245
246+-- | Like 'decodeFileStrict' but returns an error message when decoding fails.
247+eitherDecodeFileStrict :: (FromJSON a) => FilePath -> IO (Either String a)
248+eitherDecodeFileStrict =
249+ fmap (eitherFormatError . eitherDecodeStrictWith jsonEOF ifromJSON) . B.readFile
250+{-# INLINE eitherDecodeFileStrict #-}
251+
213252-- | Like 'decode'' but returns an error message when decoding fails.
214253eitherDecode' :: (FromJSON a) => L.ByteString -> Either String a
215254eitherDecode' = eitherFormatError . eitherDecodeWith jsonEOF' ifromJSON
@@ -221,6 +260,12 @@ eitherDecodeStrict' =
221260 eitherFormatError . eitherDecodeStrictWith jsonEOF' ifromJSON
222261{-# INLINE eitherDecodeStrict' #-}
223262
263+-- | Like 'decodeFileStrict'' but returns an error message when decoding fails.
264+eitherDecodeFileStrict' :: (FromJSON a) => FilePath -> IO (Either String a)
265+eitherDecodeFileStrict' =
266+ fmap (eitherFormatError . eitherDecodeStrictWith jsonEOF' ifromJSON) . B.readFile
267+{-# INLINE eitherDecodeFileStrict' #-}
268+
224269-- $use
225270--
226271-- This section contains basic information on the different ways to