Allow customization of help info via introducing semantic Doc #482

Martinsos · 2023-06-10T12:07:26Z

Should fix #478 once it is done.

@HuwCampbell this is still more of a playground then a solution, and it doesn't even compile completely, but I think it is starting to take some initial shape, so I thought I would rather share while still in this early stage, so you can course-correct me if I am going in a very wrong direction.

I mostly asked questions in the code, in comments, about things that are not clear to me.

The approach is that I introduced a new type of Doc annotation, HelpAnn, which still allows for "old" AnsiStyle annotations (to support future feature of users specifying style via modifiers, and also the current feature of custom AnsiStyle docs they can already provide for some parts of docs like header, footer and similar), but also allows for HelpType annotations, which we use internally to annotate parts.

type HelpDoc = PP.Doc HelpAnn

data HelpAnn = HelpAnnType HelpType | HelpAnnStyle AnsiStyle

data HelpType = CmdName | OptionName | Description | Title | Metavar

The idea is then to later, probably at SimpleDocStream stage (in prettyprinter docs they recommend doing it at this stage), reannotate HelpAnn annotations into AnsiStyle annotations and continue from there same as before.

I haven't yet started at all working on modifiers that would allow users to specify custom style. For now, I just focused on replacing one kind of annotation with another kind of annotation. I mostly got stuck on figuring out where to exactly annotate what with our new semantic annotation (HelpAnn, specifically HelpAnnType), because I am having hard time figuring out which Chunk Doc is presenting what from the code -> is it option name, description, metavar, ... .

Once we have internal semantic annotation working, and a default way defined of converting those annotations (HelpAnn) into ansi annotations (AnsiStyle) (probably we will just do nothing for most of them), we can start looking into allowing users to define their own function that transforms HelpAnn into AnsiStyle as one way of (global) customization, and style modifiers as another way of (local) customization.

Interested to hear what you think, does this direction make sense? Thanks!

HuwCampbell · 2023-06-11T00:11:38Z

Hi.

Yes that's pretty much what I was suggesting. Please don't reformat everything in a PR though. It's too hard to tell what the point is.

Martinsos · 2023-06-11T15:13:52Z

Hi.

Yes that's pretty much what I was suggesting. Please don't reformat everything in a PR though. It's too hard to tell what the point is.

Ah sorry I didn't realize I was doing reformatting! That was ormolu doing it on its own. I will have to turn it off and then re-do the changes.
In the meantime, do you have any pointers? You said direction seems to be ok, that is great -> what about good places to annotate stuff? I annotated on about two places, but I am not sure about some other places where I should do it. It would help if you could comment on the TODOs that I left in the code.

Martinsos · 2023-06-11T15:14:51Z

src/Options/Applicative/Help/Core.hs

