Help with a good API for a function

Hi all,
I am struggling with an API for very important function in my library, maybe someone will find a better idea than mine.

Background: there is a function poke, coming with arity of 2, 3 or 4, specs are:

@spec poke(Phoenix.Socket.t(), Keyword.t()) :: result
def poke(socket, assigns)
@spec poke(Phoenix.Socket.t(), String.t(), Keyword.t()) :: result
def poke(socket, partial, assigns)

@spec poke(Phoenix.Socket.t(), atom, String.t(), Keyword.t()) :: result
def poke(socket, view, partial, assigns)


poke socket, assign1: "something", assign2: 42

I need to add an optional option, also the keyword list (although so far it will be only one option, :using_assigs). I could just use one key from the assigns list for this, so user would mix the assigns and options:

poke socket, assign1: "something", assign2: 42, using_assigns: [...]

Because assigns keyword list key are Phoenix template assigns, I could even prevent having using_assign by user (I compile the template and may raise when some uses this assign).

This would do a trick, but I am having the impression that it is not very idiomatic. Is there the cleaner way to solve this, without changing the existing API?

I am still struggling with this. Maybe the macro, like:

using assigns: [...], other_option: 42 do
   poke socket, assign1: "something", assign2: 42

would be cleaner?

I would honestly just put the assign/user arguments and the ‘optional’ argument into 2 different lists. I’m not a fan of the ‘hidden’ list that Elixir makes by default for trailing keyword arguments syntax and prefer it explicit, but personally using elixir’s syntax I’d prefer the user assigns to be in a list that is not at the end, and the optional arguments being at the end. User data that is in list format should always be represented as being a list, no surprises.

1 Like

The issue is I can’t just do it. This function has versions with arity of 2, 3 and 4. So I just can’t put options \\ [] at the end, as I would normally do.

The 2 and 3 arity versions seem like excellent candidates to me to just become some of those ‘optional arguments’ though. :slight_smile:

poke(socket, assigns, [view: view, partial: partial | other_options]) :slight_smile:


Yep, I’ve been thinking about this.
But… (there is always a “but”) I really like the API of those functions, and how they fit the render conn, view, template of Phoenix. For me it is just natural.

Heh, well they really are optional arguments though? ^.^

Could just use a different name for one or more of them too.

Yep, they are optional. And yes, I will probably use them. I am lucky enough I compile the template before, so if some uses my name of options as the assign name, I can just refuse to compile it.

Still, I am not very happy with this one :wink: but it is probably the cleanest way. Thanks a lot!

1 Like