[Git][ghc/ghc][master] 4 commits: Update exactprint docs
Marge Bot (@marge-bot)
gitlab at gitlab.haskell.org
Thu May 30 07:00:27 UTC 2024
Marge Bot pushed to branch master at Glasgow Haskell Compiler / GHC
Commits:
3c97c74a by Jan Hrček at 2024-05-30T02:58:58-04:00
Update exactprint docs
- - - - -
77760cd7 by Jan Hrček at 2024-05-30T02:58:58-04:00
Incorporate review feedback
- - - - -
87591368 by Jan Hrček at 2024-05-30T02:58:58-04:00
Remove no longer relevant reference to comments
- - - - -
05f4f142 by Jan Hrček at 2024-05-30T02:58:59-04:00
Replace outdated code example
- - - - -
2 changed files:
- compiler/GHC/Parser/Annotation.hs
- compiler/GHC/Types/SrcLoc.hs
Changes:
=====================================
compiler/GHC/Parser/Annotation.hs
=====================================
@@ -485,9 +485,9 @@ instance Outputable AddEpAnn where
-- ---------------------------------------------------------------------
-- | The exact print annotations (EPAs) are kept in the HsSyn AST for
--- the GhcPs phase. We do not always have EPAs though, only for code
--- that has been parsed as they do not exist for generated
--- code. This type captures that they may be missing.
+-- the GhcPs phase. They are usually inserted into the AST by the parser,
+-- and in case of generated code (e.g. by TemplateHaskell) they are usually
+-- initialized using 'NoAnn' type class.
--
-- A goal of the annotations is that an AST can be edited, including
-- moving subtrees from one place to another, duplicating them, and so
@@ -501,19 +501,19 @@ instance Outputable AddEpAnn where
--
-- The 'ann' type parameter allows this general structure to be
-- specialised to the specific set of locations of original exact
--- print annotation elements. So for 'HsLet' we have
+-- print annotation elements. For example
--
--- type instance XLet GhcPs = EpAnn AnnsLet
--- data AnnsLet
--- = AnnsLet {
--- alLet :: EpaLocation,
--- alIn :: EpaLocation
--- } deriving Data
+-- @
+-- type SrcSpannAnnA = EpAnn AnnListItem
+-- @
+--
+-- is a commonly used type alias that specializes the 'ann' type parameter to
+-- 'AnnListItem'.
--
-- The spacing between the items under the scope of a given EpAnn is
-- normally derived from the original 'Anchor'. But if a sub-element
-- is not in its original position, the required spacing can be
--- directly captured in the 'anchor_op' field of the 'entry' Anchor.
+-- captured using an appropriate 'EpaDelta' value for the 'entry' Anchor.
-- This allows us to freely move elements around, and stitch together
-- new AST fragments out of old ones, and have them still printed out
-- in a precise way.
@@ -535,7 +535,7 @@ data EpAnn ann
-- annotations.
-- It is also normally used as the reference point for the spacing of
-- the element relative to its container. If the AST element is moved,
--- that relationship is tracked in the 'anchor_op' instead.
+-- that relationship is tracked using the 'EpaDelta' constructor instead.
type Anchor = EpaLocation -- Transitional
anchor :: (EpaLocation' a) -> RealSrcSpan
@@ -553,7 +553,7 @@ noSpanAnchor = EpaDelta (SameLine 0) noAnn
-- ---------------------------------------------------------------------
--- | When we are parsing we add comments that belong a particular AST
+-- | When we are parsing we add comments that belong to a particular AST
-- element, and print them together with the element, interleaving
-- them into the output stream. But when editing the AST to move
-- fragments around it is useful to be able to first separate the
@@ -602,9 +602,9 @@ Note [XRec and Anno in the AST]
The exact print annotations are captured directly inside the AST, using
TTG extension points. However certain annotations need to be captured
-on the Located versions too. While there is a general form for these,
-captured in the type SrcSpanAnn', there are also specific usages in
-different contexts.
+on the Located versions too. There is a general form for these,
+captured in the type 'EpAnn ann' with the specific usage captured in
+the 'ann' parameter in different contexts.
Some of the particular use cases are
@@ -615,7 +615,7 @@ to its usage inside a list.
See the section above this note for the rest.
-The Anno type family maps the specific SrcSpanAnn' variant for a given
+The Anno type family maps to the specific EpAnn variant for a given
item.
So
@@ -639,7 +639,7 @@ data TrailingAnn
| AddCommaAnn { ta_location :: EpaLocation } -- ^ Trailing ','
| AddVbarAnn { ta_location :: EpaLocation } -- ^ Trailing '|'
| AddDarrowAnn { ta_location :: EpaLocation } -- ^ Trailing '=>'
- | AddDarrowUAnn { ta_location :: EpaLocation } -- ^ Trailing "⇒"
+ | AddDarrowUAnn { ta_location :: EpaLocation } -- ^ Trailing '⇒'
deriving (Data, Eq)
instance Outputable TrailingAnn where
@@ -730,7 +730,7 @@ data NameAnn
nann_close :: EpaLocation,
nann_trailing :: [TrailingAnn]
}
- -- | Used for @(,,,)@, or @(#,,,#)#
+ -- | Used for @(,,,)@, or @(#,,,#)@
| NameAnnCommas {
nann_adornment :: NameAdornment,
nann_open :: EpaLocation,
@@ -769,7 +769,7 @@ data NameAnn
nann_trailing :: [TrailingAnn]
}
-- | Used when adding a 'TrailingAnn' to an existing 'LocatedN'
- -- which has no Api Annotation (via the 'EpAnnNotUsed' constructor.
+ -- which has no Api Annotation.
| NameAnnTrailing {
nann_trailing :: [TrailingAnn]
}
@@ -893,7 +893,7 @@ So for the first example we have
binds: fa = 1 , fb = 'c'
sigs: fa :: Int, fb :: Char
- tags: SigTag, BindTag, SigTag, BindTag
+ tags: SigDTag, BindTag, SigDTag, BindTag
so we draw first from the signatures, then the binds, and same again.
@@ -901,7 +901,7 @@ For the second example we have
binds: fb = 'c', fa = 1
sigs: fa :: Int, fb :: Char
- tags: SigTag, SigTag, BindTag, BindTag
+ tags: SigDTag, SigDTag, BindTag, BindTag
so we draw two signatures, then two binds.
=====================================
compiler/GHC/Types/SrcLoc.hs
=====================================
@@ -908,15 +908,12 @@ mkSrcSpanPs (PsSpan r b) = RealSrcSpan r (Strict.Just b)
-- ---------------------------------------------------------------------
--- | The anchor for an @'AnnKeywordId'@. The Parser inserts the
+-- | The anchor for an exact print annotation. The Parser inserts the
-- @'EpaSpan'@ variant, giving the exact location of the original item
-- in the parsed source. This can be replaced by the @'EpaDelta'@
-- version, to provide a position for the item relative to the end of
-- the previous item in the source. This is useful when editing an
--- AST prior to exact printing the changed one. The list of comments
--- in the @'EpaDelta'@ variant captures any comments between the prior
--- output and the thing being marked here, since we cannot otherwise
--- sort the relative order.
+-- AST prior to exact printing the changed one.
data EpaLocation' a = EpaSpan !SrcSpan
| EpaDelta !DeltaPos !a
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/d040133546a1b2754539e0942987233209c1eced...05f4f1420be27f2852b61f8c348c742961e210d5
--
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/d040133546a1b2754539e0942987233209c1eced...05f4f1420be27f2852b61f8c348c742961e210d5
You're receiving this email because of your account on gitlab.haskell.org.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20240530/bd3ed4fe/attachment-0001.html>
More information about the ghc-commits
mailing list