+              [ ( annotateHelp CmdName $ pretty cmdName,
+                  align (annotateHelp Description $ ansiDocToHelpDoc $ extractChunk (infoProgDesc cmdInfo))


I did some annotating here.

Martinsos · 2023-06-11T15:15:14Z

src/Options/Applicative/Help/Core.hs


+    with_title :: String -> Chunk HelpDoc -> Chunk HelpDoc
+    with_title title = fmap (annotateHelp Title . (pretty title .$.))


I did a bit of annotating here.

yet.

Martinsos · 2023-06-11T21:10:21Z

src/Options/Applicative/Help/Core.hs

+        annotateHelp Metavar <$> stringChunk (optMetaVar opt)
      descs =
-        map (pretty . showOption) names
+        map (annotateHelp OptionName . pretty . showOption) names


I did some annotating here.

Martinsos · 2023-06-11T21:10:32Z

src/Options/Applicative/Help/Core.hs

+              [ (annotateHelp CmdName $ pretty cmdName,
+                 align (annotateHelp Description $ ansiDocToHelpDoc $ extractChunk (infoProgDesc cmdInfo))
+                )
+              | (cmdName, cmdInfo) <- reverse cmds


Some more annotating here.

Martinsos · 2023-06-11T21:12:26Z

src/Options/Applicative/Types.hs

+  , infoProgDesc :: Chunk AnsiDoc -- ^ brief parser description
+  , infoHeader :: Chunk AnsiDoc   -- ^ header of the full parser description
+  , infoFooter :: Chunk AnsiDoc   -- ^ footer of the full parser description


This is still AnsiDoc, so that existing interface or these definitions doesn't change and so that users can continue using ansi styles while defining these.
Does that make sense?

Martinsos · 2023-06-11T21:36:48Z

src/Options/Applicative/Types.hs

+  , propHelp :: Chunk HelpDoc                 -- ^ help text for this option
  , propMetaVar :: String                 -- ^ metavariable for this option
  , propShowDefault :: Maybe String       -- ^ what to show in the help text as the default
  , propShowGlobal :: Bool                -- ^ whether the option is presented in global options text
-  , propDescMod :: Maybe ( Doc -> Doc )   -- ^ a function to run over the brief description
+  , propDescMod :: Maybe ( HelpDoc -> HelpDoc )   -- ^ a function to run over the brief description


I am not quite sure if these should operate on HelpDoc or AnsiDoc?

Martinsos · 2023-06-11T21:38:24Z

@HuwCampbell I reverted the formatting changes, so now it should be ready for a closer look!

HuwCampbell · 2023-06-15T07:46:16Z

src/Options/Applicative/Help/Chunk.hs

+--   really a "doc chunk"? But isn't Doc already a "chunk of doc"?.
+
+-- TODO: We have two types of functions here: general (Chunk a) operations, and Chunk (Doc a) operations. We should probably split those into separate modules.
+


It's so we can get a different monoid instance and not add spaces or breaks when things are hidden.

You'll find if its removed that internal and hidden options will affect the way the parser is rendered.

HuwCampbell · 2023-06-22T23:25:41Z

I spent 10 minutes on the train and got it to this:

HuwCampbell · 2023-06-23T11:12:35Z

All up your approach it good. Do you mind if I push some commits to your branch?

Martinsos · 2023-06-24T10:11:53Z

That's looking great! @HuwCampbell sure pls go for it -> I am currently slammed with other work, but might be able to dedicate some more time in a couple of weeks. But if you can make progress / get it done in the meantime, none happier than me!

Btw this is what we currently have in our CLI, and what we would like to also achieve with optparse applicative:

So I am really hoping to achieve level of customizability that can bring us close to that.

This is what we achieved with optparse so far:

HuwCampbell · 2023-06-27T10:22:25Z

Will do. We're still a way to go though.

The issue isn't actually providing colours per se, that's relatively easy. I also want to respect if it's a TTY; environment variables like NOCOLOR; and a --no-color flag – while also giving a good programming API.

I general, if it's not a TTY, one shouldn't print colours; same for the other two ways of suppressing them. This gets a bit tricky for us because at the moment we don't have an environment parser to lean on internally.

Martinsos · 2023-07-21T12:34:40Z

Will do. We're still a way to go though.

The issue isn't actually providing colours per se, that's relatively easy. I also want to respect if it's a TTY; environment variables like NOCOLOR; and a --no-color flag – while also giving a good programming API.

I general, if it's not a TTY, one shouldn't print colours; same for the other two ways of suppressing them. This gets a bit tricky for us because at the moment we don't have an environment parser to lean on internally.

Ah interesting, I completely forgot about that. So we are really talking about the support for the ansi escape codes? And you are saying we don't have any logic for checking that at the moment + for propagating it to the right places?

Martinsos mentioned this pull request Jun 10, 2023

Make all wasp cli commands to use optparse-applicative wasp-lang/wasp#1202

Closed

43 tasks

Martinsos commented Jun 11, 2023

View reviewed changes

Initial work on replacing Doc with HelpDoc and AnsiDoc. Not compiling

5efa15f

yet.

Martinsos force-pushed the semantic-doc branch from 5f79978 to 5efa15f Compare June 11, 2023 21:09

Martinsos commented Jun 11, 2023

View reviewed changes

Martinsos added 2 commits June 11, 2023 23:24

Some compiler fixes.

b25bde5

fix

f5e7f72

Martinsos commented Jun 11, 2023

View reviewed changes

HuwCampbell reviewed Jun 15, 2023

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Allow customization of help info via introducing semantic Doc #482

Allow customization of help info via introducing semantic Doc #482

Martinsos commented Jun 10, 2023 •

edited

HuwCampbell commented Jun 11, 2023

Martinsos commented Jun 11, 2023

Martinsos Jun 11, 2023

Martinsos Jun 11, 2023

Martinsos Jun 11, 2023

Martinsos Jun 11, 2023

Martinsos Jun 11, 2023 •

edited

Martinsos Jun 11, 2023

Martinsos commented Jun 11, 2023

HuwCampbell Jun 15, 2023

HuwCampbell commented Jun 22, 2023

HuwCampbell commented Jun 23, 2023

Martinsos commented Jun 24, 2023 •

edited

HuwCampbell commented Jun 27, 2023

Martinsos commented Jul 21, 2023

		[ ( annotateHelp CmdName $ pretty cmdName,
		align (annotateHelp Description $ ansiDocToHelpDoc $ extractChunk (infoProgDesc cmdInfo))


		with_title :: String -> Chunk HelpDoc -> Chunk HelpDoc
		with_title title = fmap (annotateHelp Title . (pretty title .$.))

		-- really a "doc chunk"? But isn't Doc already a "chunk of doc"?.

		-- TODO: We have two types of functions here: general (Chunk a) operations, and Chunk (Doc a) operations. We should probably split those into separate modules.

Allow customization of help info via introducing semantic Doc #482

Are you sure you want to change the base?

Allow customization of help info via introducing semantic Doc #482

Conversation

Martinsos commented Jun 10, 2023 • edited

HuwCampbell commented Jun 11, 2023

Martinsos commented Jun 11, 2023

Martinsos Jun 11, 2023

Choose a reason for hiding this comment

Martinsos Jun 11, 2023

Choose a reason for hiding this comment

Martinsos Jun 11, 2023

Choose a reason for hiding this comment

Martinsos Jun 11, 2023

Choose a reason for hiding this comment

Martinsos Jun 11, 2023 • edited

Choose a reason for hiding this comment

Martinsos Jun 11, 2023

Choose a reason for hiding this comment

Martinsos commented Jun 11, 2023

HuwCampbell Jun 15, 2023

Choose a reason for hiding this comment

HuwCampbell commented Jun 22, 2023

HuwCampbell commented Jun 23, 2023

Martinsos commented Jun 24, 2023 • edited

HuwCampbell commented Jun 27, 2023

Martinsos commented Jul 21, 2023

Martinsos commented Jun 10, 2023 •

edited

Martinsos Jun 11, 2023 •

edited

Martinsos commented Jun 24, 2023 •

edited