julia - 制作宏以将函数标记为已弃用

问题描述

在我之前的问题中，我发现标准库（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件事在文档中有解释。
从不使用宏内部的变量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. 有趣的是，Tab-Completion 似乎不适用于这些低级数据结构及其字段。

走向我的宏

试图抄袭上述内容：

# 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. 但是，是否可以将宏默认应用到裸函数符号以弃用所有方法？

标签： juliametaprogrammingdeprecated

解决方案

我认为您想要实现的目标与实际目标不同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