Merge branch 'master' into backport

.github/workflows/CI.yml

@@ -1,15 +1,10 @@
 name: CI
 on:
-  push:
-    branches:
-      - 'master'
-    tags: '*'
   pull_request:
     types:
     - opened
     - reopened
     - synchronize
-    - ready_for_review
 
 jobs:
   test:
@@ -21,7 +16,7 @@ jobs:
         version:
           - '1.6'
           - '1' # latest 1.X
-          # - 'nightly'
+          - 'nightly'
         os:
           - ubuntu-latest
           - windows-latest

.github/workflows/Invalidations.yml

@@ -0,0 +1,44 @@
+name: Invalidations
+
+on: 
+  pull_request:
+    types:
+    - ready_for_review
+
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: always.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  evaluate:
+    # Only run on PRs to the default branch.
+    # In the PR trigger above branches can be specified only explicitly whereas this check should work for master, main, or any other default branch
+    if: github.base_ref == github.event.repository.default_branch
+    runs-on: ubuntu-latest
+    steps:
+    - uses: julia-actions/setup-julia@v1
+      with:
+        version: '1'
+    - uses: actions/checkout@v3
+    - uses: julia-actions/julia-buildpkg@v1
+    - uses: julia-actions/julia-invalidations@v1
+      id: invs_pr
+
+
+    - uses: actions/checkout@v3
+      with:
+        ref: ${{ github.event.repository.default_branch }}
+    - uses: julia-actions/julia-buildpkg@v1
+    - uses: julia-actions/julia-invalidations@v1
+      id: invs_default
+
+
+    - name: Report invalidation counts
+      run: |
+        echo "Invalidations on default branch: ${{ steps.invs_default.outputs.total }} (${{ steps.invs_default.outputs.deps }} via deps)" >> $GITHUB_STEP_SUMMARY
+        echo "This branch: ${{ steps.invs_pr.outputs.total }} (${{ steps.invs_pr.outputs.deps }} via deps)" >> $GITHUB_STEP_SUMMARY
+    - name: Check if the PR does increase number of invalidations
+      if: steps.invs_pr.outputs.total > steps.invs_default.outputs.total
+      run: exit 1

.github/workflows/unused_dependencies.yml

@@ -0,0 +1,18 @@
+name: Check for unused dependencies
+
+on: 
+  pull_request:
+    types:
+    - ready_for_review
+
+
+jobs:
+  treeshake:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: 1
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-treeshake@main

Project.toml

@@ -1,9 +1,10 @@
 name = "Term"
 uuid = "22787eb5-b846-44ae-b979-8e399b8463ab"
 authors = ["FedeClaudi <federicoclaudi@protonmail.com> and contributors"]
-version = "1.0.4"
+version = "1.2.0"
 
 [deps]
+AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
 CodeTracking = "da1fd8a2-8d9e-5ec2-8556-3022fb5608a2"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 Highlights = "eafb193a-b7ab-5a9e-9068-77385905fa72"
@@ -16,9 +17,11 @@ Parameters = "d96e819e-fc66-5662-9728-84c9c7592b0a"
 ProgressLogging = "33c8b6b6-d38a-422a-b730-caa89a2f386c"
 Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
 UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
+Unicode = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"
 UnicodeFun = "1cfade01-22cf-5700-b092-accc4b62d6e1"
 
 [compat]
+AbstractTrees = "0.4"
 CodeTracking = "1"
 Highlights = "0.5"
 MyterialColors = "0.3"

codecov.yaml

@@ -2,5 +2,6 @@
 ignore:
   - "./src/errors.jl"
   - "./src/_errors.jl"
+  - "./src/__precompilation.jl"
   - "./test"       
   - "./scripts"         

docs/Project.toml

@@ -1,6 +1,7 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 JuliaFormatter = "98e50ef6-434e-11e9-1051-2b60c6c9e899"
+Suppressor = "fd094767-a336-5f1f-9728-57cf17d0bbfb"
 Term = "22787eb5-b846-44ae-b979-8e399b8463ab"
 
 [compat]

docs/make.jl

@@ -23,13 +23,16 @@ makedocs(;
             "basics/renderables.md",
             "basics/tprint.md",
             "basics/console.md",
+            "basics/prompt.md",
+            "basics/markdown.md",
         ],
         "Renderables" => Any[
             "ren/intro.md",
             "ren/text.md",
             "ren/panel.md",
             "ren/table.md",
             "ren/layout_rens.md",
+            "ren/annotation.md",
             "ren/dendogram.md",
             "ren/tree.md",
         ],
