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.

Sign up for GitHub

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

Add docs and tests for as-> macro #1141

Merged
merged 5 commits into from
Nov 3, 2016
Merged

Add docs and tests for as-> macro #1141

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
25843f5
Add docs and tests for as-> macro
tuturto Oct 25, 2016
5ab4649
Fix typo in as-> docstring
tuturto Oct 25, 2016
4411f10
Update docs based on review
tuturto Oct 25, 2016
3bf0184
Fix typo in as-> documentation
tuturto Oct 27, 2016
ffd28fa
Add better examples for as->
tuturto Oct 29, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions docs/language/api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,6 +179,59 @@ other case, the first false value will be returned. Example usage:
False


as->
----

.. versionadded:: 0.12.0

Expands to sequence of assignments to the provided name, starting with head.
The previous result is thus available in the subsequent form. Returns the final
result, and leaves the name bound to it in the local scope. This behaves much
like the other threading macros, but requires you to specify the threading
point per form via the name instead of always the first or last arument.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

...this is kind of confusing. I mean, I'm guessing that there will likely never be a "simple" explanation for something like this. I think maybe at minimum the example should use something more descriptive than x; maybe assigned_name?

Copy link
Contributor Author

@tuturto tuturto Oct 25, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

true, assigned-name is much better. I'll try to think better explanation, but currently I'm drawing a blank.

Copy link
Member

@gilch gilch Oct 27, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I disagree that assigned-name is better. Perhaps you could use it in the first example just to point out which argument is which, but certainly not for all of them. The whole point of as-> is an alternative to -> and ->>, but where the insertion point can be anywhere in the list, instead of the first or last argument only. For deeply nested calls, this name may have to be repeated many times. Therefore, idiomatic usage is with a very short name, perhaps one or two letters. (This is not a problem for -> and ->> where the point is implied by the position.)

Perhaps the documentation would be clearer if you demonstrated how to accomplish a -> using as->. You can also look at Clojure's community documentation for clarification.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of assigned-name I could also us it as it's short and generic enough. I'll try to come up with a better examples still, that would highlight usage of as-> better (as now the example could be easily rewritten with ->).


.. code-block:: clj

;; create data for our cuttlefish database

=> (setv data [{:name "hooded cuttlefish"
... :classification {:subgenus "Acanthosepion"
... :species "Sepia prashadi"}
... :discovered {:year 1936
... :name "Ronald Winckworth"}}
... {:name "slender cuttlefish"
... :classification {:subgenus "Doratosepion"
... :species "Sepia braggi"}
... :discovered {:year 1907
... :name "Sir Joseph Cooke Verco"}}])

;; retrieve name of first entry
=> (as-> (first data) x
... (:name x))
'hooded cuttlefish'

;; retrieve species of first entry
=> (as-> (first data) x
... (:classification x)
... (:species x))
'Sepia prashadi'

;; find out who discovered slender cuttlefish
=> (as-> (filter (fn [entry] (= (:name entry)
... "slender cuttlefish")) data) x
... (first x)
... (:discovered x)
... (:name x))
'Sir Joseph Cooke Verco'

.. note::

In these examples, REPL will report a tupple as result:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tuple? (Also, missing the before REPL.)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good catch, tuple is one of those words that I consistently misspell.

('Sepia prashadi', 'Sepia prashadi'), but the actual value returned is just
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe this should be surrounded by double-backticks for formatting? The sentence could also be worded a bit differently, like:

In these examples, the REPL will report a tuple (e.g. `('Sepia prashadi', 'Sepia prashadi')`) as the result, but only a single value is actually returned.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I'll update this

a single value 'Sepia prashadi'. Tuples are omitted from the examples in
sake of preserving space.


assert
------

Expand Down
2 changes: 1 addition & 1 deletion hy/core/macros.hy
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
The previous result is thus available in the subsequent form. Returns the
final result, and leaves the name bound to it in the local scope. This behaves
much like the other threading macros, but requires you to specify the threading
point per form via the name instead of always the first or last arument."
point per form via the name instead of always the first or last argument."
`(do (setv
~name ~head
~@(interleave (repeat name) rest))
Expand Down
23 changes: 23 additions & 0 deletions tests/native_tests/language.hy
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -588,6 +588,29 @@
["X" "B" "C" "D"])))


(defn test-as-threading []
"NATIVE: test as threading macro"
(setv data [{:name "hooded cuttlefish"
:classification {:subgenus "Acanthosepion"
:species "Sepia prashadi"}
:discovered {:year 1936
:name "Ronald Winckworth"}}
{:name "slender cuttlefish"
:classification {:subgenus "Doratosepion"
:species "Sepia braggi"}
:discovered {:year 1907
:name "Sir Joseph Cooke Verco"}}])
(assert (= (as-> (first data) x
(:name x))
"hooded cuttlefish"))
(assert (= (as-> (filter (fn [entry] (= (:name entry)
"slender cuttlefish")) data) x
(first x)
(:discovered x)
(:name x))
"Sir Joseph Cooke Verco")))


(defn test-assoc []
"NATIVE: test assoc"
(setv vals {"one" "two"})
Expand Down