制作宏以将功能标记为已弃用

Question

在我之前的中，我发现标准库 (Julia v1.5) 宏 @deprecate 用于替换其他函数。

我想制作一个宏mark_deprecated，它在应用到函数时具有以下效果：

调用目标函数时打印可自定义的弃用警告（如果可能，仅在第一次调用时）。
修改函数的文档（可查看为 julia>? function_name）以也包含弃用警告。

当然，以后可能会包括许多其他方便的选项，例如指定替换函数的能力，产生错误而不是警告的选项等。

我主要是作为 Julia 元编程 的练习来做这件事的，到目前为止我在这方面的经验为零（有点担心这作为第一个任务可能太难了）。

试图理解@deprecate

作为第一步，我查看了当前的标准库 @deprecate 宏。它是这样的：

# julia v1.5
# quoted from deprecated.jl, included by Base.jl

macro deprecate(old, new, ex=true)
    meta = Expr(:meta, :noinline)
    if isa(old, Symbol)
        oldname = Expr(:quote, old)
        newname = Expr(:quote, new)
        Expr(:toplevel,
            ex ? Expr(:export, esc(old)) : nothing,
            :(function $(esc(old))(args...)
                  $meta
                  depwarn($"`$old` is deprecated, use `$new` instead.", Core.Typeof($(esc(old))).name.mt.name)
                  $(esc(new))(args...)
              end))
    elseif isa(old, Expr) && (old.head === :call || old.head === :where)
        remove_linenums!(new)
        oldcall = sprint(show_unquoted, old)
        newcall = sprint(show_unquoted, new)
        # if old.head is a :where, step down one level to the :call to avoid code duplication below
        callexpr = old.head === :call ? old : old.args[1]
        if callexpr.head === :call
            if isa(callexpr.args[1], Symbol)
                oldsym = callexpr.args[1]::Symbol
            elseif isa(callexpr.args[1], Expr) && callexpr.args[1].head === :curly
                oldsym = callexpr.args[1].args[1]::Symbol
            else
                error("invalid usage of @deprecate")
            end
        else
            error("invalid usage of @deprecate")
        end
        Expr(:toplevel,
            ex ? Expr(:export, esc(oldsym)) : nothing,
            :($(esc(old)) = begin
                  $meta
                  depwarn($"`$oldcall` is deprecated, use `$newcall` instead.", Core.Typeof($(esc(oldsym))).name.mt.name)
                  $(esc(new))
              end))
    else
        error("invalid usage of @deprecate")
    end
end

我试图理解这个东西（如果你理解宏就不需要阅读）：

:meta 的事情在 documentation 中有解释。
宏中的变量oldname和newname从不使用。我认为这是由于开发人员的疏忽（与尽管未使用变量但具有一些不明显影响的声明相反）。我删除它们。
我不确定如何处理 a(...) where B 表达式（这样的表达式进入顶层 elseif 块）。现在不用担心那部分。似乎 where 表达式只是被剥离了。与表达式中的 :curly 括号相同。似乎在任何情况下函数符号（oldsym）都是从表达式（第一个参数）中提取的。
我不明白 Base.show_unquoted 到底是做什么的。似乎它只是为了输出而将表达式“打印”到字符串中，所以我不用担心细节。
宏的主要内容当然是返回的Expr。它断言它是在顶级评估的。我不关心导出的东西。
我不知道 Core.Typeof($(esc(oldsym))).name.mt.name 是什么。它似乎是函数的实际 Symbol （而不是包含符号的字符串）。 Core.Typeof 似乎与 typeof 相同。您可以执行 typeof(some_function).name.mt.name 并从 mt::Core.MethodTable 中取出符号。有趣的是，制表符完成似乎不适用于这些低级数据结构及其字段。

朝向我的微距

试图抄袭以上内容：

# julia v1.5
module MarkDeprecated

using Markdown
import Base.show_unquoted, Base.remove_linenums!


"""
    @mark_deprecated old msg 
Mark method `old` as deprecated. 
Print given `msg` on method call and prepend `msg` to the method's documentation.
        MACRO IS UNFINISHED AND NOT WORKING!!!!!
"""
macro mark_deprecated(old, msg="Default deprecation warning.", new=:())
    meta = Expr(:meta, :noinline)
    if isa(old, Symbol)
        # if called with only function symbol, e.g. f, declare method f(args...)
        Expr(:toplevel,
            :(
                @doc(  # This syntax is riddiculous, right?!?
                    "$(Markdown.MD($"`$old` is deprecated, use `$new` instead.", 
                                @doc($(esc(old)))))",
                    function $(esc(old))(args...)
                    $meta
                    warn_deprecated($"`$old` is deprecated, use `$new` instead.", 
                            Core.Typeof($(esc(old))).name.mt.name)
                    $(esc(new))(args...)
                    end
                )
            )
        )
    elseif isa(old, Expr) && (old.head === :call || old.head === :where)
        # if called with a "call", e.g. f(a::Int), or with where, e.g. f(a:A) where A <: Int,
        # try to redeclare that method
        error("not implemented yet.")
        remove_linenums!(new)
        # if old.head is a :where, step down one level to the :call to avoid code duplication below
        callexpr = old.head === :call ? old : old.args[1]
        if callexpr.head === :call
            if isa(callexpr.args[1], Symbol)
                oldsym = callexpr.args[1]::Symbol
            elseif isa(callexpr.args[1], Expr) && callexpr.args[1].head === :curly
                oldsym = callexpr.args[1].args[1]::Symbol
            else
                error("invalid usage of @mark_deprecated")
            end
        else
            error("invalid usage of @mark_deprecated")
        end
        Expr(:toplevel,
            :($(esc(old)) = begin
            $meta
            warn_deprecated($"`$oldcall` is deprecated, use `$newcall` instead.", 
                    Core.Typeof($(esc(oldsym))).name.mt.name)
            $(esc(old)) # TODO: this replaces the deprecated function!!!
        end))
    else
        error("invalid usage of @mark_deprecated")
    end
