Help with a good API for a function

Questions / Help
, ,
1

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)

Sample:

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?

2

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

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

would be cleaner?

3

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
4

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.

5

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:

2 Likes
6

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.

7

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

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

8

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