defprecated

defprecated copied to clipboard

[[https://travis-ci.org/alexander-yakushev/defprecated/][https://travis-ci.org/alexander-yakushev/defprecated.svg?branch=master]] [[https://coveralls.io/r/alexander-yakushev/defprecated?branch%3Dmaster][https://coveralls.io/repos/alexander-yakushev/defprecated/badge.svg?branch=master]]

• 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! #+BEGIN_QUOTE Use it or delete it. There is no deprecate. -- Master Joda #+END_QUOTE

  #+BEGIN_QUOTE 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 [[http://steve-yegge.blogspot.no/2010/07/wikileaks-to-leak-5000-open-source-java.html][Steve Yegge]] #+END_QUOTE

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

** 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=:

[[https://clojars.org/defprecated][https://clojars.org/defprecated/latest-version.svg]]

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

#+BEGIN_SRC clojure (require '[defprecated.core :as depr])

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

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.

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

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.

#+BEGIN_SRC clojure

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

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.

#+BEGIN_SRC clojure

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

** License

Deprecate the licenses, this is in public domain. [[http://creativecommons.org/publicdomain/zero/1.0/][http://i.creativecommons.org/p/zero/1.0/80x15.png]]