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

README improvements #18

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

README improvements #18

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
31 changes: 22 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ end
</tr>
</table>

## Build Status
## Build status

![Run tests](https://github.com/jkrumbiegel/Chain.jl/workflows/Run%20tests/badge.svg)

Expand All @@ -88,11 +88,24 @@ This is very useful to inspect pipeline state during debugging, for example.
- The state of the pipeline can easily be checked with the `@aside` macro
- The `begin ... end` block marks very clearly where the macro is applied and works well with auto-indentation
- Because everything is just lines with separate expressions and not one huge function call, IDEs can show exactly in which line errors happened
- Pipe is a name defined by Base Julia which can lead to conflicts
- Pipe (as used in [Pipe.jl](https://github.com/oxinabox/Pipe.jl)) is a name defined by Base Julia, which can lead to conflicts

## Example
## Usage

An example with a DataFrame:
A simple example that adds one and squares all elements of a range:

```julia
julia> @chain 1:3 begin
_ .+ 1
Copy link
Owner

@jkrumbiegel jkrumbiegel Mar 7, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

In principle I'm not opposed to adding a simple non-DataFrame example. But _ .+ 1 and _ .^ 2 show the same syntax twice, which doesn't show off the range of options.

This for example shows a couple different things you can do:

@chain 1:10 begin
	  _ .^ 2
	  mod.(5)
	  filter(iseven, _)
	  sum
end

Maybe there is a more didactic example than this.

Copy link
Owner

Choose a reason for hiding this comment

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

What about this:

julia> names = ["ursula", "alice", "iris", "olga", "erica"]
5-element Vector{String}:
 "ursula"
 "alice"
 "iris"
 "olga"
 "erica"

julia> @chain names begin
    filter(contains("a"), _)
    @. uppercasefirst
    sort
    join(" and ")
    "$_ have an 'A' in their name."
end
"Alice and Erica and Olga and Ursula have an 'A' in their name."

Copy link
Contributor Author

Choose a reason for hiding this comment

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

That's a good point — but I believe it makes sense for the very first example to aim for a demonstration of the basic structure of a chained block, rather than showcasing the variety of possibilities. With that in mind, I would maybe start with the first example you offered above, and show the second one next. This way we can keep the advantages of both. WDYT?

_ .^ 2
end
3-element Array{Int64,1}:
4
9
16
```

An example with a [DataFrame](https://github.com/JuliaData/DataFrames.jl):

```julia
using DataFrames, Chain
Expand All @@ -107,7 +120,7 @@ result = @chain df begin
end
```

The pipeless block is equivalent to this:
The equivalent native Julia syntax for the above `@chain` block would be:

```julia
result = let
Expand All @@ -118,7 +131,7 @@ result = let
end
```

## Alternative one-argument syntax
### Alternative one-argument syntax

If your initial argument name is long and / or the chain's result is assigned to a long variable, it can look cleaner if the initial value is moved into the chain.
Here is such a long expression:
Expand All @@ -142,7 +155,7 @@ a_long_result_variable_name = @chain begin
end
```

## The `@aside` macro
### The `@aside` macro

For debugging, it's often useful to look at values in the middle of a pipeline.
You can use the `@aside` macro to mark expressions that should not pass on their result.
Expand Down Expand Up @@ -172,7 +185,7 @@ result = let
end
```

## Nested Chains
## Nested chains

The `@chain` macro replaces all underscores in the following block, unless it encounters another `@chain` macrocall.
In that case, the only underscore that is still replaced by the outer macro is the first argument of the inner `@chain`.
Expand All @@ -191,7 +204,7 @@ You can use this, for example, in combination with the `@aside` macro if you nee
end
```

## Rewriting Rules
## Rewriting rules

Here is a list of equivalent expressions, where `_` is replaced by `prev` and the new variable is `next`.
In reality, each new variable simply gets a new name via `gensym`, which is guaranteed not to conflict with anything else.
Expand Down