@@ -48,7 +51,6 @@ makedocs(;
             "adv/logging.md",
             "adv/errors_tracebacks.md",
             "adv/introspection.md",
-            "adv/markdown.md",
         ],
         "API" => Any[
             "api/api_term.md",

docs/src/adv/errors_tracebacks.md

@@ -6,14 +6,46 @@ In `Logging` we've seen how `Term` can replace the default logging system in Jul
 !!! warning "not for developers"
     Setting up Term's error handling will change this behavior for any downstream user of your code. While this could be okay, it might be surprising and undesirable for some, so do at your own risk. If you're writing code just for you, then go ahead! Term's error messages look great and hopefully they'll help finding and fixing errors more quickly.
 
+
+
 Setting up `Term` to handle errors for you is very simple:
 ```Julia
 import Term: install_term_stacktrace
 
 install_term_stacktrace()  # entering the danger zone
 
-1 + "this wont work"
+function test()
+    sum([])
+end
+
+test()
+
+
 ```
 
 ![](stacktrace.png)
 
+
+### Term is opinionated
+
+In altering Julia's default stacktraces handling, a few choices where made such as: inveriting the order in which the backtrace's stack frames are shown and hiding frames from `Base` or other packages installed through `Pkg` (similarly to [AbbreviatedStackTraces.jl](/~https://github.com/BioTurboNick/AbbreviatedStackTraces.jl)).
+When installing `Term`'s stacktrace system with `install_term_stacktrace`, you can use the keyword arguments to alter this behavior
+
+```@example
+using Term # hide
+install_term_repr() # hide
+install_term_stacktrace(;
+    reverse_backtrace = true,  # change me!
+    max_n_frames = 30,
+    hide_frames = false,
+)
+```
+
+but you can also do more, if you just want to quickly change some options (e.g. to deal with a particularly though bug). You can set flags to change the behavior on the fly:
+
+```@example
+import Term: STACKTRACE_HIDDEN_MODULES, STACKTRACE_HIDE_FRAMES
+
+STACKTRACE_HIDDEN_MODULES[] = ["REPL", "OhMyREPL"]  # list names of modules you want ignored in the stacktrace
+STACKTRACE_HIDE_FRAMES[] = false # set to true to hide frame, false to show all of them
+```

docs/src/adv/introspection.md

@@ -12,7 +12,7 @@ You can now use `inspect(T::DataType)` to get all information you possibly need
 
 
 ```@meta
-CurrentModule = Introspection
+CurrentModule = Term.Introspection
 ```
 
 ```@docs

docs/src/api/api_annotations.md

@@ -0,0 +1,13 @@
+# Annotations
+```@meta
+CurrentModule = Term.Annotations
+```
+
+
+```@index
+Pages   = ["api_annotations.md"]
+```
+
+```@autodocs
+Modules = [Annotations]
+```

docs/src/api/api_prompt.md

@@ -0,0 +1,14 @@
+# Prompts
+```@meta
+CurrentModule = Term.Prompts
+```
+
+
+```@index
+Pages   = ["api_prompt.md"]
+```
+
+
+```@autodocs
+Modules = [Prompts]
+```

docs/src/basics/colors_and_theme.md

@@ -44,7 +44,7 @@ If the style information represents a color, `Term` first represents it as a `Ab
 The distinction between `NamedColor`, `BitColor` and `RGBColor` is necessary because the three color styles are represented by a different syntax in the ANSI codes. Naturally, `Term` users won't normally worry about this and can use whichever color formulation is most convenient.
 
 
-# [Panel](@id ThemeDocs)
+# [Theme](@id ThemeDocs)
 Term defines a `Theme` type that carries styling information used throughout. 
 It tells `highlight` what color things should be, it stores the colors of elements of [Tree](@ref TreeDoc), and of the [Repr functionality](@ref ReprDoc).
 
@@ -66,4 +66,12 @@ set_theme(newtheme)
 
 ```@example theme
 set_theme(Theme()) # hide
+```
+
+
+The default theme used by `Term` is tailored for a dark terminal, if you fancy a lighter terminal experience, you might want to:
+```julia
+import Term: set_theme, LightTheme
+
+set_theme(LightTheme)
 ```

docs/src/basics/console.md

@@ -24,7 +24,7 @@ tprintln("This is a very long text"^10)
 it also works for any `Renderable` made with Term:
 
 ```@example
-using Term: tprintln # hide
+using Term: tprintln, Panel # hide
 using Term.Consoles: Console, enable, disable #hide
 
 print(Panel())

docs/src/adv/markdown.md → docs/src/basics/markdown.md

@@ -5,7 +5,8 @@ Let's have a look.
 
 ```@example md
 import Term.Consoles: Console, enable, disable # hide
-con = Console(60) |> enable #hide
+con = Console(60) # hide
+enable(con) #hide
 import Term: tprintln
 using Term.TermMarkdown
 using Markdown

docs/src/basics/prompt.md

@@ -0,0 +1,66 @@
+# Prompt
+
+Time for a little example of a simple thing you can use `Term.jl` for: asking for some input. Use a `Prompt`, ask a question, get an answer. Simple, but a little extra style. That's what `AbstractPrompt` types are for. There's a few different flavors, which we'll look at in due time, but essentially a prompt is made of a bit of text, the `prompt` that is displayed to the user, and some machinery to capture the user's input and parse it/ validate it. 
+
+For example:
+
+```@example prompt
+using Term.Prompts
+
+prompt = Prompt("Simple, right?");
+```
+
+creates a `Prompt` object and `ask` then prints the propmt and asks for input: 
+```julia
+prompt |> ask
+```
+the output should look something like
+```@example prompt
+print(prompt)  # hide
+```
+
+here we construct a basic `Prompt` and "ask" it: print the message and capture the reply. `ask` returns the answer, which you can do with as you please. A small warning before we carry on:
+
+!!! warning "Using VSCode"
+    As you can see [here](https://discourse.julialang.org/t/vscode-errors-with-user-input-readline/75097/4?u=fedeclaudi), `readlines`, which `AbstractPrompts` use to get the user's input, is a bit troublesome in VSCode. In VSCode, after the prompt gets printed you need to enter "space" (hit the space bar) and then enter and **after** that you can enter your actual replies.
+
+## Prompt flavours
+There's a couple more ways you can use prompts like. One is to ensure you get an answer of the correct `Type`, using the immaginatively names `TypePrompt`:
+
+```@example prompt
+
+# this only accepts `Int`s
+prompt = TypePrompt(Int, "give me a number")  # don't forget to |> ask
+print(prompt) # hide
+```
+
+
+If your answer can't be converted to the correct type you'll get a `AnswerValidationError`, not good.
+
+
+So, what if you want to get user inputs, but you don't want to handle any crazy input they can provide? Fear not, use `OptionsPrompt` so that only acceptable options will be ok. This will keep "asking" your prompt until the user's answer matches one of the given options
+
+```@example prompt
+prompt = OptionsPrompt(["a lot", "so much", "the most"], "How likely would you be to recomend Term.jl to a friend or colleague?") # don't forget to |> ask
+print(prompt) # hide
+```
+
+Okay, so much typing though. Let's be realistic, most likely you just want to ask a yes/no question and the answer is likely just yes. So just use a `DefaultPrompt`:
+
+```@example prompt
+
+# one says the first option is the default
+prompt = DefaultPrompt(["yes", "no"], 1, "Confirm?") # don't forget to |> ask
+print(prompt) # hide
+```
+
+still too much typing? You can just use the `confirm` function which is equivalent to asking the prompt shown above. 
+
+
+## Style
+The style of prompt elements (e.g. the color of the prompt's text or of the options) is defined in `Theme`. You can also pass style information during prompt creation:
+
+```@example prompt
+Prompt("Do you like this color?", "red") |> println
+DefaultPrompt(["yes", "no"], 1, "Confirm?", "green", "blue", "red") |> println
+```

docs/src/layout/nesting.md

@@ -52,5 +52,41 @@ subtitle_justify=:right, subtitle_style="yellow default"
 )
 ```
 
+## Nested layouts? No head ache
+If you want to have several nested panels, you might want to make sure that their widths are set correctly so that they fit nicely together. There's a macro for that!
+
+```@example nesting
+import Term: @nested_panels
+@nested_panels Panel(
+    Panel(
+        Panel(
+            Panel(
+                ; title="deepest", style="blue", background="blue"
+            ); title="deeper", style="green");
+        title="not so deep");
+    style="red",
+    title="outer"
+) 
+```
+It sets the width of each panel to match their depth. It only works if you're actively calling Panel() in the macro call.
+something like this won't work:
+```@example nesting
+another_panel = Panel("this won't work")
+@nested_panels Panel(
+    Panel(
+        Panel(
+            Panel(
+                another_panel,
+                ; title="deepest", 
+            ); title="deeper", style="green");
+        title="not so deep");
+    style="red",
+    title="outer"
+) 
+
+```
+
+
+This is all nice, but, that's not enough... so let' see what more we can do!
+
 
-But, that's not enough... so let' see what more we can do!