Generate command table #531

xsebek · 2022-07-01T21:31:44Z

Generate table for Commands Cheat Sheet Wiki.

part of Create command line tools to automate documentation #344

xsebek · 2022-07-01T21:38:49Z

I just had to make it well-aligned. 😅

| Syntax          | Type                                          | Capability   | Description |
|-----------------|-----------------------------------------------|--------------|-------------|
| `noop`          | `cmd ()`                                      |              |             |
| `wait`          | `int -> cmd ()`                               |              |             |
| `selfdestruct`  | `cmd ()`                                      | selfdestruct |             |
                                      ...

| `case`          | `∀ a b c. a + b -> (a -> c) -> (b -> c) -> c` |              |             |

But I am not sure how to best get the description.
Ideally, I would like to get the haddock comments, so we would not have to duplicate them.

Do you have any tips or suggestions, @byorgey or @TristanCacqueray?

byorgey · 2022-07-01T22:27:56Z

Getting Haddock comments is a good idea, but I don't know off the top of my head how to extract them in a nice way...

byorgey · 2022-07-02T01:03:57Z

Aha, https://hackage.haskell.org/package/haddock-library-1.10.0/docs/Documentation-Haddock-Parser.html looks promising.

xsebek · 2022-07-02T09:13:32Z

Even TH could do it, but only on newer GHC - https://discourse.haskell.org/t/ghc-9-2-1-released/3527.

If there was an easy way with TH/Generics/some package I would use docstrings, but I do not think it is viable <9.2.

Writing documentation for players separately is not so bad and will be simpler Haskell. ✍️

xsebek · 2022-07-02T12:17:44Z

I wrote it manually, could you please take a look @byorgey?

Here is the gist of the resulting markdown table: https://gist.github.com/xsebek/3e8b679f4dad68a7fdf1021abdd95872

xsebek · 2022-07-02T12:30:37Z

Another idea: maybe we could split the table into

builtins (not operator and not isCmd)
commands
operators

And below that have a section per each command/function with a longer description like we have for Entities.

byorgey

Nice! We should somehow make these descriptions available in the Commands (F4) pop-up as well (in another PR).

src/Swarm/Language/Syntax.hs

byorgey · 2022-07-02T12:45:13Z

Another idea: maybe we could split the table into
* builtins (not operator and not `isCmd`)

* commands

* operators
And below that have a section per each command/function with a longer description like we have for Entities.

Sounds good, I have no particular opinions on how the table should be formatted.

noahyor · 2022-07-02T14:05:22Z

I just checked and it seems that all 4 cheat sheets are either unfinished or outdated, so maybe we could automatically generate documentation for all of them.

xsebek · 2022-07-02T17:07:00Z

@noahyor I known, that is the plan 😎

We could even update the wiki in CI, but I do not plan to automate that anytime soon.

noahyor

A few little things.

noahyor · 2022-07-02T14:14:33Z

src/Swarm/Language/Syntax.hs

+      ]
+  Move -> commandLow 0 "Move forward one step."
+  Turn -> commandLow 1 "Turn in some direction."
+  Grab -> commandLow 0 "Grab an item from the current location."


Suggested change

Grab -> commandLow 0 "Grab an item from the current location."

Grab -> commandLow 0 "Grab an item from the current cell."

Actually, I do not think a player will find the "cell" understandable. My understanding is that "cell" is more of a game developer term than gamer slang.

noahyor · 2022-07-02T14:15:46Z

src/Swarm/Language/Syntax.hs

+  Turn -> commandLow 1 "Turn in some direction."
+  Grab -> commandLow 0 "Grab an item from the current location."
+  Harvest ->
+    commandLow 0 . doc "Harvest an item from the current location." $


Suggested change

commandLow 0 . doc "Harvest an item from the current location." $

commandLow 0 . doc "Harvest an item from the current cell." $

noahyor · 2022-07-02T17:12:04Z

src/Swarm/Language/Syntax.hs

+      , "Otherwise it works exactly like 'grab'"
+      ]
+  Place ->
+    commandLow 1 . doc "Place an item at the current location." $


Suggested change

commandLow 1 . doc "Place an item at the current location." $

commandLow 1 . doc "Place an item in the current cell." $

noahyor · 2022-07-02T17:13:50Z

src/Swarm/Language/Syntax.hs

