author ross Thu, 22 Sep 2005 09:43:01 +0000 (09:43 +0000) committer ross Thu, 22 Sep 2005 09:43:01 +0000 (09:43 +0000)
some docs

index 2b983a5..df9642a 100644 (file)
@@ -127,7 +127,7 @@ Relative to John's original paper, there are the following new features:
last line of the top argument stops before the first line of the
second begins.

-        For example:  text "hi" \$\$ nest 5 "there"
+        For example:  text "hi" \$\$ nest 5 (text "there")
lays out as
hi   there
rather than
@@ -172,19 +172,20 @@ module Text.PrettyPrint.HughesPJ (
-- * The document type
Doc,            -- Abstract

-       -- * Primitive Documents
-        empty,
+       -- * Constructing documents
+       -- ** Converting values into documents
+        char, text, ptext,
+        int, integer, float, double, rational,
+
+       -- ** Simple derived documents
semi, comma, colon, space, equals,
lparen, rparen, lbrack, rbrack, lbrace, rbrace,

-       -- * Converting values into documents
-        text, char, ptext,
-        int, integer, float, double, rational,
-
-       -- * Wrapping documents in delimiters
+       -- ** Wrapping documents in delimiters
parens, brackets, braces, quotes, doubleQuotes,

-       -- * Combining documents
+       -- ** Combining documents
+        empty,
(<>), (<+>), hcat, hsep,
(\$\$), (\$+\$), vcat,
sep, cat,
@@ -225,7 +226,11 @@ infixl 5 \$\$, \$+\$

isEmpty :: Doc    -> Bool;  -- ^ Returns 'True' if the document is empty

-empty   :: Doc;                        -- ^ An empty document
+-- | The empty document, with no height and no width.
+-- 'empty' is the identity for '<>', '<+>', '\$\$' and '\$+\$', and anywhere
+-- in the argument list for 'sep', 'hcat', 'hsep', 'vcat', 'fcat' etc.
+empty   :: Doc
+
semi   :: Doc;                 -- ^ A ';' character
comma  :: Doc;                 -- ^ A ',' character
colon  :: Doc;                 -- ^ A ':' character
@@ -238,15 +243,28 @@ rbrack    :: Doc;                 -- ^ A ']' character
lbrace :: Doc;                 -- ^ A '{' character
rbrace :: Doc;                 -- ^ A '}' character

+-- | A document of height and width 1, containing a literal character.
+char    :: Char     -> Doc
+
+-- | A document of height 1 containing a literal string.
+-- 'text' satisfies the following laws:
+--
+-- * @'text' s '<>' 'text' t = 'text' (s'++'t)@
+--
+-- * @'text' \"\" '<>' x = x@, if @x@ non-empty
+--
+-- The side condition on the last law is necessary because @'text' \"\"@
+-- has height 1, while 'empty' has no height.
text    :: String   -> Doc
+
+-- | An obsolete function, now identical to 'text'.
ptext   :: String   -> Doc
-char    :: Char     -> Doc
-int      :: Int      -> Doc
-integer  :: Integer  -> Doc
-float    :: Float    -> Doc
-double   :: Double   -> Doc
-rational :: Rational -> Doc

+int      :: Int      -> Doc;   -- ^ @int n = text (show n)@
+integer  :: Integer  -> Doc;   -- ^ @integer n = text (show n)@
+float    :: Float    -> Doc;   -- ^ @float n = text (show n)@
+double   :: Double   -> Doc;   -- ^ @double n = text (show n)@
+rational :: Rational -> Doc;   -- ^ @rational n = text (show n)@

parens       :: Doc -> Doc;    -- ^ Wrap document in @(...)@
brackets     :: Doc -> Doc;    -- ^ Wrap document in @[...]@
@@ -256,28 +274,74 @@ doubleQuotes :: Doc -> Doc;       -- ^ Wrap document in @\"...\"@

-- Combining @Doc@ values

-(<>)   :: Doc -> Doc -> Doc;     -- ^Beside
-hcat   :: [Doc] -> Doc;          -- ^List version of '<>'
-(<+>)  :: Doc -> Doc -> Doc;     -- ^Beside, separated by space
-hsep   :: [Doc] -> Doc;          -- ^List version of '<+>'
+-- | Beside.
+-- '<>' is associative, with identity 'empty'.
+(<>)   :: Doc -> Doc -> Doc
+
+-- | Beside, separated by space, unless one of the arguments is 'empty'.
+-- '<+>' is associative, with identity 'empty'.
+(<+>)  :: Doc -> Doc -> Doc
+
+-- | Above, except that if the last line of the first argument stops
+-- at least one position before the first line of the second begins,
+-- these two lines are overlapped.  For example:
+--
+-- >    text "hi" \$\$ nest 5 (text "there")
+--
+-- lays out as
+--
+-- >    hi   there
+--
+-- rather than
+--
+-- >    hi
+-- >         there
+--
+-- '\$\$' is associative, with identity 'empty', and also satisfies
+--
+-- * @(x '\$\$' y) '<>' z = x '\$\$' (y '<>' z)@, if @y@ non-empty.
+--
+(\$\$)   :: Doc -> Doc -> Doc

-(\$\$)   :: Doc -> Doc -> Doc;     -- ^Above; if there is no
-                                -- overlap it \"dovetails\" the two
-(\$+\$)   :: Doc -> Doc -> Doc;   -- ^Above, without dovetailing.
-vcat   :: [Doc] -> Doc;          -- ^List version of '\$\$'
+-- | Above, with no overlapping.
+-- '\$+\$' is associative, with identity 'empty'.
+(\$+\$)   :: Doc -> Doc -> Doc

-cat    :: [Doc] -> Doc;          -- ^ Either hcat or vcat
-sep    :: [Doc] -> Doc;          -- ^ Either hsep or vcat
-fcat   :: [Doc] -> Doc;          -- ^ \"Paragraph fill\" version of cat
-fsep   :: [Doc] -> Doc;          -- ^ \"Paragraph fill\" version of sep
+hcat   :: [Doc] -> Doc;          -- ^List version of '<>'.
+hsep   :: [Doc] -> Doc;          -- ^List version of '<+>'.
+vcat   :: [Doc] -> Doc;          -- ^List version of '\$\$'.

-nest   :: Int -> Doc -> Doc;     -- ^ Nested
+cat    :: [Doc] -> Doc;          -- ^ Either 'hcat' or 'vcat'.
+sep    :: [Doc] -> Doc;          -- ^ Either 'hsep' or 'vcat'.
+fcat   :: [Doc] -> Doc;          -- ^ \"Paragraph fill\" version of 'cat'.
+fsep   :: [Doc] -> Doc;          -- ^ \"Paragraph fill\" version of 'sep'.

+-- | Nest (or indent) a document by a given number of positions
+-- (which may also be negative).  'nest' satisfies the laws:
+--
+-- * @'nest' 0 x = x@
+--
+-- * @'nest' k ('nest' k' x) = 'nest' (k+k') x@
+--
+-- * @'nest' k (x '<>' y) = 'nest' k z '<>' 'nest' k y@
+--
+-- * @'nest' k (x '\$\$' y) = 'nest' k x '\$\$' 'nest' k y@
+--
+-- * @'nest' k 'empty' = 'empty'@
+--
+-- * @x '<>' 'nest' k y = x '<>' y@, if @x@ non-empty
+--
+-- The side condition on the last law is needed because
+-- 'empty' is a left identity for '<>'.
+nest   :: Int -> Doc -> Doc

-- GHC-specific ones.

-hang :: Doc -> Int -> Doc -> Doc;      -- ^ @hang d1 n d2 = sep [d1, nest n d2]@
-punctuate :: Doc -> [Doc] -> [Doc];      -- ^ @punctuate p [d1, ... dn] = [d1 \<> p, d2 \<> p, ... dn-1 \<> p, dn]@
+-- | @hang d1 n d2 = sep [d1, nest n d2]@
+hang :: Doc -> Int -> Doc -> Doc
+
+-- | @punctuate p [d1, ... dn] = [d1 \<> p, d2 \<> p, ... dn-1 \<> p, dn]@
+punctuate :: Doc -> [Doc] -> [Doc]

-- Displaying @Doc@ values.
@@ -285,10 +349,10 @@ punctuate :: Doc -> [Doc] -> [Doc];      -- ^ @punctuate p [d1, ... dn] = [d1 \<
instance Show Doc where
showsPrec prec doc cont = showDoc doc cont

--- | Renders the document as a string using the default style
+-- | Renders the document as a string using the default 'style'.
render     :: Doc -> String

--- | The general rendering interface
+-- | The general rendering interface.
fullRender :: Mode                     -- ^Rendering mode
-> Int                       -- ^Line length
-> Float                     -- ^Ribbons per line
@@ -297,21 +361,21 @@ fullRender :: Mode                        -- ^Rendering mode
-> Doc                      -- ^The document
-> a                         -- ^Result

--- | Render the document as a string using a specified style
+-- | Render the document as a string using a specified style.
renderStyle  :: Style -> Doc -> String

--- | A rendering style
+-- | A rendering style.
data Style
= Style { mode           :: Mode     -- ^ The rendering mode
, lineLength     :: Int      -- ^ Length of line, in chars
, ribbonsPerLine :: Float    -- ^ Ratio of ribbon length to line length
}

--- | The default style (@mode=PageMode, lineLength=100, ribbonsPerLine=1.5@)
+-- | The default style (@mode=PageMode, lineLength=100, ribbonsPerLine=1.5@).
style :: Style
style = Style { lineLength = 100, ribbonsPerLine = 1.5, mode = PageMode }

--- | Rendering mode
+-- | Rendering mode.
data Mode = PageMode            -- ^Normal
| ZigZagMode          -- ^With zig-zag cuts
| LeftMode            -- ^No indentation, infinitely long lines
@@ -438,7 +502,8 @@ punctuate p (d:ds) = go d ds
-- A Doc represents a *set* of layouts.  A Doc with
-- no occurrences of Union or NoDoc represents just one layout.

--- | The abstract type of documents
+-- | The abstract type of documents.
+-- The 'Show' instance is equivalent to using 'render'.
data Doc
= Empty                                -- empty
| NilAbove Doc                         -- text "" \$\$ x
@@ -521,7 +586,7 @@ isEmpty Empty = True
isEmpty _     = False

char  c = textBeside_ (Chr c) 1 Empty
-text  s = case length   s of {sl -> textBeside_ (Str s)  sl Empty}
+text  s = case length s of {sl -> textBeside_ (Str s)  sl Empty}
ptext s = case length s of {sl -> textBeside_ (PStr s) sl Empty}

nest k  p = mkNest k (reduceDoc p)        -- Externally callable version
{"ft_lang_label":"__label__en","ft_lang_prob":0.54446936,"math_prob":0.6261772,"size":7182,"snap":"2019-51-2020-05","text_gpt3_token_len":2282,"char_repetition_ratio":0.18124826,"word_repetition_ratio":0.19607843,"special_character_ratio":0.41840714,"punctuation_ratio":0.22979985,"nsfw_num_words":0,"has_unicode_error":false,"math_prob_llama3":0.9591017,"pos_list":[0,1,2,3,4],"im_url_duplicate_count":[null,null,null,null,null],"WARC_HEADER":"{\"WARC-Type\":\"response\",\"WARC-Date\":\"2019-12-06T11:17:12Z\",\"WARC-Record-ID\":\"<urn:uuid:28f25bd4-887e-4567-8f46-db378fb252a3>\",\"Content-Length\":\"39864\",\"Content-Type\":\"application/http; msgtype=response\",\"WARC-Warcinfo-ID\":\"<urn:uuid:eb4b7997-2b23-4dc8-a681-54bfb658f3be>\",\"WARC-Concurrent-To\":\"<urn:uuid:46637e34-bfcf-46ee-bc1d-a2ba2f128834>\",\"WARC-IP-Address\":\"162.242.166.62\",\"WARC-Target-URI\":\"https://git.haskell.org/ghc.git/commitdiff/959189a25261be648db1949ea94849226f59c2b8\",\"WARC-Payload-Digest\":\"sha1:DVVFS4H2YAPDAAYSDGMA24WQXCHH536L\",\"WARC-Block-Digest\":\"sha1:AVHJ5HMAXMXLWBWH2FKIER3YFVAQWETW\",\"WARC-Identified-Payload-Type\":\"application/xhtml+xml\",\"warc_filename\":\"/cc_download/warc_2019/CC-MAIN-2019-51/CC-MAIN-2019-51_segments_1575540487789.39_warc_CC-MAIN-20191206095914-20191206123914-00388.warc.gz\"}"}