|
455 | 455 | end |
456 | 456 |
|
457 | 457 |
|
| 458 | +-- |
| 459 | +-- Mark a specific alias value of a field as deprecated. |
| 460 | +-- |
| 461 | +-- @param name |
| 462 | +-- The name of the field containing the alias. |
| 463 | +-- @param alias |
| 464 | +-- The alias or aliases to mark as deprecated. May be a string |
| 465 | +-- for a single alias or an array of multiple aliases. |
| 466 | +-- @param message |
| 467 | +-- A optional message providing more information, to be shown |
| 468 | +-- as part of the deprecation warning message. |
| 469 | +-- |
| 470 | + |
| 471 | + function api.deprecateAlias(name, alias, message) |
| 472 | + if type(alias) == "table" then |
| 473 | + for _, a in pairs(alias) do |
| 474 | + api.deprecateAlias(name, a, message) |
| 475 | + end |
| 476 | + else |
| 477 | + local field = p.fields[name] |
| 478 | + field.deprecatedaliases = field.deprecatedaliases or {} |
| 479 | + local actual = field.aliases[alias:lower()] |
| 480 | + if actual then |
| 481 | + field.deprecatedaliases[alias] = { |
| 482 | + message = message |
| 483 | + } |
| 484 | + end |
| 485 | + end |
| 486 | + end |
| 487 | + |
| 488 | + |
458 | 489 | -- |
459 | 490 | -- Control the handling of API deprecations. |
460 | 491 | -- |
|
648 | 679 | local canonical, result |
649 | 680 | local lowerValue = value:lower() |
650 | 681 |
|
| 682 | + if field.deprecatedaliases and field.deprecatedaliases[lowerValue] then |
| 683 | + local handler = field.deprecatedaliases[lowerValue] |
| 684 | + if handler.message and api._deprecations ~= "off" then |
| 685 | + local caller = filelineinfo(9) |
| 686 | + local key = field.name .. "_" .. value .. "_" .. caller |
| 687 | + p.warnOnce(key, "the %s alias %s has been deprecated and will be removed.\n %s\n @%s\n", field.name, lowerValue, handler.message, caller) |
| 688 | + if api._deprecations == "error" then |
| 689 | + return nil, "deprecation errors enabled" |
| 690 | + end |
| 691 | + end |
| 692 | + end |
| 693 | + |
651 | 694 | if field.aliases then |
652 | 695 | canonical = field.aliases[lowerValue] |
653 | 696 | end |
|
0 commit comments