+    commandLow 1 . doc "Place an item at the current location." $
+      ["The current location has to be empty for this to work."]
+  Give -> commandLow 2 "Give an item to another robot closeby."
+  Install -> commandLow 2 "Install a device from inventory on a robot."


Suggested change

Install -> commandLow 2 "Install a device from inventory on a robot."

Install -> commandLow 2 "Install a device from inventory on given robot reference."

I do not think installing stuff on references makes sense.

noahyor · 2022-07-02T17:15:08Z

src/Swarm/Language/Syntax.hs

+    commandLow 2 . doc "Reprogram another robot with new command." $
+      ["The other robot has to be closeby and idle."]
+  Drill ->
+    commandLow 1 . doc "Drill through an entity." $


Suggested change

commandLow 1 . doc "Drill through an entity." $

commandLow 1 . doc "Drill through a drillable entity." $

Well, I am content leaving that discovery to the player. 😄

Anyway, if you wanted to include some specifics, I would suggest doing it in the longer description.

noahyor · 2022-07-02T17:46:06Z

src/Swarm/Language/Syntax.hs

+  Appear ->
+    commandLow 1 . doc "Set how the robot is displayed." $
+      [ "You can either specify one character or five (for each direction)."
+      , "The default is \"X^>v<\"."


Why the 'X' ?

Because the robot is looking down. So it looks like four robots meet.

Anyway, I would like to make that customizable one day, so that powerline font users can choose prettier versions.

I understand, but how would the player ever be able to see that?

You mean build {move; turn down}?

*gape* Wow, I never knew that a robot cold turn downwards!

src/Swarm/Language/Syntax.hs

noahyor · 2022-07-02T17:51:54Z

src/Swarm/Language/Syntax.hs

+  Random ->
+    commandLow 1 . doc "Get a uniformly random integer." $
+      ["The random integer will be from the range 0 to END inclusive of your choice."]
+  Run -> commandLow 1 "Run a program loaded from a file."


Suggested change

Run -> commandLow 1 "Run a program loaded from a file."

Run -> commandLow 1 "Run a program from a file."

I am not too clear on the semantics here, but loading the program from a file sounds like English to me. 🤨

Co-authored-by: Brent Yorgey <[email protected]> Co-authored-by: Noah Yorgey <[email protected]>

xsebek · 2022-07-02T19:14:11Z

Writing documentation for players separately is not so bad and will be simpler Haskell. ✍️

So he said, as he went to write instance IsString ConstDoc... 😆

I think I now get what Emacs referred to as builtins. Instead of having their list hardcoded, I can simply add a few predicates to split consts rougly into functions, operators and commands. Technically operators are also functions, but for documentation purposes we keep them separate.

xsebek · 2022-07-02T21:17:38Z

Behold!

The ultimate command wiki is here!

It has hyperlinks:

Separate sections for functions and operators:

And finally, detailed descriptions, which we can expand in the future:

byorgey · 2022-07-03T04:20:59Z

Looks great!

byorgey · 2022-07-03T04:27:30Z

We should link to the wiki page in the Commands dialog.

TristanCacqueray · 2022-07-03T22:55:04Z

Well done @xsebek!

xsebek · 2022-07-04T08:35:33Z

@byorgey I would prefer to include the info in the game.

It would be nice to have the commands expandable, so when you select it and hit Enter it would show similar info as the wiki. Or we could have a separate view for the currently selected command similar to how we have inventory and info panel.

But for the moment a link must suffice:

This might be my first commit changing the UI! 😆

xsebek · 2022-07-04T08:38:13Z

src/Swarm/TUI/View.hs

-  constSig = case processParsedTerm (noLoc $ TConst c) of
-    Right (ProcessedTerm (TConst _) (Module pt _) _ _) -> " : " <> prettyText pt
-    _ -> "??"
+  constSig = " : " <> prettyText (inferConst c)


@TristanCacqueray Hah, I see you had fun drawing the Const type too! 😀

byorgey · 2022-07-04T11:29:32Z

@xsebek yes, including this info in the game would be great, but this is way better then nothing!

Generate command table

9d20a24

restyled-io bot mentioned this pull request Jul 1, 2022

Restyle Generate command table #532

Merged

Restyled by fourmolu

a98898e

xsebek mentioned this pull request Jul 1, 2022

Create command line tools to automate documentation #344

Closed

7 tasks

Add command description.

47b7884

Escape column separator character

17268b1

byorgey approved these changes Jul 2, 2022

View reviewed changes

noahyor reviewed Jul 2, 2022

View reviewed changes

Fix regrettable mistakes (thanks @byorgey and @noahyor)

125983f

Co-authored-by: Brent Yorgey <[email protected]> Co-authored-by: Noah Yorgey <[email protected]>

xsebek added 3 commits July 2, 2022 23:06

Split table into markdown page

41aa523

Use markdown code escapes in const doc

c6209c1

xsebek marked this pull request as ready for review July 2, 2022 21:12

TristanCacqueray approved these changes Jul 3, 2022

View reviewed changes

xsebek added 2 commits July 4, 2022 10:27

Refactor command drawing code

ea9a852

Add Wiki link to command list

568d550

xsebek commented Jul 4, 2022

View reviewed changes

xsebek added the merge me Trigger the merge process of the Pull request. label Jul 4, 2022

Merge branch 'main' into generate-tables

a5c37e7

mergify bot merged commit f2ad132 into main Jul 4, 2022

mergify bot deleted the generate-tables branch July 4, 2022 08:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Generate command table #531

Generate command table #531

xsebek commented Jul 1, 2022

xsebek commented Jul 1, 2022 •

edited

Loading

byorgey commented Jul 1, 2022

byorgey commented Jul 2, 2022

xsebek commented Jul 2, 2022

xsebek commented Jul 2, 2022

xsebek commented Jul 2, 2022

byorgey left a comment

byorgey commented Jul 2, 2022

noahyor commented Jul 2, 2022

xsebek commented Jul 2, 2022

noahyor left a comment

noahyor Jul 2, 2022

xsebek Jul 2, 2022

noahyor Jul 2, 2022

noahyor Jul 2, 2022

noahyor Jul 2, 2022

xsebek Jul 2, 2022

noahyor Jul 2, 2022

xsebek Jul 2, 2022

noahyor Jul 2, 2022

xsebek Jul 2, 2022

noahyor Jul 3, 2022

xsebek Jul 3, 2022

noahyor Jul 3, 2022

noahyor Jul 2, 2022

xsebek Jul 2, 2022

xsebek commented Jul 2, 2022 •

edited

Loading

xsebek commented Jul 2, 2022 •

edited

Loading

byorgey commented Jul 3, 2022

byorgey commented Jul 3, 2022

TristanCacqueray commented Jul 3, 2022

xsebek commented Jul 4, 2022

xsebek Jul 4, 2022

byorgey commented Jul 4, 2022

	Grab -> commandLow 0 "Grab an item from the current location."
	Grab -> commandLow 0 "Grab an item from the current cell."

	commandLow 0 . doc "Harvest an item from the current location." $
	commandLow 0 . doc "Harvest an item from the current cell." $

	commandLow 1 . doc "Place an item at the current location." $
	commandLow 1 . doc "Place an item in the current cell." $

	Install -> commandLow 2 "Install a device from inventory on a robot."
	Install -> commandLow 2 "Install a device from inventory on given robot reference."

	commandLow 1 . doc "Drill through an entity." $
	commandLow 1 . doc "Drill through a drillable entity." $

	Run -> commandLow 1 "Run a program loaded from a file."
	Run -> commandLow 1 "Run a program from a file."

Generate command table #531

Generate command table #531

Conversation

xsebek commented Jul 1, 2022

xsebek commented Jul 1, 2022 • edited Loading

byorgey commented Jul 1, 2022

byorgey commented Jul 2, 2022

xsebek commented Jul 2, 2022

xsebek commented Jul 2, 2022

xsebek commented Jul 2, 2022

byorgey left a comment

Choose a reason for hiding this comment

byorgey commented Jul 2, 2022

noahyor commented Jul 2, 2022

xsebek commented Jul 2, 2022

noahyor left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xsebek commented Jul 2, 2022 • edited Loading

xsebek commented Jul 2, 2022 • edited Loading

Behold!

byorgey commented Jul 3, 2022

byorgey commented Jul 3, 2022

TristanCacqueray commented Jul 3, 2022

xsebek commented Jul 4, 2022

Choose a reason for hiding this comment

byorgey commented Jul 4, 2022

xsebek commented Jul 1, 2022 •

edited

Loading

xsebek commented Jul 2, 2022 •

edited

Loading

xsebek commented Jul 2, 2022 •

edited

Loading