Skip to content

Make it possible to deprecate constants#5582

Closed
MDLC01 wants to merge 8 commits intotypst:mainfrom
MDLC01:deprecated-constants
Closed

Make it possible to deprecate constants#5582
MDLC01 wants to merge 8 commits intotypst:mainfrom
MDLC01:deprecated-constants

Conversation

@MDLC01
Copy link
Collaborator

@MDLC01 MDLC01 commented Dec 15, 2024

Overview

This PR adds the ability to deprecate constants from the standard library (i.e., no syntax is provided to enable the user to deprecate things). When a deprecated constant is used, a warning will be emitted. As of now, no constant is deprecated, so this cannot be observed.

The second commit bumps Codex to typst/codex#19, and retrieves deprecation info from Codex to mark deprecated symbols and modules as such in Typst. This PR is marked as a draft for now as it requires typst/codex#19 to be merged first. Undone by the last commit, as per #5582 (comment).

Implementation details

I can think of three notable details:

  • I did not change the behavior of crates/typst-ide, nor doc. In the future, we may want to use deprecation information in those crates.

  • When importing a deprecated constant, no warning is emitted. Instead, a warning is emitted when the symbol is used. This is because emitting a warning when importing a deprecated constant does not make sense in the case of a wildcard import. Moreover, emitting a warning on import would likely result in duplicated warnings: one when the constant is imported, and another one when it is used.

  • When importing a value called is, a warning used to be emitted about is being a future keyword. I removed it, because the same warning is already emitted at the place where the binding is defined.

Testing

For now, I have not extensively tested this, but I will in the following days. I added two tests.

@MDLC01
Copy link
Collaborator Author

MDLC01 commented Dec 17, 2024

I marked pattern as deprecated and added some tests.

@MDLC01
Copy link
Collaborator Author

MDLC01 commented Dec 19, 2024

I don't know how close we are to the next Typst release, and therefore how urgent this PR is, but I can decouple it from typst/codex#19 if necessary.

@laurmaedje
Copy link
Member

Decoupling it would be nice in principle. I haven't yet commented here because the amount of changes seem quite large, but I haven't yet considered things enough to comment on whether that's unavoidable or whether it could be simplified.

@MDLC01 MDLC01 force-pushed the deprecated-constants branch from db2337a to 2d9f0c3 Compare December 19, 2024 21:21
@MDLC01
Copy link
Collaborator Author

MDLC01 commented Dec 19, 2024

If that helps, in the first commit, the main changes are in scope.rs and diag.rs.

@laurmaedje
Copy link
Member

Two thoughts:

  • Instead of having _deprecated variants for the define_* methods, how about having one mutable method? So that you'd write:

    scope.define_elem::<MyElem>();
    scope.deprecate("my", "it's old");
  • The MaybeDeprecated type is kind of viral here. Would it make sense to instead pass a mutable warning sink to the field access? It could also potentially be a dyn trait that is implemented by () and Sink, maybe even Engine and Vm, so that we can ignore it by passing &mut () if we don't have a Sink. I'm not sure it's really better than what you did, but worth exploring.

@MDLC01
Copy link
Collaborator Author

MDLC01 commented Dec 20, 2024

Instead of having _deprecated variants for the define_* methods, how about having one mutable method?

I agree the accumulation of define_* method variants is unfortunate. I can try this, but it would probably be more annoying at the call site when we already have a MaybeDeprecated (e.g., at import.rs:71), because we would need to deconstruct it.

The MaybeDeprecated type is kind of viral here. Would it make sense to instead pass a mutable warning sink to the field access?

I am not convinced this would be better. The advantage of MaybeDeprecated is that it lets us chose if and when to emit the deprecation warning (by calling access or into_inner). It becomes viral in situations where we don't yet know if a warning should be emitted (e.g., when accessing a field on a value1). In other words, every function that currently returns a MaybeDeprecated would have to accept an additional sink argument; this sink argument would itself become similarly viral. This is a matter of personal preference, but returning a MaybeDeprecated feels cleaner to me.

Footnotes

  1. Value::field returns a result of MaybeDeprecated<Value>. In eval_field_call in call.rs, a warning is emitted in the case of a deprecated value, because this corresponds to the user explicitly accessing a deprecated value in code. In field_access_completions in complete.rs, a warning is never emitted because this is just an IDE feature, for which emitting a warning does not make sense.

@MDLC01 MDLC01 force-pushed the deprecated-constants branch from 2d9f0c3 to 42ec8b1 Compare December 28, 2024 10:41
@MDLC01 MDLC01 marked this pull request as ready for review December 28, 2024 10:41
@MDLC01
Copy link
Collaborator Author

MDLC01 commented Dec 29, 2024

Should I deprecate calc.inf as well? This was briefly mentioned in #4724 (comment).

@MDLC01
Copy link
Collaborator Author

MDLC01 commented Jan 23, 2025

Properly deprecating the methods that were deprecated in #5671 would likely require a new attribute for items in a #[scope] impl block. I will wait until the deprecation infrastructure is finalized to implement it (there are still some unanswered design questions above).

@laurmaedje laurmaedje mentioned this pull request Feb 3, 2025
@laurmaedje
Copy link
Member

I opened #5798 as an alternative, with the rationale for differing design decisions in the PR description.

@MDLC01
Copy link
Collaborator Author

MDLC01 commented Feb 3, 2025

Closing in favor of #5798, which is more lightweight and has some other advantages.

@MDLC01 MDLC01 closed this Feb 3, 2025
@MDLC01 MDLC01 deleted the deprecated-constants branch February 21, 2025 13:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants