Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Better &optional, &rest, &kwonly, and &kwargs docs. #1722

Closed
Quelklef opened this issue Jan 11, 2019 · 7 comments
Closed

Better &optional, &rest, &kwonly, and &kwargs docs. #1722

Quelklef opened this issue Jan 11, 2019 · 7 comments

Comments

@Quelklef
Copy link
Contributor

The documentation for these four constructs is, in my opinion, lacking. I got tripped up not realizing that &optional affected not only the next argument but also all those afterwards.

Undocumented bits include:

  • That &optional affects all succeeding arguments
  • Can &rest be used with &optional?
  • That &kwonly affects all succeeding arguments (I assume, since this is how it works in Python)
  • Can an argument come after a &kwargs argument?
  • More stuff that I haven't thought of.

The interactions between these things is not particularly simple and, though understandable after a bit, can be difficult for a beginner (in Python and Hy or in Hy but not Python, like me). Further, the error message (at least for the &optional interaction) is not particularly enlightening, so it's hard to figure out what's going wrong beyond just trial&error.

@Kodiologist
Copy link
Member

Recapitulating the fine details of Python's argument handling is not a good idea—we should link to the relevant parts of the Python language reference instead—but there are definitely some outright errors and omissions in the current descriptions, such as the implication that &optional affects a single parameter.

@Quelklef
Copy link
Contributor Author

Makes sense.

To provide a little more insight, I'll say that my understanding after reading the docs was as follows:

  1. All optional arguments must be marked individually
  2. If an optional argument defaults to None, use &optional.
  3. If an optional argument has a default provided, simply use a pair [arg default] without &optional.

An example case like the following:

(defn long-fun [arg1 arg2 &optional arg3 [arg4 with-default] arg5 arg6 [with-default]]
    body)

Would help greatly.

@refi64
Copy link
Contributor

refi64 commented Jan 11, 2019

Now that I think about it, should we really have &optional? It seems a bit awkward given how defaults work otherwise...maybe just allow someone to omit the default but still use inner brackets to imply a default of None?

(Also hey look, I'm not dead.)

@Kodiologist
Copy link
Member

That's not a bad idea. I think the status quo is just because that's how Lisps have traditionally specified optional parameters.

@gilch
Copy link
Member

gilch commented Jan 12, 2019

I don't particularly like the status quo here, and have mulled over alternatives. #1411

Ideally, I'd like Clojure-style destructuring to work in the lambda lists. This may be incompatible with just using brackets instead of &optional

@Quelklef
Copy link
Contributor Author

On the thread of more concise arguments, thoughts on not having &kwonly and just having all keyword-only arguments be written as a keyword with :?

@Quelklef
Copy link
Contributor Author

Quelklef commented Jan 18, 2019

So e.g.

(defn print [&rest values &kwonly end] ...)

is written instead as

(defn print [&rest values :end] ...)

I would be against this in Common Lisp, because "keywords" are symbols, by Hy treats keywords differently anyway.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants