# ExPropriate

[![ version](](
[![GitHub: CI](](
[![License: MIT](](

ExPropriate is an Elixir library that allows you to decide whether or not a function is public at
compile time.

When would you want to do this?


There's an argument to be had that you should be testing your private functions through your public
interfaces, and I agree! But it's also true that often times projects grow more complicated than
you'd wish.

The aim of this library is to provide a way to be able to test your overly complicated private
functions without making changes in the design.

When push comes to shove, a questionably designed but well tested function is better than a
questionably designed and vaguely tested one.

## Installation

In `mix.exs`, add the ExPropriate dependency:

def deps do
    {:ex_propriate, "~> 0.1"}

Then run `mix deps.get` to install it.

$ mix deps.get

Now add this configuration in your test config, or any other env you wish your functions to be

# config/test.exs
config ExPropriate,
  enable: true

It may also be useful to configure your dev environment like this, so you can test expropriated
functions in console.

# config/dev.exs
config ExPropriate,
  enable: System.get_env("EXPROPRIATE_ENABLED") == "true"


## Usage

There are two ways in which you can use ExPropriate in a module:

- Module level granularity
- Function level granularity

**Module Level Granularity**:

This level will expropriate _all_ private functions in the module, giving them public access.

defmodule MyModule do
  use ExPropriate,
    expropriate_all: true

  defp my_private_function,
    do: :has_been_expropriated

# :has_been_expropriated

It's also worth mentioning that this granularity level is by design less "_intrusive_" than the
function one, so if you're having issues with the later, you can try using this one as a fallback.

**Function Level Granularity**:

This level will only expropriate functions that are tagged with the `@expropriate` attribute set
to `true`.

defmodule MyModule do
  use ExPropriate

  # Function becomes public
  @expropriate true
  defp expropriated_function,
    do: :am_expropriated

  # Functions with multiple bodies only need to be tagged on the first body
  @expropriate true
  defp divide_by(number) when is_integer(number) and number > 0,
    do: {:ok, div(100, number)}

  defp divide_by(_other),
    do: :error

  # Untagged functions remain private
  @expropriate false
  defp remains_private,
    do: :am_private

# :am_expropriated

# { :ok, 50 }
# :error

# (UndefinedFunctionError) function MyModule.remains_private/0 is undefined or private.

This graph may also help you visualize how ExPropriate decides when and which private functions to

graph TD

  config_enabled{{Enabled in Config?}}
  config_enabled -- false --> everything_private[All defp remain private]
  config_enabled -- true  --> expropriate_all{{use ExPropriate, expropriate_all: ?}}

  expropriate_all -- true  --> module_becomes_public[All defp in the Module become public]
  expropriate_all -- false --> module_remains_private[All defp in the Module remain private]
  expropriate_all -- nil   --> function_is_tagged{{"@expropriate true"}}

  function_is_tagged -- true  --> function_becomes_public[Tagged defp becomes public]
  function_is_tagged -- false --> function_remains_private[Tagged defp remains private]

## Limitations

Some libraries define their own versions of `def` and `defp`.

It's advised **against** using ExPropriate in modules that implement such libraries. If you want to
try regardless, please be aware that:

#### Only **Module Granularity** (`expropriate_all`) is (_loosely_) supported.

Function-level granularity explicitly defines functions with `Kernel.def/2` and `Kernel.defp/2`, so
even if things seem to work at first, you are probably loosing the functionality that you're seeking
from the other library.

#### If the library only overrides `def/2`

Libraries that override `Kernel.def/2` typically do so to enhance functionality. Since expropriating
a function basically makes it public, be wary of any unwanted side-effect that may occur.

Other than that, the setup should look something like this:

defmodule MyModule do
  use OtherLibrary

  use ExPropriate,
    expropriate_all: true

#### If the library also overrides `defp/2`


You really shouldn't use `ExPropriate` in that module, but if you absolutely must... \
You'll be trading off the functionality of that library's `defp/2` whenever you expropriate the
functions. You'll also be responsible of preventing the import of said library's `defp/2`, otherwise
you'll get compilation errors.

The setup would look something like this:

demfodule MyModule do
  use OtherLibrary

  if Application.compile_env(:ex_propriate, :enable) do
    import OtherLibrary.Macros, except: [defp: 1, defp: 2]

    use ExPropriate,
      expropriate_all: true do

## License

ExPropriate is released under the [MIT License](