Docs + saner 'Show' instances

* Removed "pretty" 'Show' instances in favour of derived ones and
  new 'Pretty' instances
* Updated examples
* Be consistent: pretty print, not pretty-print
* Spelling + grammar

Author: harpocrates

.travis.yml

@@ -3,14 +3,16 @@ sudo: true
 
 # Add new environments to the build here:
 env:
-  - GHCVER=7.10.3 CABALVER=1.22
+  - GHCVER=7.10.3 CABALVER=1.22 
   - GHCVER=8.0.2  CABALVER=1.24
-  - GHCVER=8.2.1  CABALVER=2.0
+  - GHCVER=8.2.2  CABALVER=2.0
+  - GHCVER=8.4.1  CABALVER=head
   - GHCVER=head   CABALVER=head
 
 # Allow for develop branch to break
 matrix:
   allow_failures:
+    - env: GHCVER=8.4.1  CABALVER=head
     - env: GHCVER=head   CABALVER=head
 
 # Manually install ghc and cabal

ChangeLog.md

@@ -1,11 +1,11 @@
 # Revision history for language-rust
 
-## 0.1.0.0  -- YYYY-mm-dd
+## 0.1.0.26  -- 2018-03-01
 
-* First version. Released on an unsuspecting world.
 * Parser module (using Alex and Happy)
-* Pretty-printing module (using Wadler's prettier)
+* Pretty printing module
 * Resolving module for validating ASTs
 * Unit testsuite
 * Difference testsuite
-* Benchmarks
+* Allocation benchmarks
+* Timing benchmarks

README.md

@@ -1,9 +1,8 @@
-# Parser and pretty-printer for Rust [![Build Status][4]][5] [![Windows build status][7]][8]
+# Parser and pretty printer for Rust [![Build Status][4]][5] [![Windows build status][7]][8]
 
-`language-rust` aspires to efficiently and accurately parse and pretty-print the [Rust language][0].
+`language-rust` aspires to efficiently and accurately parse and pretty print the [Rust language][0].
 The underlying AST structures are also intended to be as similar as possible to the [`libsyntax` AST
-`rustc`][10] uses itself. When `language-rust` and `rustc` have diverging AST, the divergence should
-be detailed in the documentation.
+that `rustc`][10] itself uses.
 
 A typical use looks like:
 
@@ -18,7 +17,7 @@ inp :: InputStream
 >>> let sourceFile = parse' @(SourceFile Span) inp
 sourceFile :: SourceFile Span
 