end


function warn_deprecated(msg, funcsym)
    @warn """
            Warning! Using deprecated symbol $funcsym.
            $msg
            """
end

end # Module MarkDeprecated

用于测试：

module Testing

import ..MarkDeprecated  # (if in the same file)

a(x) = "Old behavior"
MarkDeprecated.@mark_deprecated a "Message" print

a("New behavior?")

end

问题

到目前为止，我没有做任何我想做的两件事：

当调用者没有导入我用来连接文档字符串的 Markdown 时，我该如何处理？（编辑：显然这不是问题？出于某种原因，尽管模块 Markdown 未在 Testing 模块中导入，但修改似乎有效。不过我不完全理解为什么。很难遵循宏生成代码的每个部分执行的位置...)
如何真正避免替换函数？从内部调用它会创建一个无限循环。我基本上需要一个 Python 风格的装饰器？也许这样做的方法是只允许将 @mark_deprecated 添加到实际的函数定义中？（这样的宏实际上是我期望在标准库中找到的，并且在我掉进这个兔子洞之前就使用了）
宏（对 @deprecate 也是如此）不会影响我示例中的方法 a(x)，因为它只创建了一个具有较低优先级的签名 a(args...) 的方法对于一个参数调用，当仅在函数符号上调用宏时。虽然对我来说并不明显，但这似乎是 @deprecate 所希望的行为。但是，是否可以默认将宏应用到裸函数符号以弃用 all 方法？

Answer 1

我认为您想要实现的目标与 Base.@deprecate 实现的目标不同。如果我理解正确的话：

您不希望宏为已弃用的方法创建定义；您想注释手写定义
您想修改文档字符串，@deprecate 不

并且由于您将此作为学习元编程的练习，也许您可以尝试逐步编写自己的宏，而不是了解 Base.@deprecate 的工作原理并尝试对其进行调整。

关于您的具体问题：

1.调用方没有导入Markdown怎么处理？

也许以下示例有助于解释事情的运作方式：

module MyModule

# Markdown.MD, Markdown.Paragraph and msg are only available from this module
import Markdown
msg(name) = "Hello $name"

macro greet(name)
    quote
        # function names (e.g. Markdown.MD or msg) are interpolated
        # => evaluated at macro expansion time in the scope of the macro itself
        # => refer to functions available from within the module
        $(Markdown.MD)($(Markdown.Paragraph)($msg($name)))

        # (But these functions are not called at macro expansion time)
    end
end
end

请特别查看 msg 如何正确引用 Main.MyModule.msg，这就是您必须从“外部”上下文中调用它的方式：

julia> @macroexpand MyModule.@greet "John"
quote
    #= REPL[8]:8 =#
    (Markdown.MD)((Markdown.Paragraph)((Main.MyModule.msg)("John")))
end

julia> MyModule.@greet "John"
  Hello John

2。也许这样做的方法是只允许将 @mark_deprecated 添加到实际函数定义中？

是的，那是我会做的。

3。是否可以默认将宏应用到裸函数符号以弃用所有方法？

我想在技术上可以弃用给定函数的所有方法......或者至少在弃用代码运行时存在的所有方法。但是之后定义的方法呢？我个人不会那样做，只标记方法定义。

也许像这样的东西可以作为一个更复杂的宏的起点来精确地做你想做的事情：

module MarkDeprecate
using Markdown
using MacroTools

function mark_docstring(docstring, message)
    push!(docstring,
          Markdown.Paragraph("Warning: this method is deprecated! $message"))
    docstring
end

function warn_if_necessary(message)
    @warn "This method is deprecated! $message"
end

macro mark_deprecate(msg, expr)
    fundef = splitdef(expr)
    prototype = :($(fundef[:name])($(fundef[:args]...);
                                   $(fundef[:kwargs]...)) where {$(fundef[:whereparams]...)})

    fundef[:body] = quote
        $warn_if_necessary($msg)
        $(fundef[:body])
    end

    quote
        Base.@__doc__ $(esc(MacroTools.combinedef(fundef)))
        Base.@doc $mark_docstring(@doc($prototype), $msg) $prototype
    end
end
end

julia> """
           bar(x::Number)
       
       some help
       """
       MarkDeprecate.@mark_deprecate "Use foo instead" function bar(x::Number)
           42
       end
bar

julia> """
           bar(s::String)
       
       This one is not deprecated
       """
       bar(s::String) = "not deprecated"
bar

julia> methods(bar)
# 2 methods for generic function "bar":
[1] bar(s::String) in Main at REPL[4]:6
[2] bar(x::Number) in Main at REPL[1]:23

julia> @doc(bar)
  bar(x::Number)

  some help

  Warning: this method is deprecated! Use foo instead

  bar(s::String)

  This one is not deprecated

julia> bar("hello")
"not deprecated"

julia> bar(5)
┌ Warning: This method is deprecated! Use foo instead
└ @ Main.MarkDeprecate REPL[1]:12
42

制作宏以将功能标记为已弃用

Making a macro to mark functions as deprecated

metaprogramming

deprecated

julia

试图理解@deprecate

朝向我的微距

用于测试：

问题