From 38a73da600d797aec4dd5542f3bd67d29a8cf668 Mon Sep 17 00:00:00 2001 From: Arya Irani Date: Fri, 5 Jul 2024 11:33:11 -0400 Subject: [PATCH] switch `Left` to `Right` on help outputs; add draft transcripts --- .../src/Unison/CommandLine/InputPatterns.hs | 12 +- .../transcripts-manual/docs.to-html.output.md | 2 +- unison-src/transcripts/help.md | 14 + unison-src/transcripts/help.output.md | 963 ++++++++++++++++++ unison-src/transcripts/input-parse-errors.md | 173 ++++ .../transcripts/input-parse-errors.output.md | 202 ++++ unison-src/transcripts/merge.output.md | 30 +- unison-src/transcripts/pull-errors.output.md | 16 +- 8 files changed, 1384 insertions(+), 28 deletions(-) create mode 100644 unison-src/transcripts/help.md create mode 100644 unison-src/transcripts/help.output.md create mode 100644 unison-src/transcripts/input-parse-errors.md create mode 100644 unison-src/transcripts/input-parse-errors.output.md diff --git a/unison-cli/src/Unison/CommandLine/InputPatterns.hs b/unison-cli/src/Unison/CommandLine/InputPatterns.hs index 0e86f15c8c..da684d80c9 100644 --- a/unison-cli/src/Unison/CommandLine/InputPatterns.hs +++ b/unison-cli/src/Unison/CommandLine/InputPatterns.hs @@ -2312,12 +2312,12 @@ helpTopics = [("topic", Optional, topicNameArg)] ("`help-topics` lists all topics and `help-topics ` shows an explanation of that topic.") ( \case - [] -> Left topics + [] -> Right $ Input.CreateMessage topics [topic] -> do topic <- unsupportedStructuredArgument "help-topics" "a help topic" topic case Map.lookup topic helpTopicsMap of Nothing -> Left . warn $ "I don't know of that topic. Try `help-topics`." - Just t -> Left t + Just t -> Right $ Input.CreateMessage t _ -> Left $ warn "Use `help-topics ` or `help-topics`." ) where @@ -2497,7 +2497,7 @@ help = "`help` shows general help and `help ` shows help for one command." $ \case [] -> - Left $ + Right . Input.CreateMessage $ intercalateMap "\n\n" showPatternHelp @@ -2505,13 +2505,13 @@ help = [cmd] -> do cmd <- unsupportedStructuredArgument "help" "a command" cmd case (Map.lookup cmd commandsByName, isHelp cmd) of - (Nothing, Just msg) -> Left msg + (Nothing, Just msg) -> Right $ Input.CreateMessage msg (Nothing, Nothing) -> Left . warn $ "I don't know of that command. Try `help`." - (Just pat, Nothing) -> Left $ showPatternHelp pat + (Just pat, Nothing) -> Right . Input.CreateMessage $ showPatternHelp pat -- If we have a command and a help topic with the same name (like "projects"), then append a tip to the -- command's help that suggests running `help-topic command` (Just pat, Just _) -> - Left $ + Right . Input.CreateMessage $ showPatternHelp pat <> P.newline <> P.newline diff --git a/unison-src/transcripts-manual/docs.to-html.output.md b/unison-src/transcripts-manual/docs.to-html.output.md index bdfc5fa4a6..fbd51a4eaf 100644 --- a/unison-src/transcripts-manual/docs.to-html.output.md +++ b/unison-src/transcripts-manual/docs.to-html.output.md @@ -6,7 +6,7 @@ I'll now fetch the latest version of the base Unison library... - Downloaded 14053 entities. + Downloaded 12886 entities. 🎨 Type `ui` to explore this project's code in your browser. 🔭 Discover libraries at https://share.unison-lang.org diff --git a/unison-src/transcripts/help.md b/unison-src/transcripts/help.md new file mode 100644 index 0000000000..7a2ffa2906 --- /dev/null +++ b/unison-src/transcripts/help.md @@ -0,0 +1,14 @@ +# Shows `help` output + +```ucm:error +scratch/main> help +scratch/main> help-topics +scratch/main> help-topic filestatus +scratch/main> help-topic messages.disallowedAbsolute +scratch/main> help-topic namespaces +scratch/main> help-topic projects +scratch/main> help-topic remotes +scratch/main> help-topic testcache +``` + +We should add a command to show help for hidden commands also. diff --git a/unison-src/transcripts/help.output.md b/unison-src/transcripts/help.output.md new file mode 100644 index 0000000000..2044217df0 --- /dev/null +++ b/unison-src/transcripts/help.output.md @@ -0,0 +1,963 @@ +# Shows `help` output + +```ucm +scratch/main> help + + add + `add` adds to the codebase all the definitions from the most recently typechecked file. + + add.preview + `add.preview` previews additions to the codebase from the most recently typechecked file. This command only displays cached typechecking results. Use `load` to reparse & typecheck the file if the context has changed. + + add.run + `add.run name` adds to the codebase the result of the most recent `run` command as `name`. + + alias.many (or copy) + `alias.many [relative2...] ` creates + aliases `relative1`, `relative2`, ... in the namespace + `namespace`. + `alias.many foo.foo bar.bar .quux` creates aliases + `.quux.foo.foo` and `.quux.bar.bar`. + + alias.term + `alias.term foo bar` introduces `bar` with the same definition as `foo`. + + alias.type + `alias.type Foo Bar` introduces `Bar` with the same definition as `Foo`. + + api + `api` provides details about the API. + + auth.login + Obtain an authentication session with Unison Share. + `auth.login`authenticates ucm with Unison Share. + + back (or popd) + `back` undoes the last `switch` command. + + branch (or branch.create, create.branch) + `branch foo` forks the current project branch to a new + branch `foo` + `branch /bar foo` forks the branch `bar` of the current + project to a new branch `foo` + `branch .bar foo` forks the path `.bar` of the current + project to a new branch `foo` + + branch.empty (or branch.create-empty, create.empty-branch) + Create a new empty branch. + + branch.rename (or rename.branch) + `branch.rename foo` renames the current branch to `foo` + + branches (or list.branch, ls.branch, branch.list) + `branches` lists all branches in the current project + `branches foo` lists all branches in the project `foo` + + clear + `clear` Clears the screen. + + clone + `clone @unison/json/topic json/my-topic` creates + `json/my-topic` from + the remote branch + `@unison/json/topic` + `clone @unison/base base/` creates `base/main` + from the remote + branch + `@unison/base/main` + `clone @unison/base /main2` creates the branch + `main2` in the + current project from + the remote branch + `@unison/base/main` + `clone /main /main2` creates the branch + `main2` in the + current project from + the remote branch + `main` of the + current project's + associated remote + (see + `help-topics remotes`) + `clone /main my-fork/` creates + `my-fork/main` from + the branch `main` of + the current + project's associated + remote (see + `help-topics remotes`) + + compile (or compile.output) + `compile main file` Outputs a stand alone file that can be + directly loaded and executed by unison. + Said execution will have the effect of + running `!main`. + + create.author + `create.author alicecoder "Alice McGee"` creates `alicecoder` + values in `metadata.authors` and `metadata.copyrightHolders.` + + debug.clear-cache + Clear the watch expression cache + + debug.doc-to-markdown + `debug.doc-to-markdown term.doc` Render a doc to markdown. + + debug.doctor + Analyze your codebase for errors and inconsistencies. + + debug.dump-namespace + Dump the namespace to a text file + + debug.dump-namespace-simple + Dump the namespace to a text file + + debug.file + View details about the most recent successfully typechecked file. + + debug.numberedArgs + Dump the contents of the numbered args state. + + delete + `delete foo` removes the term or type name `foo` from the namespace. + `delete foo bar` removes the term or type name `foo` and `bar` from the namespace. + + delete.branch (or branch.delete) + `delete.branch foo/bar` deletes the branch `bar` in the + project `foo` + `delete.branch /bar` deletes the branch `bar` in the + current project + + delete.namespace + `delete.namespace ` deletes the namespace `foo` + + delete.namespace.force + `delete.namespace.force ` deletes the namespace `foo`,deletion will proceed even if other code depends on definitions in foo. + + delete.project (or project.delete) + `delete.project foo` deletes the local project `foo` + + delete.term + `delete.term foo` removes the term name `foo` from the namespace. + `delete.term foo bar` removes the term name `foo` and `bar` from the namespace. + + delete.term.verbose + `delete.term.verbose foo` removes the term name `foo` from the namespace. + `delete.term.verbose foo bar` removes the term name `foo` and `bar` from the namespace. + + delete.type + `delete.type foo` removes the type name `foo` from the namespace. + `delete.type foo bar` removes the type name `foo` and `bar` from the namespace. + + delete.type.verbose + `delete.type.verbose foo` removes the type name `foo` from the namespace. + `delete.type.verbose foo bar` removes the type name `foo` and `bar` from the namespace. + + delete.verbose + `delete.verbose foo` removes the term or type name `foo` from the namespace. + `delete.verbose foo bar` removes the term or type name `foo` and `bar` from the namespace. + + dependencies + List the dependencies of the specified definition. + + dependents + List the named dependents of the specified definition. + + deprecated.cd (or deprecated.namespace) + Moves your perspective to a different namespace. Deprecated for now because too many important things depend on your perspective selection. + + `deprecated.cd foo.bar` descends into foo.bar from the + current namespace. + `deprecated.cd .cat.dog` sets the current namespace to the + absolute namespace .cat.dog. + `deprecated.cd ..` moves to the parent of the current + namespace. E.g. moves from + '.cat.dog' to '.cat' + `deprecated.cd` invokes a search to select which + namespace to move to, which requires + that `fzf` can be found within your + PATH. + + diff.namespace + `diff.namespace before after` shows how the namespace `after` + differs from the namespace + `before` + `diff.namespace before` shows how the current namespace + differs from the namespace + `before` + + display + `display foo` prints a rendered version of the term `foo`. + `display` without arguments invokes a search to select a definition to display, which requires that `fzf` can be found within your PATH. + + display.to + `display.to foo` prints a rendered version of the + term `foo` to the given file. + + docs + `docs foo` shows documentation for the definition `foo`. + `docs` without arguments invokes a search to select which definition to view documentation for, which requires that `fzf` can be found within your PATH. + + docs.to-html + `docs.to-html .path.to.ns doc-dir` Render + all docs + contained + within + the + namespace + `.path.to.ns`, + no matter + how deep, + to html + files in + `doc-dir` + in the + directory + UCM was + run from. + `docs.to-html project0/branch0:a.path /tmp/doc-dir` Renders + all docs + anywhere + in the + namespace + `a.path` + from + `branch0` + of + `project0` + to html + in + `/tmp/doc-dir`. + + edit + `edit foo` prepends the definition of `foo` to the top of the most recently saved file. + `edit` without arguments invokes a search to select a definition for editing, which requires that `fzf` can be found within your PATH. + + edit.namespace + `edit.namespace` will load all terms and types contained within the current namespace into your scratch file. This includes definitions in namespaces, but excludes libraries. + `edit.namespace ns1 ns2 ...` loads the terms and types contained within the provided namespaces. + + find + `find` lists all definitions in the + current namespace. + `find foo` lists all definitions with a + name similar to 'foo' in the + current namespace (excluding + those under 'lib'). + `find foo bar` lists all definitions with a + name similar to 'foo' or + 'bar' in the current + namespace (excluding those + under 'lib'). + `find-in namespace` lists all definitions in the + specified subnamespace. + `find-in namespace foo bar` lists all definitions with a + name similar to 'foo' or + 'bar' in the specified + subnamespace. + find.all foo lists all definitions with a + name similar to 'foo' in the + current namespace (including + one level of 'lib'). + `find-in.all namespace` lists all definitions in the + specified subnamespace + (including one level of its + 'lib'). + `find-in.all namespace foo bar` lists all definitions with a + name similar to 'foo' or + 'bar' in the specified + subnamespace (including one + level of its 'lib'). + find.global foo lists all definitions with a + name similar to 'foo' in any + namespace + + find-in + `find` lists all definitions in the + current namespace. + `find foo` lists all definitions with a + name similar to 'foo' in the + current namespace (excluding + those under 'lib'). + `find foo bar` lists all definitions with a + name similar to 'foo' or + 'bar' in the current + namespace (excluding those + under 'lib'). + `find-in namespace` lists all definitions in the + specified subnamespace. + `find-in namespace foo bar` lists all definitions with a + name similar to 'foo' or + 'bar' in the specified + subnamespace. + find.all foo lists all definitions with a + name similar to 'foo' in the + current namespace (including + one level of 'lib'). + `find-in.all namespace` lists all definitions in the + specified subnamespace + (including one level of its + 'lib'). + `find-in.all namespace foo bar` lists all definitions with a + name similar to 'foo' or + 'bar' in the specified + subnamespace (including one + level of its 'lib'). + find.global foo lists all definitions with a + name similar to 'foo' in any + namespace + + find-in.all + `find` lists all definitions in the + current namespace. + `find foo` lists all definitions with a + name similar to 'foo' in the + current namespace (excluding + those under 'lib'). + `find foo bar` lists all definitions with a + name similar to 'foo' or + 'bar' in the current + namespace (excluding those + under 'lib'). + `find-in namespace` lists all definitions in the + specified subnamespace. + `find-in namespace foo bar` lists all definitions with a + name similar to 'foo' or + 'bar' in the specified + subnamespace. + find.all foo lists all definitions with a + name similar to 'foo' in the + current namespace (including + one level of 'lib'). + `find-in.all namespace` lists all definitions in the + specified subnamespace + (including one level of its + 'lib'). + `find-in.all namespace foo bar` lists all definitions with a + name similar to 'foo' or + 'bar' in the specified + subnamespace (including one + level of its 'lib'). + find.global foo lists all definitions with a + name similar to 'foo' in any + namespace + + find.all + `find` lists all definitions in the + current namespace. + `find foo` lists all definitions with a + name similar to 'foo' in the + current namespace (excluding + those under 'lib'). + `find foo bar` lists all definitions with a + name similar to 'foo' or + 'bar' in the current + namespace (excluding those + under 'lib'). + `find-in namespace` lists all definitions in the + specified subnamespace. + `find-in namespace foo bar` lists all definitions with a + name similar to 'foo' or + 'bar' in the specified + subnamespace. + find.all foo lists all definitions with a + name similar to 'foo' in the + current namespace (including + one level of 'lib'). + `find-in.all namespace` lists all definitions in the + specified subnamespace + (including one level of its + 'lib'). + `find-in.all namespace foo bar` lists all definitions with a + name similar to 'foo' or + 'bar' in the specified + subnamespace (including one + level of its 'lib'). + find.global foo lists all definitions with a + name similar to 'foo' in any + namespace + + find.all.verbose + `find.all.verbose` searches for definitions like `find.all`, but includes hashes and aliases in the results. + + find.global + `find` lists all definitions in the + current namespace. + `find foo` lists all definitions with a + name similar to 'foo' in the + current namespace (excluding + those under 'lib'). + `find foo bar` lists all definitions with a + name similar to 'foo' or + 'bar' in the current + namespace (excluding those + under 'lib'). + `find-in namespace` lists all definitions in the + specified subnamespace. + `find-in namespace foo bar` lists all definitions with a + name similar to 'foo' or + 'bar' in the specified + subnamespace. + find.all foo lists all definitions with a + name similar to 'foo' in the + current namespace (including + one level of 'lib'). + `find-in.all namespace` lists all definitions in the + specified subnamespace + (including one level of its + 'lib'). + `find-in.all namespace foo bar` lists all definitions with a + name similar to 'foo' or + 'bar' in the specified + subnamespace (including one + level of its 'lib'). + find.global foo lists all definitions with a + name similar to 'foo' in any + namespace + + find.verbose + `find.verbose` searches for definitions like `find`, but includes hashes and aliases in the results. + + fork (or copy.namespace) + `fork src dest` creates + the + namespace + `dest` as + a copy of + `src`. + `fork project0/branch0:a.path project1/branch1:foo` creates + the + namespace + `foo` in + `branch1` + of + `project1` + as a copy + of + `a.path` + in + `project0/branch0`. + `fork srcproject/srcbranch dest` creates + the + namespace + `dest` as + a copy of + the + branch + `srcbranch` + of + `srcproject`. + + help (or ?) + `help` shows general help and `help ` shows help for one command. + + help-topics (or help-topic) + `help-topics` lists all topics and `help-topics ` shows an explanation of that topic. + + history + `history` Shows the history of the current + path. + `history .foo` Shows history of the path .foo. + `history #9dndk3kbsk13nbpeu` Shows the history of the + namespace with the given hash. + The full hash must be provided. + + io.test (or test.io) + `io.test mytest` Runs `!mytest`, where `mytest` is a delayed + test that can use the `IO` and `Exception` + abilities. + + io.test.all (or test.io.all) + `io.test.all` runs unit tests for the current branch that use + IO + + lib.install (or install.lib) + The `lib.install` command installs a dependency into the `lib` + namespace. + + `lib.install @unison/base/releases/latest` installs the + latest release of + `@unison/base` + `lib.install @unison/base/releases/3.0.0` installs version + 3.0.0 of + `@unison/base` + `lib.install @unison/base/topic` installs the + `topic` branch of + `@unison/base` + + list (or ls, dir) + `list` lists definitions and namespaces at the current + level of the current namespace. + `list foo` lists the 'foo' namespace. + `list .foo` lists the '.foo' namespace. + + load + `load` parses, typechecks, and evaluates the + most recent scratch file. + `load ` parses, typechecks, and evaluates the + given scratch file. + + merge + `merge /branch` merges `branch` into the current branch + + merge.commit (or commit.merge) + `merge.commit` merges a temporary branch created by the + `merge` command back into its parent branch, and removes the + temporary branch. + + For example, if you've done `merge topic` from main, then + `merge.commit` is equivalent to doing + + * switch /main + * merge /merge-topic-into-main + * delete.branch /merge-topic-into-main + + move (or rename) + `move foo bar` renames the term, type, and namespace foo to bar. + + move.namespace (or rename.namespace) + `move.namespace foo bar` renames the path `foo` to `bar`. + + move.term (or rename.term) + `move.term foo bar` renames `foo` to `bar`. + + move.type (or rename.type) + `move.type foo bar` renames `foo` to `bar`. + + names + `names foo` shows the hash and all known names for `foo`. + + names.global + `names.global foo` shows the hash and all known names for + `foo`. + + namespace.dependencies + List the external dependencies of the specified namespace. + + project.create (or create.project) + `project.create` creates a project with a random name + `project.create foo` creates a project named `foo` + + project.rename (or rename.project) + `project.rename foo` renames the current project to `foo` + + projects (or list.project, ls.project, project.list) + List projects. + + pull + The `pull` command merges a remote namespace into a local + branch + + `pull @unison/base/main` merges the branch + `main` of the Unison + Share hosted project + `@unison/base` into + the current branch + `pull @unison/base/main my-base/topic` merges the branch + `main` of the Unison + Share hosted project + `@unison/base` into + the branch `topic` of + the local `my-base` + project + + where `remote` is a project or project branch, such as: + Project (defaults to the /main branch) `@unison/base` + Project Branch `@unison/base/feature` + Contributor Branch `@unison/base/@johnsmith/feature` + Project Release `@unison/base/releases/1.0.0` + + pull.without-history + The `pull.without-history` command merges a remote namespace + into a local branch without including the remote's history. + This usually results in smaller codebase sizes. + + `pull.without-history @unison/base/main` merges + the + branch + `main` + of the + Unison + Share + hosted + project + `@unison/base` + into + the + current + branch + `pull.without-history @unison/base/main my-base/topic` merges + the + branch + `main` + of the + Unison + Share + hosted + project + `@unison/base` + into + the + branch + `topic` + of the + local + `my-base` + project + + where `remote` is a project or project branch, such as: + Project (defaults to the /main branch) `@unison/base` + Project Branch `@unison/base/feature` + Contributor Branch `@unison/base/@johnsmith/feature` + Project Release `@unison/base/releases/1.0.0` + + push + The `push` command merges a local project or namespace into a + remote project or namespace. + + `push ` publishes the contents of a local + namespace or branch into a remote + namespace or branch. + `push ` publishes the current namespace or + branch into a remote namespace or + branch + `push` publishes the current namespace or + branch. Remote mappings for + namespaces are configured in your + `.unisonConfig` at the key + `RemoteMappings.` where + `` is the current + namespace. Remote mappings for + branches default to the branch that + you cloned from or pushed to + initially. Otherwise, it is pushed to + @/ + + where `remote` is a project or project branch, such as: + Project (defaults to the /main branch) `@unison/base` + Project Branch `@unison/base/feature` + Contributor Branch `@unison/base/@johnsmith/feature` + + push.create + The `push.create` command pushes a local namespace to an empty + remote namespace. + + `push.create remote local` pushes the contents of the local + namespace `local` into the empty + remote namespace `remote`. + `push.create remote` publishes the current namespace + into the empty remote namespace + `remote` + `push.create` publishes the current namespace + into the remote namespace + configured in your `.unisonConfig` + at the key + `RemoteMappings.` where + `` is the current + namespace, then publishes the + current namespace to that + location. + + where `remote` is a project or project branch, such as: + Project (defaults to the /main branch) `@unison/base` + Project Branch `@unison/base/feature` + Contributor Branch `@unison/base/@johnsmith/feature` + + quit (or exit, :q) + Exits the Unison command line interface. + + reflog + `reflog` lists the changes that have affected the root namespace + + release.draft (or draft.release) + Draft a release. + + reset + `reset #pvfd222s8n` reset the current namespace to the + causal `#pvfd222s8n` + `reset foo` reset the current namespace to + that of the `foo` namespace. + `reset foo bar` reset the namespace `bar` to that + of the `foo` namespace. + `reset #pvfd222s8n /topic` reset the branch `topic` of the + current project to the causal + `#pvfd222s8n`. + + rewrite (or sfind.replace) + `rewrite rule1` rewrites definitions in the latest scratch file. + + The argument `rule1` must refer to a `@rewrite` block or a + function that immediately returns a `@rewrite` block. It can + be in the codebase or scratch file. An example: + + rule1 x = @rewrite term x + 1 ==> Nat.increment x + + Here, `x` will stand in for any expression wherever this + rewrite is applied, so this rule will match `(42+10+11) + 1` + and replace it with `Nat.increment (42+10+11)`. + + See https://unison-lang.org/learn/structured-find to learn more. + + Also see the related command `rewrite.find` + + rewrite.find (or sfind) + `rewrite.find rule1` finds definitions that match any of the + left side(s) of `rule` in the current namespace. + + The argument `rule1` must refer to a `@rewrite` block or a + function that immediately returns a `@rewrite` block. It can + be in the codebase or scratch file. An example: + + -- right of ==> is ignored by this command + rule1 x = @rewrite term x + 1 ==> () + + Here, `x` will stand in for any expression, so this rule will + match `(42+10+11) + 1`. + + See https://unison-lang.org/learn/structured-find to learn more. + + Also see the related command `rewrite` + + run + `run mymain args...` Runs `!mymain`, where `mymain` is + searched for in the most recent + typechecked file, or in the codebase. + Any provided arguments will be passed as + program arguments as though they were + provided at the command line when + running mymain as an executable. + + run.native + `run.native main args` Executes !main using native + compilation via scheme. + + switch + `switch` opens an interactive selector to pick a + project and branch + `switch foo/bar` switches to the branch `bar` in the project + `foo` + `switch foo/` switches to the last branch you visited in + the project `foo` + `switch /bar` switches to the branch `bar` in the current + project + + test + `test` runs unit tests for the current branch + `test foo` runs unit tests for the current branch defined in + namespace `foo` + + test.all + `test.all` runs unit tests for the current branch (including the `lib` namespace). + + todo + `todo` lists the current namespace's outstanding issues, + including conflicted names, dependencies with missing names, + and merge precondition violations. + + ui + `ui` opens the Local UI in the default browser. + + undo + `undo` reverts the most recent change to the codebase. + + update + Adds everything in the most recently typechecked file to the + namespace, replacing existing definitions having the same + name, and attempts to update all the existing dependents + accordingly. If the process can't be completed automatically, + the dependents will be added back to the scratch file for your + review. + + update.old + `update.old` works like `add`, except that if a definition in + the file has the same name as an existing definition, the name + gets updated to point to the new definition. If the old + definition has any dependents, `update` will add those + dependents to a refactoring session, specified by an optional + patch.`update.old` adds all definitions in + the .u file, noting replacements + in the default patch for the + current namespace. + `update.old ` adds all definitions in the .u + file, noting replacements in the + specified patch. + `update.old foo bar` adds `foo`, `bar`, and their + dependents from the .u file, + noting any replacements into the + specified patch. + + update.old.nopatch + `update.old.nopatch` works like `update.old`, except it + doesn't add a patch entry for any updates. Use this when you + want to make changes to definitions without pushing those + changes to dependents beyond your codebase. An example is when + updating docs, or when updating a term you just added.`update.old.nopatch` updates + all definitions in the .u file. + `update.old.nopatch foo bar` updates `foo`, `bar`, and their + dependents from the .u file. + + update.old.preview + `update.old.preview` previews updates to the codebase from the most recently typechecked file. This command only displays cached typechecking results. Use `load` to reparse & typecheck the file if the context has changed. + + upgrade + `upgrade old new` upgrades library dependency `lib.old` to + `lib.new`, and, if successful, deletes `lib.old`. + + upgrade.commit (or commit.upgrade) + `upgrade.commit` merges a temporary branch created by the + `upgrade` command back into its parent branch, and removes the + temporary branch. + + For example, if you've done `upgrade foo bar` from main, then + `upgrade.commit` is equivalent to doing + + * switch /main + * merge /upgrade-foo-to-bar + * delete.branch /upgrade-foo-to-bar + + version + Print the version of unison you're running + + view + `view foo` shows definitions named `foo` within your current + namespace. + `view` without arguments invokes a search to select + definitions to view, which requires that `fzf` can be found + within your PATH. + + Supports glob syntax, where ? acts a wildcard, so + `view List.?` will show `List.map`, `List.filter`, etc, but + not `List.map.doc` (since ? only matches 1 name segment). + + view.global + `view.global foo` prints definitions of `foo` within your codebase. + `view.global` without arguments invokes a search to select definitions to view, which requires that `fzf` can be found within your PATH. + +scratch/main> help-topics + + 🌻 + + Here's a list of topics I can tell you more about: + + filestatus + messages.disallowedAbsolute + namespaces + projects + remotes + testcache + + Example: use `help filestatus` to learn more about that topic. + +scratch/main> help-topic filestatus + + Sorry, I wasn’t sure how to process your request. 📓 + Here's a list of possible status messages you might see for + definitions in a .u file. + needs update A definition with the same name as an + existing definition. Doing `update` + instead of `add` will turn this failure + into a successful update. + + term/ctor collision A definition with the same name as an + existing constructor for some data type. + Rename your definition or the data type + before trying again to `add` or `update`. + + ctor/term collision A type defined in the file has a + constructor that's named the same as an + existing term. Rename that term or your + constructor before trying again to `add` + or `update`. + blocked This definition was blocked because it + dependended on a definition with a failed + status. + extra dependency This definition was added because it was + a dependency of a definition explicitly + selected. + + You can run `help help-topic` for more information on using `help-topic` + `help-topics` lists all topics and `help-topics ` shows an explanation of that topic. + +scratch/main> help-topic messages.disallowedAbsolute + + Sorry, I wasn’t sure how to process your request. 🤖 + Although I can understand absolute (ex: .foo.bar) or relative + (ex: util.math.sqrt) references to existing definitions + (help namespaces to learn more), I can't yet handle giving new + definitions with absolute names in a .u file. + As a workaround, you can give definitions with a relative name + temporarily (like `exports.blah.foo`) and then use `move.*`. + + You can run `help help-topic` for more information on using `help-topic` + `help-topics` lists all topics and `help-topics ` shows an explanation of that topic. + +scratch/main> help-topic namespaces + + Sorry, I wasn’t sure how to process your request. 🧐 + There are two kinds of namespaces, absolute, such as (.foo.bar + or .base.math.+) and relative, such as (math.sqrt or + util.List.++). + Relative names are converted to absolute names by prepending + the current namespace. For example, if your Unison prompt + reads: .foo.bar> and your .u file looks like: x = 41 + then doing an add will create the definition with the absolute + name .foo.bar.x = 41 + and you can refer to x by its absolute name .foo.bar.x + elsewhere in your code. For instance: + answerToLifeTheUniverseAndEverything = .foo.bar.x + 1 + + You can run `help help-topic` for more information on using `help-topic` + `help-topics` lists all topics and `help-topics ` shows an explanation of that topic. + +scratch/main> help-topic projects + + Sorry, I wasn’t sure how to process your request. + A project is a versioned collection of code that can be + edited, published, and depended on other projects. Unison + projects are analogous to Git repositories. + project.create create a new project + projects list all your projects + branch create a new workstream + branches list all your branches + merge merge one branch into another + switch switch to a project or branch + push upload your changes to Unison Share + pull download code(/changes/updates) from Unison Share + clone download a Unison Share project or branch for contribution + Tip: Use `help project.create` to learn more. + For full documentation, see + https://unison-lang.org/learn/projects + + You can run `help help-topic` for more information on using `help-topic` + `help-topics` lists all topics and `help-topics ` shows an explanation of that topic. + +scratch/main> help-topic remotes + + Sorry, I wasn’t sure how to process your request. 🤖 + Local projects may be associated with at most one remote + project on Unison Share. When this relationship is + established, it becomes the default argument for a number of + share commands. For example, running `push` or `pull` in a + project with no arguments will push to or pull from the + associated remote, if it exists. + This association is created automatically on when a project is + created by `clone`. If the project was created locally then + the relationship will be established on the first `push`. + + You can run `help help-topic` for more information on using `help-topic` + `help-topics` lists all topics and `help-topics ` shows an explanation of that topic. + +scratch/main> help-topic testcache + + Sorry, I wasn’t sure how to process your request. 🎈 + Unison caches the results of test> watch expressions. Since + these expressions are pure and always yield the same result + when evaluated, there's no need to run them more than once! + A test is rerun only if it has changed, or if one of the + definitions it depends on has changed. + + You can run `help help-topic` for more information on using `help-topic` + `help-topics` lists all topics and `help-topics ` shows an explanation of that topic. + +``` +We should add a command to show help for hidden commands also. diff --git a/unison-src/transcripts/input-parse-errors.md b/unison-src/transcripts/input-parse-errors.md new file mode 100644 index 0000000000..fe67a06cd9 --- /dev/null +++ b/unison-src/transcripts/input-parse-errors.md @@ -0,0 +1,173 @@ +# demonstrating our new input parsing errors + +```ucm:hide +scratch/main> builtins.merge lib.builtin +``` + +```unison:hide +x = 55 +``` +```ucm:hide +scratch/main> add +``` + +`handleNameArg` parse error in `add` +```ucm:error +scratch/main> add . +scratch/main> ls +scratch/main> add 1 +scratch/main> ls +scratch/main> add 2 +``` + +todo: +```haskell + SA.Name name -> pure name + SA.NameWithBranchPrefix (Left _) name -> pure name + SA.NameWithBranchPrefix (Right prefix) name -> pure $ Path.prefixNameIfRel (Path.AbsolutePath' prefix) name + SA.HashQualified hqname -> maybe (Left "can’t find a name from the numbered arg") pure $ HQ.toName hqname + SA.HashQualifiedWithBranchPrefix (Left _) hqname -> pure $ HQ'.toName hqname + SA.HashQualifiedWithBranchPrefix (Right prefix) hqname -> + pure . Path.prefixNameIfRel (Path.AbsolutePath' prefix) $ HQ'.toName hqname + SA.ShallowListEntry prefix entry -> + pure . HQ'.toName . fmap (Path.prefixNameIfRel prefix) $ shallowListEntryToHQ' entry + SA.SearchResult mpath result -> + maybe (Left "can’t find a name from the numbered arg") pure . HQ.toName $ searchResultToHQ mpath result + otherNumArg -> Left . I.Formatted $ wrongStructuredArgument "a name" otherNumArg +``` + +aliasMany: skipped -- similar to `add` + +```ucm:error +scratch/main> update arg +``` + +aliasTerm +``` +scratch/main> alias.term ##Nat.+ Nat.+ +``` + +aliasTermForce, +aliasType, + + +todo: +``` + +aliasMany, +api, +authLogin, +back, +branchEmptyInputPattern, +branchInputPattern, +branchRenameInputPattern, +branchesInputPattern, +cd, +clear, +clone, +compileScheme, +createAuthor, +debugClearWatchCache, +debugDoctor, +debugDumpNamespace, +debugDumpNamespaceSimple, +debugTerm, +debugTermVerbose, +debugType, +debugLSPFoldRanges, +debugFileHashes, +debugNameDiff, +debugNumberedArgs, +debugTabCompletion, +debugFuzzyOptions, +debugFormat, +delete, +deleteBranch, +deleteProject, +deleteNamespace, +deleteNamespaceForce, +deleteTerm, +deleteTermVerbose, +deleteType, +deleteTypeVerbose, +deleteVerbose, +dependencies, +dependents, +diffNamespace, +display, +displayTo, +docToMarkdown, +docs, +docsToHtml, +edit, +editNamespace, +execute, +find, +findIn, +findAll, +findInAll, +findGlobal, +findShallow, +findVerbose, +findVerboseAll, +sfind, +sfindReplace, +forkLocal, +help, +helpTopics, +history, +ioTest, +ioTestAll, +libInstallInputPattern, +load, +makeStandalone, +mergeBuiltins, +mergeIOBuiltins, +mergeOldInputPattern, +mergeOldPreviewInputPattern, +mergeOldSquashInputPattern, +mergeInputPattern, +mergeCommitInputPattern, +names False, -- names +names True, -- names.global +namespaceDependencies, +previewAdd, +previewUpdate, +printVersion, +projectCreate, +projectCreateEmptyInputPattern, +projectRenameInputPattern, +projectSwitch, +projectsInputPattern, +pull, +pullWithoutHistory, +push, +pushCreate, +pushExhaustive, +pushForce, +quit, +releaseDraft, +renameBranch, +renameTerm, +renameType, +moveAll, +reset, +resetRoot, +runScheme, +saveExecuteResult, +test, +testAll, +todo, +ui, +undo, +up, +update, +updateBuiltins, +updateOld, +updateOldNoPatch, +upgrade, +upgradeCommitInputPattern, +view, +viewGlobal, +viewReflog +``` diff --git a/unison-src/transcripts/input-parse-errors.output.md b/unison-src/transcripts/input-parse-errors.output.md new file mode 100644 index 0000000000..35718aea33 --- /dev/null +++ b/unison-src/transcripts/input-parse-errors.output.md @@ -0,0 +1,202 @@ +# demonstrating our new input parsing errors + +```unison +x = 55 +``` + +`handleNameArg` parse error in `add` +```ucm +scratch/main> add . + + Sorry, I wasn’t sure how to process your request. 1:2: | 1 | . + | ^ unexpected end of input expecting '`' or operator (valid + characters: !$%&*+-/:<=>\^|~) + + You can run `help add` for more information on using `add` + `add` adds to the codebase all the definitions from the most recently typechecked file. + +scratch/main> ls + + 1. lib/ (469 terms, 74 types) + 2. x (Nat) + +scratch/main> add 1 + + + +scratch/main> ls + + 1. lib/ (469 terms, 74 types) + 2. x (Nat) + +scratch/main> add 2 + + ⊡ Ignored previously added definitions: x + +``` +todo: +```haskell + + SA.Name name -> pure name + SA.NameWithBranchPrefix (Left _) name -> pure name + SA.NameWithBranchPrefix (Right prefix) name -> pure $ Path.prefixNameIfRel (Path.AbsolutePath' prefix) name + SA.HashQualified hqname -> maybe (Left "can’t find a name from the numbered arg") pure $ HQ.toName hqname + SA.HashQualifiedWithBranchPrefix (Left _) hqname -> pure $ HQ'.toName hqname + SA.HashQualifiedWithBranchPrefix (Right prefix) hqname -> + pure . Path.prefixNameIfRel (Path.AbsolutePath' prefix) $ HQ'.toName hqname + SA.ShallowListEntry prefix entry -> + pure . HQ'.toName . fmap (Path.prefixNameIfRel prefix) $ shallowListEntryToHQ' entry + SA.SearchResult mpath result -> + maybe (Left "can’t find a name from the numbered arg") pure . HQ.toName $ searchResultToHQ mpath result + otherNumArg -> Left . I.Formatted $ wrongStructuredArgument "a name" otherNumArg + +``` + +aliasMany: skipped -- similar to `add` + +```ucm +scratch/main> update arg + + Sorry, I wasn’t sure how to process your request. I expected + no arguments, but received 1. + + You can run `help update` for more information on using `update` + Adds everything in the most recently typechecked file to the + namespace, replacing existing definitions having the same + name, and attempts to update all the existing dependents + accordingly. If the process can't be completed + automatically, the dependents will be added back to the + scratch file for your review. + +``` +aliasTerm +```scratch +/main> alias.term ##Nat.+ Nat.+ + +``` + +aliasTermForce, +aliasType, + + +todo: +```alias +Many, +api, +authLogin, +back, +branchEmptyInputPattern, +branchInputPattern, +branchRenameInputPattern, +branchesInputPattern, +cd, +clear, +clone, +compileScheme, +createAuthor, +debugClearWatchCache, +debugDoctor, +debugDumpNamespace, +debugDumpNamespaceSimple, +debugTerm, +debugTermVerbose, +debugType, +debugLSPFoldRanges, +debugFileHashes, +debugNameDiff, +debugNumberedArgs, +debugTabCompletion, +debugFuzzyOptions, +debugFormat, +delete, +deleteBranch, +deleteProject, +deleteNamespace, +deleteNamespaceForce, +deleteTerm, +deleteTermVerbose, +deleteType, +deleteTypeVerbose, +deleteVerbose, +dependencies, +dependents, +diffNamespace, +display, +displayTo, +docToMarkdown, +docs, +docsToHtml, +edit, +editNamespace, +execute, +find, +findIn, +findAll, +findInAll, +findGlobal, +findShallow, +findVerbose, +findVerboseAll, +sfind, +sfindReplace, +forkLocal, +help, +helpTopics, +history, +ioTest, +ioTestAll, +libInstallInputPattern, +load, +makeStandalone, +mergeBuiltins, +mergeIOBuiltins, +mergeOldInputPattern, +mergeOldPreviewInputPattern, +mergeOldSquashInputPattern, +mergeInputPattern, +mergeCommitInputPattern, +names False, -- names +names True, -- names.global +namespaceDependencies, +previewAdd, +previewUpdate, +printVersion, +projectCreate, +projectCreateEmptyInputPattern, +projectRenameInputPattern, +projectSwitch, +projectsInputPattern, +pull, +pullWithoutHistory, +push, +pushCreate, +pushExhaustive, +pushForce, +quit, +releaseDraft, +renameBranch, +renameTerm, +renameType, +moveAll, +reset, +resetRoot, +runScheme, +saveExecuteResult, +test, +testAll, +todo, +ui, +undo, +up, +update, +updateBuiltins, +updateOld, +updateOldNoPatch, +upgrade, +upgradeCommitInputPattern, +view, +viewGlobal, +viewReflog + +``` + diff --git a/unison-src/transcripts/merge.output.md b/unison-src/transcripts/merge.output.md index 258413502d..46280da177 100644 --- a/unison-src/transcripts/merge.output.md +++ b/unison-src/transcripts/merge.output.md @@ -6,22 +6,26 @@ branch. For example, to merge `topic` into `main`, switch to `main` and run `mer ```ucm .> help merge -merge -`merge /branch` merges `branch` into the current branch + Sorry, I wasn’t sure how to process your request. merge + `merge /branch` merges `branch` into the current branch + + You can run `help help` for more information on using `help` + `help` shows general help and `help ` shows help for one command. .> help merge.commit -merge.commit (or commit.merge) -`merge.commit` merges a temporary branch created by the `merge` -command back into its parent branch, and removes the temporary -branch. - -For example, if you've done `merge topic` from main, then -`merge.commit` is equivalent to doing - - * switch /main - * merge /merge-topic-into-main - * delete.branch /merge-topic-into-main + Sorry, I wasn’t sure how to process your request. merge.commit + (or commit.merge) + `merge.commit` merges a temporary branch created by the + `merge` command back into its parent branch, and removes the + temporary branch. + For example, if you've done `merge topic` from main, then + `merge.commit` is equivalent to doing * switch /main * + merge /merge-topic-into-main * + delete.branch /merge-topic-into-main + + You can run `help help` for more information on using `help` + `help` shows general help and `help ` shows help for one command. ``` Let's see a simple unconflicted merge in action: Alice (us) and Bob (them) add different terms. The merged result diff --git a/unison-src/transcripts/pull-errors.output.md b/unison-src/transcripts/pull-errors.output.md index 4890a5c1d1..13731c20f5 100644 --- a/unison-src/transcripts/pull-errors.output.md +++ b/unison-src/transcripts/pull-errors.output.md @@ -12,10 +12,10 @@ test/main> pull @aryairani/test-almost-empty/main lib.base_latest test/main> pull @aryairani/test-almost-empty/main a.b - Sorry, I wasn’t sure how to process your request. I think - you're wanting to merge @aryairani/test-almost-empty/main into - the a.b namespace, but the `pull` command only supports - merging into the top level of a local project branch. + Sorry, I wasn’t sure how to process your request. I think you + want to merge @aryairani/test-almost-empty/main into the a.b + namespace, but the `pull` command only supports merging into + the top level of a local project branch. You can run `help pull` for more information on using `pull` The `pull` command merges a remote namespace into a local @@ -49,10 +49,10 @@ test/main> pull @aryairani/test-almost-empty/main a test/main> pull @aryairani/test-almost-empty/main .a - Sorry, I wasn’t sure how to process your request. I think - you're wanting to merge @aryairani/test-almost-empty/main into - the .a namespace, but the `pull` command only supports merging - into the top level of a local project branch. + Sorry, I wasn’t sure how to process your request. I think you + want to merge @aryairani/test-almost-empty/main into the .a + namespace, but the `pull` command only supports merging into + the top level of a local project branch. You can run `help pull` for more information on using `pull` The `pull` command merges a remote namespace into a local