README.org

DEFprecated - deprecate all the things!

Psst, chummer! Looking for some deprecation? You’ve come to the right place. Deprecate like never before, deprecate everything! Deprecate symbols, deprecate functions and macros, deprecate arities, deprecate programming languages, deprecate hardware and software, deprecate your enemies and friends, deprecate your loved ones, deprecate your dog, deprecate yourself for eating that donut, deprecate social institutions, deprecate social injustice, deprecate government and FRS, deprecate NSA, deprecate yourself again for deprecating everything, deprecate that feeling, go on deprecation spree!

Did you just say “deprecate your dog”?

No, I didn’t.

Can I deprecate this library?

Yes, you can, but then you will be responsible for writing a new one.

Just read these testimonies!

Use it or delete it. There is no deprecate. – Master Joda

We have a policy of releasing entire Java packages in which every single class, interface and method is deprecated right out of the box, starting at version 1.0. – Morris Baldwin, by Steve Yegge

I just do (:refer-clojure :exclude [defn defmacro]) and (:use defprecated.core). Deprecating stuff has never been easier. – Regular Joe

Man, you need help

No, wait, I got this. defprecated is a minimalistic library for marking functions, macros and global vars as deprecated. When the time comes and you realize that you made a bad API decision, mark the function as deprecated instead of removing it. You’ll get the best from two worlds: old users’ code won’t crash, but they will migrate to the new API over time.

Usage

Put this into your :depencencies:

Replace any def, defn or defmacro you want to deprecate with a corresponding macro from defprecated.core. For example:

(require '[defprecated.core :as depr])

(depr/defn foo "A useless function."
  [x y]
  (+ x y))

A few things will happen:

• Docstring will be updated to contain the deprecation warning.
• Same warning will be printed when the function is called for the first time.

You can change deprecation options by editing :deprecated metadata for that function/macro/var.

(depr/defn foo "A useless function."
  {:deprecated {:in "0.2.5"
                :use-instead bar
                :print-warning :always}}
  [x] (+ x x))

Here are the possible options:

• :in — specifies the version of the library/program when the function became deprecated.
• :use-instead — can be a string or a var name. Expands the warning message to contain the alternative function/macro to be used instead of the deprecated one. If var name is provided, its namespace will be also shown.
• :print-warning — can either be :always, :once and :never. The default is :once, which means warning will be printed only the first time the function is called (or the macro is expanded).
• :print-function — set a custom function for printing out warnings. By default they are printed to STDERR.

Deprecate specific arities

You can add ^:deprecated tag to argument vectors in a multi-arity function/macro.

(depr/defn baz
  ([x]
   (+ x x))
  (^:deprecated [x y]
   (+ x y))
  ([x y z]
   (+ x y z))
  (^:deprecated [x y z o]
   (+ x y)))

If a function/macro has at least one :deprecated arity, the following will happen:

• The functions itself will NOT be marked as deprecated.
• :forms metadata will contain only non-deprecated arities.
• Warning will be printed only when deprecated arities are called.

=> (baz 2 3)
WARNING: arities ([x y] [x y z o]) are deprecated, use one of ([x] [x y z]) instead.
5

License

Deprecate the licenses, this is in public domain.