Skip to content

Commit 8900fc1

Browse files
committed
Finished Haddocks everywhere, trimmed API
Added some examples and explanations to the Haddocks. The APIs for the 'Parse' and 'Pretty' module are now symmetric.
1 parent 7311313 commit 8900fc1

23 files changed

+635
-296
lines changed

language-rust.cabal

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@ license: BSD3
1010
license-file: LICENSE
1111
author: Alec Theriault
1212
maintainer: alec.theriault@gmail.com
13-
copyright: (c) 2017 Alec Theriault
14-
stability: alpha
13+
copyright: (c) 2017-2018 Alec Theriault
14+
stability: provisional
1515
bug-reports: https://github.com/harpocrates/language-rust/issues
1616
category: Language
1717
build-type: Simple

src/Language/Rust/Data/Ident.hs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{-|
22
Module : Language.Rust.Data.Ident
33
Description : Identifiers
4-
Copyright : (c) Alec Theriault, 2017
4+
Copyright : (c) Alec Theriault, 2017-2018
55
License : BSD-style
66
Maintainer : alec.theriault@gmail.com
77
Stability : experimental

src/Language/Rust/Data/InputStream.hs

Lines changed: 63 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,18 @@
11
{-|
22
Module : Language.Rust.Data.InputStream
33
Description : Interface to the underlying input of parsing
4-
Copyright : (c) Alec Theriault, 2017
4+
Copyright : (c) Alec Theriault, 2017-2018
55
License : BSD-style
66
Maintainer : alec.theriault@gmail.com
77
Stability : experimental
88
Portability : portable
99
1010
These are the only functions that need to be implemented in order to use the parser. Whether this
1111
wraps 'ByteString' or 'String' depends on whether the @useByteStrings@ option is on or not (it is
12-
by default). Using 'ByteString' means better handling of weird characters ('takeByte' fails badly
13-
if you try to take a byte that doesn't fall on a character boundary), but it means incurring a
14-
dependency on the [utf8-string](https://hackage.haskell.org/package/utf8-string) package.
12+
by default). Using 'ByteString' means better handling of weird characters ('takeByte' for plain old
13+
'String' fails badly if you try to take a byte that doesn't fall on a character boundary), but it
14+
means incurring a dependency on the [utf8-string](https://hackage.haskell.org/package/utf8-string)
15+
package.
1516
-}
1617
{-# LANGUAGE CPP #-}
1718

@@ -45,50 +46,95 @@ import qualified Data.ByteString.UTF8 as BE
4546
import qualified Data.Char as Char
4647
#endif
4748

48-
-- | Read a file into an 'InputStream'
49+
-- | Read an encoded file into an 'InputStream'
4950
readInputStream :: FilePath -> IO InputStream
5051
{-# INLINE readInputStream #-}
5152

5253
-- | Read an 'InputStream' from a 'Handle'
5354
hReadInputStream :: Handle -> IO InputStream
5455
{-# INLINE hReadInputStream #-}
5556

56-
-- | Convert 'InputStream' to 'String'
57+
-- | Convert 'InputStream' to 'String'.
5758
inputStreamToString :: InputStream -> String
5859
{-# INLINE inputStreamToString #-}
5960

60-
-- | Convert a 'String' to an 'InputStream'
61+
-- | Convert a 'String' to an 'InputStream'.
6162
inputStreamFromString :: String -> InputStream
6263
{-# INLINE inputStreamFromString #-}
6364

65+
-- | Uses 'inputStreamFromString'
6466
instance IsString InputStream where fromString = inputStreamFromString
6567

6668
-- | Read the first byte from an 'InputStream' and return that byte with what remains of the
67-
-- 'InputStream'. Should only be called when 'inputStreamEmpty' returns 'False'.
69+
-- 'InputStream'. Behaviour is undefined when 'inputStreamEmpty' returns 'True'.
70+
--
71+
-- >>> takeByte "foo bar"
72+
-- (102, "oo bar")
73+
--
74+
-- >>> takeByte "Ĥăƨĸëļļ"
75+
-- (196, "\ETX\168\&8\235<<")
76+
--
6877
takeByte :: InputStream -> (Word8, InputStream)
6978
{-# INLINE takeByte #-}
7079

7180
-- | Read the first character from an 'InputStream' and return that 'Char' with what remains of the
72-
-- 'InputStream'. Should only be called when 'inputStreamEmpty' returns 'False'.
81+
-- 'InputStream'. Behaviour is undefined when 'inputStreamEmpty' returns 'True'.
82+
--
83+
-- >>> takeChar "foo bar"
84+
-- ('f', "oo bar")
85+
--
86+
-- >>> takeChar "Ĥăƨĸëļļ"
87+
-- ('Ĥ', "ăƨĸëļļ")
88+
--
7389
takeChar :: InputStream -> (Char, InputStream)
7490
{-# INLINE takeChar #-}
7591

7692
-- | Return @True@ if the given input stream is empty.
93+
--
94+
-- >>> inputStreamEmpty ""
95+
-- True
96+
--
97+
-- >>> inputStreamEmpty "foo"
98+
-- False
99+
--
77100
inputStreamEmpty :: InputStream -> Bool
78101
{-# INLINE inputStreamEmpty #-}
79102

80103
-- | Returns the first @n@ characters of the given input stream, without removing them.
104+
--
105+
-- >>> peekChars 5 "foo bar"
106+
-- "foo ba"
107+
--
108+
-- >>> peekChars 5 "foo"
109+
-- "foo"
110+
--
111+
-- >>> peekChars 3 "Ĥăƨĸëļļ"
112+
-- "Ĥăƨ"
113+
--
81114
peekChars :: Int -> InputStream -> String
82115
{-# INLINE peekChars #-}
83116

84117
-- | Returns the number of text lines in the given 'InputStream'
118+
--
119+
-- >>> countLines ""
120+
-- 0
121+
--
122+
-- >>> countLines "foo"
123+
-- 1
124+
--
125+
-- >>> countLines "foo\n\nbar"
126+
-- 3
127+
--
128+
-- >>> countLines "foo\n\nbar\n"
129+
-- 3
130+
--
85131
countLines :: InputStream -> Int
86132
{-# INLINE countLines #-}
87133

88134
#ifdef USE_BYTESTRING
89135

90136
-- | Opaque input type.
91-
newtype InputStream = IS BS.ByteString
137+
newtype InputStream = IS BS.ByteString deriving (Eq, Ord)
92138
takeByte bs = (BS.head (coerce bs), coerce (BS.tail (coerce bs)))
93139
takeChar bs = maybe (error "takeChar: no char left") coerce (BE.uncons (coerce bs))
94140
inputStreamEmpty = BS.null . coerce
@@ -99,10 +145,13 @@ inputStreamToString = BE.toString . coerce
99145
inputStreamFromString = IS . BE.fromString
100146
countLines = length . BE.lines . coerce
101147

148+
instance Show InputStream where
149+
show (IS bs) = show bs
150+
102151
#else
103152

104153
-- | Opaque input type.
105-
newtype InputStream = IS String
154+
newtype InputStream = IS String deriving (Eq, Ord)
106155
takeByte (IS ~(c:str))
107156
| Char.isLatin1 c = let b = fromIntegral (Char.ord c) in b `seq` (b, IS str)
108157
| otherwise = error "takeByte: not a latin-1 character"
@@ -115,4 +164,7 @@ inputStreamToString = coerce
115164
inputStreamFromString = IS
116165
countLines (IS str) = length . lines $ str
117166

167+
instance Show InputStream where
168+
show (IS bs) = show bs
169+
118170
#endif

src/Language/Rust/Data/Position.hs

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{-|
22
Module : Language.Rust.Data.Position
33
Description : Positions and spans in files
4-
Copyright : (c) Alec Theriault, 2017
4+
Copyright : (c) Alec Theriault, 2017-2018
55
License : BSD-style
66
Maintainer : alec.theriault@gmail.com
77
Stability : experimental
@@ -54,7 +54,16 @@ data Position = Position {
5454
col :: {-# UNPACK #-} !Int -- ^ column in the source file.
5555
}
5656
| NoPosition
57-
deriving (Eq, Ord, Show, Data, Typeable, Generic, NFData)
57+
deriving (Eq, Ord, Data, Typeable, Generic, NFData)
58+
59+
-- | Field names are shown
60+
instance Show Position where
61+
showsPrec _ NoPosition = showString "NoPosition"
62+
showsPrec p (Position a r c) = showParen (p >= 11)
63+
( showString "Position"
64+
. showString " " . showsPrec 11 a
65+
. showString " " . showsPrec 11 r
66+
. showString " " . showsPrec 11 c )
5867

5968
-- | Pretty print a 'Position'
6069
prettyPosition :: Position -> String
@@ -116,7 +125,15 @@ incOffset p@Position{ absoluteOffset = a } offset = p { absoluteOffset = a + off
116125
-- | Spans represent a contiguous region of code, delimited by two 'Position's. The endpoints are
117126
-- inclusive. Analogous to the information encoded in a selection.
118127
data Span = Span { lo, hi :: !Position }
119-
deriving (Eq, Ord, Show, Data, Typeable, Generic, NFData)
128+
deriving (Eq, Ord, Data, Typeable, Generic, NFData)
129+
130+
-- | Field names are not shown
131+
instance Show Span where
132+
showsPrec p (Span l h) = showParen (p >= 11)
133+
( showString "Span"
134+
. showString " " . showsPrec 11 l
135+
. showString " " . showsPrec 11 h )
136+
120137

121138
-- | Check if a span is a subset of another span
122139
subsetOf :: Span -> Span -> Bool

0 commit comments

Comments
 (0)