* Add support for showing all LSPs in --health <lang>
* Add support for showing all LSPs in --health languages
* Use available/configured in --health languages
* Apply @AlexanderBrevig suggestion in --health
* Update `--health <language>`
Better output (inspired by #8156).
Handle the case where no LSPs are configured.
* Display all LSPs in `--health languages` instead of x/x
Displays all LSPs as a list in the table generated wih `--health languages`
* Make check_binary accept Optional references to str
Avoids some calls to .clone()
* Apply @the-mikedavis suggestions
* Avoid useless collecting and cloning
* Use for loop instead of .try_for_each()
* Accept +num flag for opening at line number
* Update +N argument feature according to feedback in original PR #5603
* Only override the line number of the first file if +N is specified
---------
Co-authored-by: Nachum Barcohen <38861757+nabaco@users.noreply.github.com>
* added working path arg to cli and help menu
* improve working path cli arg handling
* enable hx to set the working path
* applied cargo formatting
* improved code from cargo clippy suggestion
* improved code from follow up review
* fix for -w <path> is set but args.files is empty
* improved formatting of --help output
* adds treesitter-highlight-name command
* commit documentation changes
* moves the get_highlight_name function into core/syntax
* rename get_highlight_name function to get_highlight_for_node_at_position
* addresses pr comments: moves fn into helper fn, simplifies a lot
* commit updated documentation changes
* changes scope method to return &str so that callers can decide whether or not to own
* only stream from background thread if necessary
If the file transversal is longer shorter 30ms it will now be performed
on the main thread. Spawning a thread can take a while (or rather it
takes a while until that thread is scheduled) so the files can actually
take a while to show up. This prevents the `(running)` indicator from
briefly showing up when opening the file picker in a small directory.
* run partial cargo update
The completion component assumes that it operates on the same View but
it's possible to break this assumption by switching windows through
left-clicking. I believe we should clear the completion menu when
switching windows to fix this.
This change fixes a panic for this scenario:
* Open a buffer with LSP completion available
* Split the window (for example '<C-w>v')
* Enter insert mode and trigger the completion menu
* Select a completion candidate (for example with '<C-n>')
* Switch to the original window by left-clicking in its area
* Enter insert mode and make edits (for example 'o<backspace>')
This will trip the 'assert_eq' in Document::restore.
* transition to nucleo for fuzzy matching
* drop flakey test case
since the picker streams in results now any test that relies
on the picker containing results is potentially flakely
* use crates.io version of nucleo
* Fix typo in commands.rs
Co-authored-by: Skyler Hawthorne <skyler@dead10ck.com>
---------
Co-authored-by: Skyler Hawthorne <skyler@dead10ck.com>
* fix: line numbers remain relative when helix loses focus
If `line number = relative` and a new window is opened in helix, lines inside unfocused windows will be `absolute`. This commit adds the same thing when helix becomes unfocused in a terminal emulator.
* partial rebase
* create separate timer for redraw requests
* Update helix-view/src/editor.rs
Co-authored-by: Michael Davis <mcarsondavis@gmail.com>
---------
Co-authored-by: Michael Davis <mcarsondavis@gmail.com>
YAML indents queries are tweaked to fix auto indent behavior.
A new capture type `indent.always` is introduced to address use cases
where combining indent captures on a single line is desired.
Fixes#6661
* fix(picker): `alt-ret' changes cursor pos of current file, not new one
Closes#7673
* fix other pickers
* symbol pickers
* diagnostick pickers
This is done using the already patched `jump_to_location` method.
* fix global and jumplist pickers
* use `view` as old_id; make `align_view` method of `Action`
* test(picker): basic <alt-ret> functionality
* fix: picker integrational test
* fix nit
Co-authored-by: Michael Davis <mcarsondavis@gmail.com>
---------
Co-authored-by: Michael Davis <mcarsondavis@gmail.com>
The clipboard special registers are able to retain multiple selections
and also join the value when copying it to the clipboard. So by default
we should yank regularly to the '*' and '+' registers. That will have
the same behavior for the clipboards but will allow pasting multiple
selections if the clipboard doesn't change between yanks.
Since the clipboard provider now lives on the Registers type, we want
to eliminate it from the Editor. We can do that and clean up the
commands that interact with the clipboard by calling regular yank,
paste and replace impls on the clipboard special registers.
Eventually the clipboard commands could be removed once macro keybinding
is supported.
This fixes a discrepancy between regular registers which are used for
yanking multiple values (for example via `"ay`) and regular registers
that store a history of values (for example `"a*`).
Previously, the preview shown in `select_register`'s infobox would show
the oldest value in history. It's intuitive and useful to see the most
recent value pushed to the history though.
We cannot simply switch the preview line from `values.first()`
to `values.last()`: that would fix the preview for registers
used for history but break the preview for registers used to yank
multiple values. We could push to the beginning of the values with
`Registers::push` but this is wasteful from a performance perspective.
Instead we can have `Registers::read` return an iterator that
returns elements in the reverse order and reverse the values in
`Register::write`. This effectively means that `push` adds elements to
the beginning of the register's values. For the sake of the preview, we
can switch to `values.last()` and that is then correct for both usage-
styles. This also needs a change to call-sites that read the latest
history value to switch from `last` to `first`.
This is an unfortunately noisy change: we need to update virtually all
callsites that access the registers. For reads this means passing in the
Editor and for writes this means handling potential failure when we
can't write to a clipboard register.
This removes a handful of allocations for functions calling into the
function, which is nice because the prompt may call this function on
every keypress.
Pascal and I discussed this and we think it's generally better to
take a 'RopeSlice' rather than a '&Rope'. The code block rendering
function in the markdown component module is a good example for how
this can be useful: we can remove an allocation of a rope and instead
directly turn a '&str' into a 'RopeSlice' which is very cheap.
A change to prefer 'RopeSlice' to '&Rope' whenever the rope isn't
modified would be nice, but it would be a very large diff (around 500+
500-). Starting off with just the syntax functions seems like a nice
middle-ground, and we can remove a Rope allocation because of it.
Co-authored-by: Pascal Kuthe <pascal.kuthe@semimod.de>
Since regex is almost always injected into other languages,
`pattern_character`s will inherit the highlight for the structure that
injects them (for example `/foo/` in JavaScript or `~r/foo/` in Elixir).
This removes the string highlight when used in the prompt.
We also add `ERROR` node highlighting so that errors in regex syntax
appear in the prompt. This resolves a TODO in the `regex_prompt`
function about highlighting errors in the regex.
We can use tree-sitter-regex highlighting in prompts for entering
regexes, like `search` or `global_search`. The `highlighted_code_block`
function from the markdown component makes this a very small change.
This could be improved in the future by leaving the parsed syntax tree
on the prompt, allowing incremental updates. Prompt lines are usually so
short though and tree-sitter-regex is rather small and uncomplicated,
so that improvement probably wouldn't make a big difference.
* Add initial support for LSP DidChangeWatchedFiles
* Move file event Handler to helix-lsp
* Simplify file event handling
* Refactor file event handling
* Block on future within LSP file event handler
* Fully qualify uses of the file_event::Handler type
* Rename ops field to options
* Revert newline removal from helix-view/Cargo.toml
* Ensure file event Handler is cleaned up when lsp client is shutdown
* _apply_motion generalization where possible
API encourages users to not forget setting `editor.last_motion` when
applying a motion. But also not setting `last_motion` without applying a
motion first.
* (rename) will_find_char -> find_char
method name makes it sound like it would be returning a boolean.
* use _apply_motion in find_char
Feature that falls out from this is that repetitions of t,T,f,F are
saved with the context extention/move and count. (Not defaulting to extend
by 1 count).
* Finalize apply_motion API
last_motion is now a private field and can only be set by calling
Editor.apply_motion(). Removing need (and possibility) of writing:
`motion(editor); editor.last_motion = motion`
Now it's just: `editor.apply_motion(motion)`
* editor.last_message: rm Box wrap around Arc
* Use pre-existing `Direction` rather than custom `SearchDirection`.
* `LastMotion` type alias for `Option<Arc<dyn Fn(&mut Editor)>>`
* Take motion rather than cloning it.
Co-authored-by: Michael Davis <mcarsondavis@gmail.com>
* last_motion as Option<Motion>.
* Use `Box` over `Arc` for `last_motion`.
---------
Co-authored-by: Michael Davis <mcarsondavis@gmail.com>
The spec explicitly disallows publishDiagnostic to be sent before
the initialize response:
> ... the server is not allowed to send any requests or notifications to
> the client until it has responded with an InitializeResult ...
(https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#initialize)
But if a non-compliant server sends this we currently panic because we
'.expect()' the server capabilities to be known to fetch the position
encoding. Instead of panicking we can discard the notification and log
the non-compliant behavior.
Merges the code for the Picker and FilePicker into a single Picker that
can show a file preview if a preview callback is provided. This change
was mainly made to facilitate refactoring out a simple skeleton of a
picker that does not do any filtering to be reused in a normal Picker
and a DynamicPicker (see #5714; in particular [mikes-comment] and
[gokuls-comment]).
The crux of the issue is that a picker maintains a list of predefined
options (eg. list of files in the directory) and (re-)filters them every
time the picker prompt changes, while a dynamic picker (eg. interactive
global search, #4687) recalculates the full list of options on every
prompt change. Using a filtering picker to drive a dynamic picker hence
does duplicate work of filtering thousands of matches for no reason. It
could also cause problems like interfering with the regex pattern in the
global search.
I tried to directly extract a PickerBase to be reused in Picker and
FilePicker and DynamicPicker, but the problem is that DynamicPicker is
actually a DynamicFilePicker (i.e. it can preview file contents) which
means we would need PickerBase, Picker, FilePicker, DynamicPicker and
DynamicFilePicker and then another way of sharing the previewing code
between a FilePicker and a DynamicFilePicker. By merging Picker and
FilePicker into Picker, we only need PickerBase, Picker and
DynamicPicker.
[gokuls-comment]: https://github.com/helix-editor/helix/issues/5714#issuecomment-1410949578
[mikes-comment]: https://github.com/helix-editor/helix/issues/5714#issuecomment-1407451963
Resolves issue #6888 by adding a command to join all selections and yank
them to the specified register. The typed command takes an argument as
the separator to use when joining the selections.
Previously a count or register selection would be lost while opening
the command palette. This change allows using a register selection or
count in any command chosen from the command palette.
Previously the register selection (via `"`) would be lost in the middle
of any key sequence longer than one key. For example, `<space>f` would
clear the register selection after the `<space>` making it inaccessible
for the `file_picker` command.
This behavior does not currently have any effect in the default keymap
but might affect custom keymaps. This change aligns the behavior of the
register with count. Making this change allows propagating the register
to the `command_palette` (see the child commit) or other pickers should
we decide to use registers in those in the future. (Interactive global
search for example.)
Does not change any behavior other than making the tuple slightly
more idiomatic. Keymap infobox shows key events, then the respective
description. This commit makes sure that order is used from the get go,
rather than flipping it midway.
* chore: avoid format! call with argument when useless
* feat: also clear diagnostics for unopened documents when exiting an LSP
* feat: we already worked on `self.editor.diagnostics` no need to redo the checks
* Add command for merging non-consecutive ranges
* Add `merge_selections` command to book
* Simplify `merge_ranges`
Heeded the advice of @the-mikedavis to stop iterating over all ranges and simply merge the first and the last range, as the invariants of `Selection` guarantee that the list of ranges is always sorted and never empty.
* Clarify doc comment of `merge_ranges`
* Add `helix_lsp::client::Client::supports_feature(&self, LanguageServerFeature)`
* Extend `doc.language_servers_with_feature` to use this method as filter as well
* Add macro `language_server_with_feature!` to reduce boilerplate for non-mergeable language server requests (like goto-definition)
* Refactored most of the `find_map` code to use the either the macro or filter directly via `doc.language_servers_with_feature`
Language Servers are now configured in a separate table in `languages.toml`:
```toml
[langauge-server.mylang-lsp]
command = "mylang-lsp"
args = ["--stdio"]
config = { provideFormatter = true }
[language-server.efm-lsp-prettier]
command = "efm-langserver"
[language-server.efm-lsp-prettier.config]
documentFormatting = true
languages = { typescript = [ { formatCommand ="prettier --stdin-filepath ${INPUT}", formatStdin = true } ] }
```
The language server for a language is configured like this (`typescript-language-server` is configured by default):
```toml
[[language]]
name = "typescript"
language-servers = [ { name = "efm-lsp-prettier", only-features = [ "format" ] }, "typescript-language-server" ]
```
or equivalent:
```toml
[[language]]
name = "typescript"
language-servers = [ { name = "typescript-language-server", except-features = [ "format" ] }, "efm-lsp-prettier" ]
```
Each requested LSP feature is priorized in the order of the `language-servers` array.
For example the first `goto-definition` supported language server (in this case `typescript-language-server`) will be taken for the relevant LSP request (command `goto_definition`).
If no `except-features` or `only-features` is given all features for the language server are enabled, as long as the language server supports these. If it doesn't the next language server which supports the feature is tried.
The list of supported features are:
- `format`
- `goto-definition`
- `goto-declaration`
- `goto-type-definition`
- `goto-reference`
- `goto-implementation`
- `signature-help`
- `hover`
- `document-highlight`
- `completion`
- `code-action`
- `workspace-command`
- `document-symbols`
- `workspace-symbols`
- `diagnostics`
- `rename-symbol`
- `inlay-hints`
Another side-effect/difference that comes with this PR, is that only one language server instance is started if different languages use the same language server.
There was an issue with autocompletion of a path with a space in it.
Before:
:o test\ dir -> <TAB> -> test\ dirfile1
After:
:o test\ dir -> <TAB> -> test\ dir\file1
Currently, when forward deleting (`delete_char_forward` bound to `del`,
`delete_word_forward`, `kill_to_line_end`) the cursor is moved to the
left in append mode (or generally when the cursor is at the end of the
selection). For example in a document `|abc|def` (|indicates selection)
if enter append mode the cursor is moved to `c` and the selection
becomes: `|abcd|ef`. When deleting forward (`del`) `d` is deleted. The
expectation would be that the selection doesn't shrink so that `del`
again deletes `e` and then `f`. This would look as follows:
`|abcd|ef`
`|abce|f`
`|abcf|`
`|abc |`
This is inline with how other editors like kakoune work.
However, helix currently moves the selection backwards leading to the
following behavior:
`|abcd|ef`
`|abc|ef`
`|ab|ef`
`ef`
This means that `delete_char_forward` essentially acts like
`delete_char_backward` after deleting the first character in append
mode.
To fix the problem the cursor must be moved to the right while deleting
forward (first fix in this commit). Furthermore, when the EOF char is
reached a newline char must be inserted (just like when entering
appendmode) to prevent the cursor from moving to the right
Some deletion operations (especially those that use indentation)
can generate overlapping deletion ranges when using multiple cursors.
To fix that problem a new `Transaction::delete` and
`Transaction:delete_by_selection` function were added. These functions
merge overlapping deletion ranges instead of generating an invalid
transaction. This merging of changes is only possible for deletions
and not for other changes and therefore require its own function.
The function has been used in all commands that currently delete
text by using `Transaction::change_by_selection`.
When re requesting a completion that already has a selected item we
reuse that selections savepoint. However, the selection has likely
changed since that savepoint which requires us to use the selection
from that savepoint
* inject language based on file extension
Nodes can now be captured with "injection.filename". If this capture
contains a valid file extension known to Helix, then the content will
be highlighted as that language.
* inject language by shebang
Nodes can now be captured with "injection.shebang". If this capture
contains a valid shebang line known to Helix, then the content will
be highlighted as the language the shebang calls for.
* add documentation for language injection
* nix: fix highlights
The `@` is now highlighted properly on either side of the function arg.
Also, extending the phases with `buildPhase = prev.buildPhase + ''''`
is now highlighted properly.
Fix highlighting of `''$` style escapes (requires tree-sitter-nix bump)
Fix `inherit` highlighting.
* simplify injection_for_match
Split out injection pair logic into its own method to make the overall
flow easier to follow.
Also transform the top-level function into a method on a
HighlightConfiguration.
* markdown: add shebang injection query
This picks up changes to the `editor.mouse` option at runtime - either
through `:set-option` or `:config-reload`. When the value changes, we
tell the terminal to enable or disable mouse capture sequences.
* Fix crash on opening from suspend state (#6725)
* Fix code style
* revert using of the imperative code style. Add panic if couldn't set terminal raw mode
* remove redundant import of core::panic macros
* small refactoring
* Fix#6669: Theme preview doesn't return theme to normal when delete name with Alt-Backspace
* Fix#6669: Return theme preview to normal theme for all remaining keybinds that change the promt text
The current implementation didn't reload the theme if no no theme was
explicitly configured (so the default theme was used). This commit
brings `refresh_theme` in line with the initialization code.
Add new theme highlight keys, for setting the colour of the breakpoint
character and the current line at which execution has been paused at.
The two new keys are `ui.highlight.frameline` and `ui.debug.breakpoint`.
Highlight according to those keys, both the line at which debugging
is paused at and the breakpoint indicator.
Add an indicator for the current line at which execution is paused
at, themed by the `ui.debug.active` theme scope. Update various themes
to showcase how the new functionality works.
Better icons are dependent on #2869, and as such will be handled in the
future, once it lands.
Closes: #5952
Signed-off-by: Filip Dutescu <filip.dutescu@gmail.com>
While scrolling (with the `scroll`) command scrolloff was calculated
slightly differently than in `ensure_cursor_in_view` which could cause
the cursor to get stuck while scrolling
Virtual text lines (either caused by softwrapped inlay hints that take
multiple or line annotations) currently block scrolling downwards.
if the visual offset passed to char_idx_at_visual_offset or
visual_offset_from_block is within a virtual text line then the char
position before the virtual text and a visual offset are returned.
We previously ignored that visual offset and as a result the cursor
would be stuck at the start of the virtual text. This commit fixes
that by simply moving the cursor to the next char (so past the virtual
text) if this visual offset is non-zero
The current test DSL currently has no way to express being at the end of
a line, save for putting an explicit LF or CRLF inside the `#[|]#`. The
problem with this approach is that it can add unintended extra new lines
if used in conjunction with raw strings, which insert newlines for you.
This is a simple attempt to mitigate this problem. If there is an
explicit newline character at the end of the selection, and then it
is immediately followed by the same newline character at the right end
of the selection, this following newline is removed. This way, one can
express a cursor at the end of a line explicitly.
* helix-term: send the STOP signal to all processes in the process group
From kill(3p):
If pid is 0, sig shall be sent to all processes (excluding an unspecified set
of system processes) whose process group ID is equal to the process group ID
of the sender, and for which the process has permission to send a signal.
This fixes the issue of running `git commit`, attempting to suspend
helix with ^Z, and then not regaining control over the terminal and
having to press ^Z again.
* helix-term: use libc directly to send STOP signal
* helix-term: document safety of libc::kill
* helix-term: properly handle libc::kill's failure
I misread the manpage for POSIX `kill` -- it returns `-1` in
the failure case, and sets `errno`, which is retrieved via
`std::io::Error::last_os_error()`, has its string representation printed
out, and then exits with the matching status code (or 1 if, for whatever
reason, there is no matching status code).
* helix-term: expand upon why we need to SIGSTOP the entire process group
Also add a link back to one of the upstream issues.
* misc: missing inline, outdated link
* doc: Add new theme keys and config option to book
* fix: don't panic in Tree::try_get(view_id)
Necessary for later, where we could be receiving an LSP response
for a closed window, in which case we don't want to crash while
checking for its existence
* fix: reset idle timer on all mouse events
* refacto: Introduce Overlay::new and InlineAnnotation::new
* refacto: extract make_job_callback from Context::callback
* feat: add LSP display_inlay_hint option to config
* feat: communicate inlay hints support capabilities of helix to LSP server
* feat: Add function to request range of inlay hint from LSP
* feat: Save inlay hints in document, per view
* feat: Update inlay hints on document changes
* feat: Compute inlay hints on idle timeout
* nit: Add todo's about inlay hints for later
* fix: compute text annotations for current view in view.rs, not document.rs
* doc: Improve Document::text_annotations() description
* nit: getters don't use 'get_' in front
* fix: Drop inlay hints annotations on config refresh if necessary
* fix: padding theming for LSP inlay hints
* fix: tracking of outdated inlay hints should not be dependant on document revision (because of undos and such)
* fix: follow LSP spec and don't highlight padding as virtual text
* config: add some LSP inlay hint configs
Multicursor completions may overlap and therefore overlapping
completions must be dropped to avoid crashes. Furthermore, multicursor
edits might simply be out of range if the word before/after the cursor
is shorter. This currently leads to crashes, instead these selections
are now also removed for completions.
This commit also significantly refactors snippet transaction generation
so that tabstops behave correctly with the above rules. Furthermore,
snippet tabstops need to be carefully mapped to ensure their position
is correct and consistent with our selection semantics. Finally,
we now keep a partially updated Rope while creating snippet
transactions so that we can fill information into snippets that
depends on the position in the document.
Most LSPs will complete case-insensitive matches, particularly from
lowercase to uppercase. In some cases, notably Pyright, this is given
as a simple insert text instead of TextEdit. When this happens, the
prefix text was left unedited.
* Generalised to multiple runtime directories with priorities
This is an implementation for #3346.
Previously, one of the following runtime directories were used:
1. `$HELIX_RUNTIME`
2. sibling directory to `$CARGO_MANIFEST_DIR`
3. subdirectory of user config directory
4. subdirectory of path to helix executable
The first directory provided / found to exist in this order was used as a
root for all runtime file searches (grammars, themes, queries).
This change lowers the priority of `$HELIX_RUNTIME` so that the user
config runtime has higher priority. More significantly, all of these
directories are now searched for runtime files, enabling a user to override
default or system-level runtime files. If the same file name appears
in multiple runtime directories, the following priority is now used:
1. sibling directory to `$CARGO_MANIFEST_DIR`
2. subdirectory of user config directory
3. `$HELIX_RUNTIME`
4. subdirectory of path to helix executable
One exception to this rule is that a user can have a `themes`
directory directly in the user config directory that has higher piority
to `themes` directories in runtime directories. That behaviour has been
preserved.
As part of implementing this feature `theme::Loader` was simplified
and the cycle detection logic of the theme inheritance was improved to
cover more cases and to be more explicit.
* Removed AsRef usage to avoid binary growth
* Health displaying ;-separated runtime dirs
* Changed HELIX_RUNTIME build from src instructions
* Updated doc for more detail on runtime directories
* Improved health symlink printing and theme cycle errors
The health display of runtime symlinks now prints both ends of the
link.
Separate errors are given when theme file is not found and when the
only theme file found would form an inheritence cycle.
* Satisfied clippy on passing Path
* Clarified highest priority runtime directory purpose
* Further clarified multiple runtime details in book
Also gave markdown headings to subsections.
Fixed a error with table indentation not building
table that also appears present on master.
---------
Co-authored-by: Paul Scott <paul.scott@anu.edu.au>
Co-authored-by: Blaž Hrastnik <blaz@mxxn.io>
* Fix#6092
Cause were some incorrect assumptions that missed an edge case in the
`Selection.contains()` calculation. Tests were added accordingly.
* Fix Selection.contains() edge-case handling.
Removing the len check short-circuit was the only thing needed as
pointed out by @dead10ck.
Repeating completions currently crates a savepoint when a completion
popup was triggered (so after the request completed). Just like for
normal completions the savepoint must be created at the request.
The occurrence of the completion request was previously not saved in
`last_insert`. To that end a new `InsertEvent::RequestCompletion`
variant has been added. When replayed this event creates a snapshot
that is "actived" by the `TriggerCompletion` event and subsequently
used during any `InsertEvent::CompletiuonApply` events.
Completion requests are computed asynchronously to avoid common micro
freezes while editing. This means that once a completion request
completes, the state of the editor might have changed. Currently,
there is a check to ensure we are still in insert mode. However,
we also need to ensure that the view and document hasn't changed
to avoid accidentally using a savepoint with the wrong view/document.
Furthermore, the editor might request a new completion while the
previous completion request hasn't complemented yet. This can
lead to weird flickering or an outdated completion request replacing
a newer completion that has already completed (the LSP server
is not required to process completion requests in order). This change
also needed to ensure determinism/linear ordering so that completion
popup always correspond to the last completion request.
Fixing autocomplete required moving the document savepoint before the
asynchronous completion request. However, this in turn causes new bugs:
If the completion popup is open, the savepoint is restored when the
popup closes (or another entry is selected). However, at that point
a new completion request might already have been created which
would have replaced the new savepoint (therefore leading to incorrectly
applied complies).
This commit fixes that bug by allowing in arbitrary number of
savepoints to be tracked on the document. The savepoints are reference
counted and therefore remain valid as long as any reference to them
remains. Weak reference are stored on the document and any reference
that can not be upgraded anymore (hence no strong reference remain)
are automatically discarded.