->>> -- Sample use of the pretty-printer
+>>> -- Sample use of the pretty printer
 >>> import Language.Rust.Pretty
 >>> pretty' sourceFile
 fn main() {
@@ -52,8 +51,10 @@ happy-1.19.8`.
 
 ## Evolution of Rust
 
-As Rust evolves, so will `language-rust`. We will make a best effort to support unstable features
-from nightly as they come out, but in general will only target compatibility with stable.
+As Rust evolves, so will `language-rust`. A best effort will be made to support unstable features
+from nightly as they come out, but only compatibility with stable is guaranteed. The last component
+of the version number indicates the nightly Rust compiler version against which tests were run. For
+example, `0.1.0.26` is tested against `rustc 1.26.0-nightly`.
 
 ## Bugs
 
@@ -62,7 +63,7 @@ Please report any bugs to the [github issue tracker][9].
 ### Parser
 
 Any difference between what is accepted by the `rustc` parser and the `language-rust` parser
-indicates
+indicates one of
 
   * a bug in `language-rust` (this is almost always the case)
   * a bug in `rustc`
@@ -71,11 +72,11 @@ indicates
 If the AST/parser of `rustc` changes, the `rustc-tests` test suite should start failing - it
 compares the JSON AST debug output of `rustc` to our parsed AST.
 
-### Pretty-printer
+### Pretty printer
 
-For the pretty-printer, bugs are a bit tougher to list exhaustively. Suggestions for better layout
+For the pretty printer, bugs are a bit tougher to list exhaustively. Suggestions for better layout
 algorithms are most welcome! The [`fmt-rfcs`][6] repo is loosely used as the reference for "correct"
-pretty-printing.
+pretty printing.
 
 [0]: https://www.rust-lang.org/en-US/
 [1]: https://docs.haskellstack.org/en/stable/README/

language-rust.cabal

@@ -1,9 +1,9 @@
 name:                language-rust
-version:             0.1.0.0
+version:             0.1.0.26
 
 synopsis:            Parsing and pretty printing of Rust code
-description:         Language Rust is a well tested library for converting Rust source code into
-                     and out of abstract syntax trees.
+description:         Language Rust is a library for the analysis of Rust code. It includes a
+                     complete, well tested parser and pretty printer. 
 
 homepage:            https://github.com/harpocrates/language-rust
 license:             BSD3
@@ -48,6 +48,7 @@ library
                        Language.Rust.Parser
                        Language.Rust.Parser.ParseMonad
                        Language.Rust.Parser.Lexer
+                       Language.Rust.Parser.Internal
                        Language.Rust.Pretty
                        Language.Rust.Pretty.Internal
                        Language.Rust.Data.Position
@@ -56,8 +57,7 @@ library
   if flag(enableQuasiquotes)
     exposed-modules:   Language.Rust.Quote
 
-  other-modules:       Language.Rust.Parser.Internal
-                       Language.Rust.Parser.Literals
+  other-modules:       Language.Rust.Parser.Literals
                        Language.Rust.Parser.Reversed
                        Language.Rust.Pretty.Resolve
                        Language.Rust.Pretty.Literals

src/Language/Rust/Data/Ident.hs

@@ -32,8 +32,9 @@ data Ident
           , hash :: {-# UNPACK #-} !Int  -- ^ hash for quick comparision
           } deriving (Data, Typeable, Generic, NFData)
 
+-- | Shows the identifier as a string (for use with @-XOverloadedStrings@)
 instance Show Ident where
-  show = name
+  show = show . name
 
 instance IsString Ident where
   fromString = mkIdent

src/Language/Rust/Data/InputStream.hs

@@ -8,8 +8,8 @@ Stability   : experimental
 Portability : portable
 
 These are the only functions that need to be implemented in order to use the parser. Whether this
-wraps 'ByteString' or 'String' depends on whether the @useByteStrings@ option is on or not (it is
-by default). Using 'ByteString' means better handling of weird characters ('takeByte' for plain old
+wraps 'BS.ByteString' or 'String' depends on whether the @useByteStrings@ option is on or not (it is
+by default). Using 'BS.ByteString' means better handling of weird characters ('takeByte' for plain
 'String' fails badly if you try to take a byte that doesn't fall on a character boundary), but it
 means incurring a dependency on the [utf8-string](https://hackage.haskell.org/package/utf8-string)
 package.

src/Language/Rust/Data/Position.hs

@@ -56,7 +56,7 @@ data Position = Position {
   | NoPosition
   deriving (Eq, Ord, Data, Typeable, Generic, NFData)
 
--- | Field names are shown
+-- | Field names are not shown
 instance Show Position where
   showsPrec _ NoPosition = showString "NoPosition"
   showsPrec p (Position a r c) = showParen (p >= 11) 

src/Language/Rust/Parser.hs

@@ -10,11 +10,18 @@ Portability : GHC
 Selecting the right parser may require adding an annotation or using @-XTypeApplications@ to avoid
 an "Ambiguous type variable" error.
 
-Using 'Control.Monad.void' (as in the examples below) uses the fact that most AST nodes are
+Using 'Control.Monad.void' (as in the examples below) exploits the fact that most AST nodes are
 instances of 'Functor' to discard the 'Span' annotation that is attached to most parsed AST nodes.
 Conversely, if you wish to extract the 'Span' annotation, the 'Language.Rust.Syntax.AST.Located'
 typeclass provides a 'Language.Rust.Syntax.AST.spanOf' method.
 
+The examples below assume the following GHCi flags and imports:
+
+>>> :set -XTypeApplications -XOverloadedStrings
+>>> import Language.Rust.Syntax.AST
+>>> import Control.Monad ( void )
+>>> import System.IO
+
 -}
 {-# LANGUAGE FlexibleInstances #-}
 
@@ -65,11 +72,11 @@ import System.IO                       ( Handle )
 
 -- | Parse something from an input stream (it is assumed the initial position is 'initPos').
 --
--- >>> :set -XOverloadedStrings -XTypeApplications
 -- >>> fmap void $ parse @(Expr Span) "x + 1"
--- Right (Binary [] AddOp (PathExpr [] Nothing (Path False [PathSegment x Nothing ()] ()) ())
---                        (Lit [] (Int Dec 1  ()) ())
+-- Right (Binary [] AddOp (PathExpr [] Nothing (Path False [PathSegment "x" Nothing ()] ()) ())
+--                        (Lit [] (Int Dec 1 Unsuffixed ()) ())
 --                        ())
+--
 -- >>> fmap void $ parse @(Expr Span) "x + "
 -- Left (parse failure at 1:4 (Syntax error: unexpected `<EOF>' (expected an expression)))
 --
@@ -80,12 +87,12 @@ parse is = execParser parser is initPos
 -- intended for situations in which you are already stuck catching exceptions - otherwise you should
 -- prefer 'parse'.
 --
--- >>> :set -XOverloadedStrings -XTypeApplications
--- >>> void $ parse @(Expr Span) "x + 1"
--- Binary [] AddOp (PathExpr [] Nothing (Path False [PathSegment x Nothing ()] ()) ())
---                 (Lit [] (Int Dec 1  ()) ())
+-- >>> void $ parse' @(Expr Span) "x + 1"
+-- Binary [] AddOp (PathExpr [] Nothing (Path False [PathSegment "x" Nothing ()] ()) ())
+--                 (Lit [] (Int Dec 1 Unsuffixed ()) ())
 --                 ()
--- >>> void $ parse @(Expr Span) "x + "
+--
+-- >>> void $ parse' @(Expr Span) "x + "
 -- *** Exception: parse failure at 1:4 (Syntax error: unexpected `<EOF>' (expected an expression))
 --
 parse' :: Parse a => InputStream -> a
@@ -100,7 +107,7 @@ execParserTokens p toks = execParser (pushTokens toks *> p) (inputStreamFromStri
 --
 -- >>> writeFile "empty_main.rs" "fn main() { }"
 -- >>> fmap void $ withFile "empty_main.rs" ReadMode readSourceFile
--- SourceFile Nothing [] [Fn [] InheritedV main
+-- SourceFile Nothing [] [Fn [] InheritedV "main"
 --                           (FnDecl [] Nothing False ())
 --                           Normal NotConst Rust
 --                           (Generics [] [] (WhereClause [] ()) ())

src/Language/Rust/Parser/Internal.y

@@ -704,7 +704,23 @@ ty_param_bound_mod :: { TyParamBound Span }
 -- Sort of like parse_opt_abi() -- currently doesn't handle raw string ABI
 abi :: { Abi }
   : str             {% case unspan $1 of
-                         (LiteralTok (StrTok s) Nothing) -> maybe (parseError $1 {- "invalid ABI" -}) pure (readMaybe s)
+                         LiteralTok (StrTok "cdecl") Nothing ->              pure Cdecl             
+                         LiteralTok (StrTok "stdcall") Nothing ->            pure Stdcall          
+                         LiteralTok (StrTok "fastcall") Nothing ->           pure Fastcall         
+                         LiteralTok (StrTok "vectorcall") Nothing ->         pure Vectorcall       
+                         LiteralTok (StrTok "aapcs") Nothing ->              pure Aapcs            
+                         LiteralTok (StrTok "win64") Nothing ->              pure Win64            
+                         LiteralTok (StrTok "sysv64") Nothing ->             pure SysV64           
+                         LiteralTok (StrTok "ptx-kernel") Nothing ->         pure PtxKernel        
+                         LiteralTok (StrTok "msp430-interrupt") Nothing ->   pure Msp430Interrupt  
+                         LiteralTok (StrTok "x86-interrupt") Nothing ->      pure X86Interrupt     
+                         LiteralTok (StrTok "Rust") Nothing ->               pure Rust             
+                         LiteralTok (StrTok "C") Nothing ->                  pure C                
+                         LiteralTok (StrTok "system") Nothing ->             pure System           
+                         LiteralTok (StrTok "rust-intrinsic") Nothing ->     pure RustIntrinsic    
+                         LiteralTok (StrTok "rust-call") Nothing ->          pure RustCall         
+                         LiteralTok (StrTok "platform-intrinsic") Nothing -> pure PlatformIntrinsic
+                         LiteralTok (StrTok "unadjusted") Nothing ->         pure Unadjusted       
                          _ -> parseError $1 {- "invalid ABI" -}
                     }
   | {- empty -}     { C }
@@ -1728,19 +1744,19 @@ parseTraitItem :: P (TraitItem Span)
 -- | Parser for token trees.
 parseTt :: P TokenTree
 
--- | Parser for token streams
+-- | Parser for token streams.
 parseTokenStream :: P TokenStream
 
--- | Parser for lifetime definitions
+-- | Parser for lifetime definitions.
 parseLifetimeDef :: P (LifetimeDef Span)
 
--- | Parser for a type parameter
+-- | Parser for a type parameter.
 parseTyParam :: P (TyParam Span)
 
--- | Parser for a where clause
+-- | Parser for a where clause.
 parseWhereClause :: P (WhereClause Span)
 
--- | Parser for generics (although 'WhereClause' is always empty here)
+-- | Parser for generics (although 'WhereClause' is always empty here).
 parseGenerics :: P (Generics Span)
 
 -- | Generate a nice looking error message based on expected tokens

src/Language/Rust/Pretty.hs

@@ -37,6 +37,11 @@ advantages over printing plain old strings:
   * /Annotations/: Depending on the backend you are using to render the 'Doc', annotations can
     determine colours, styling, links, etc.
 
+The examples below assume the following GHCi flag and import:
+
+>>> :set -XOverloadedStrings
+>>> import Language.Rust.Syntax.AST
+
 -}
 {-# OPTIONS_GHC -Wall -fno-warn-orphans #-}
 
@@ -87,7 +92,7 @@ import Control.Exception                     ( throw )
 -- >>> pretty (Binary [] MulOp (Binary [] AddOp one two ()) three ())
 -- Right (1 + 2) * 3
 -- >>> pretty (Binary [] AddOp one bogusVar ())
--- Left (invalid AST (identifier is a keyword))
+-- Left (invalid AST (identifier `let' is a keyword))
 -- 
 pretty :: (Resolve a, Pretty a) => a -> Either ResolveFail (Doc b)
 pretty = fmap prettyUnresolved . resolve
@@ -103,7 +108,7 @@ pretty = fmap prettyUnresolved . resolve
 -- >>> pretty' (Binary [] MulOp (Binary [] AddOp one two ()) three ())
 -- (1 + 2) * 3
 -- >>> pretty' (Binary [] AddOp one bogusVar ())
--- *** Exception: invalid AST (identifier is a keyword))
+-- *** Exception: invalid AST (identifier `let' is a keyword))
 --
 pretty' :: (Resolve a, Pretty a) => a -> Doc b
 pretty' = either throw id . pretty
@@ -132,14 +137,14 @@ writeSourceFile hdl = renderIO hdl . PP.layoutPretty layout . prettyAnnotated'
 
 -- | Given a handle to a file, write a 'SourceFile' in with a desired width of 100 characters.
 --
--- The 'Span' associated with the tokens (if present) will be used as a hint to for spacing
--- out the tokens.
+-- The 'Span' associated with the tokens (if present) will be used as a hint for laying out and
+-- spacing the tokens.
 writeTokens :: Handle -> [Spanned Token] -> IO ()
 writeTokens hdl = renderIO hdl . PP.layoutPretty layout . pretty' . Stream . map mkTT
   where layout = PP.LayoutOptions (PP.AvailablePerLine 100 1.0)
         mkTT (Spanned s t) = Tree (Token t s)
 
--- | Describes things that can be pretty printed
+-- | Describes things that can be pretty printed.
 class Pretty a where
   -- | Pretty print the given value without resolving it.
   prettyUnresolved :: a -> Doc b
@@ -149,6 +154,7 @@ instance Pretty BindingMode        where prettyUnresolved = printBindingMode
 instance Pretty BinOp              where prettyUnresolved = printBinOp
 instance Pretty Ident              where prettyUnresolved = printIdent
 instance Pretty ImplPolarity       where prettyUnresolved = printPolarity
+instance Pretty Suffix             where prettyUnresolved = printLitSuffix
 instance Pretty LitTok             where prettyUnresolved = printLitTok
 instance Pretty Mutability         where prettyUnresolved = printMutability
 instance Pretty RangeLimits        where prettyUnresolved = printRangeLimits