Fix docs error for File.match? ** globbing pattern.

[zw963]

This really a small changes, so, i create a PR directly.

I just copy the docs of Ruby std-lib Dir.glob to here, because it more accurately.

Thank you.

[asterite]

Could you give an example of what this means? I know this came from Ruby, but I still don't understand it

[zw963]

Oops, Okay, maybe it should be describe better than ruby version.

let us use crystal-book project as root, i write a new 1.cr, with following content:

# 1. If we are use ** without followed by a /, or followed by others, e.g. followed by `.md`, it same as `*`

p Dir.glob("docs/**.md")
p Dir.glob("docs/*.md") # totally same as above.

# Dir.glob("docs/**.md") # => ["docs/platform_support.md", "docs/SUMMARY.md", "docs/governance.md", "docs/README.md"]
# Dir.glob("docs/*.md") # => ["docs/platform_support.md", "docs/SUMMARY.md", "docs/governance.md", "docs/README.md"]

# 2. But if ** followed by a `/`, it matches directories recursively. (behavior not same as `*`)

x =  Dir.glob("docs/**/*.md") # => ["docs/guides/ci/circleci.md", "docs/guides/ci/gh-actions.md", "docs/guides/ci/README.md",
# ...... a very long list which include all md file in any depth subdirectory ...
# "do "docs/database/connection.md", "docs/database/README.md", "docs/database/transactions.md"]
p x.size # => 143

y =  Dir.glob("docs/*/*.md") # ["docs/conventions/coding_style.md", "docs/database/README.md",
# .... a long list which include all md file in level 1 and level 2 subdirectory of docs/.
# , "docs/syntax_and_semantics/while.md", "docs/the_shards_command/README.md", "docs/using_the_compiler/README.md"]
p y.size # => 92

[asterite]

Thanks!

I'm thinking that **.md should actually produce a runtime error. It doesn't make sense to me if it's the same as *... 🤔

[zw963]

I'm thinking that **.md should actually produce a runtime error.

Yes, i think so, runtime error is better, in fact, i never use like Dir.glob("docs/**.md") before.

[straight-shoota]

No, we should not change established semantics. The glob patterns are not our own invention, they work the same way as in bash and multiple other shells and glob implementations.
ls docs/**.md in bash lists exactly the same paths as Dir.glob("docs/**.md").

This is completely valid though. ** only has a special meaning as a recursive match when it's followed by a path separator (/). But with out that, it's just consecutive wildcards, each matching a string of any length. That's completely valid syntax and has a clear meaning. It doesn't make a semantic difference to using a single wildcard. But that's not a reason to make it a syntax error. Especially when the same thing works in all other glob implementations.

[zw963]

I guess the first thought is, we don't like duplicate, if docs/*.md work same as docs/**.md, why we let user select?

talking about convention, i think the really big issue(for newcomer) is the " and ', when migrate one Ruby project to Crystal, probably the most annoy(boring) work is change ' to ". for least surprised, i still propose make double and single quotes function same in 2.0?, we can introduce ?A(ruby) or $'A'(bash) to present the Char type.

[zw963]

This documentation improvement has not been merged yet ...

[straight-shoota]

Yeah, it still needs a second approval from a Core Team member.

[zw963]

Yeah, it still needs a second approval from a Core Team member.

Hi, can i know for those delayed PR, because git HEAD is keeping moving, current old PR between newest master was forked, What is needs to be done before merging?

When this case happen, i usually do a rebase on my fork, and push -f instead, especially when there is a conflict with newest master, i guess this is not the expected way, what is the preferred way to do this for crystal-lang? e.g. for this PR.

[straight-shoota]

If there are conflicts with master, you should merge master into the PR branch and resolve the conflicts in that merge (see https://github.com/crystal-lang/crystal/blob/master/CONTRIBUTING.md#making-good-pull-requests).

But you don't need to do anything here. Master has progressed, but there's no conflict.

[zw963]

But you don't need to do anything here. Master has progressed, but there's no conflict.

@straight-shoota , one more question please, if the master is keep moving, which cause this old PR is not fast-forword, right?

if merge this branch into master after several months, which will cause a big merge graph, you know, like following screenshot.

This is acceptable, right?

[straight-shoota]

We'll do a squash merge, so the entire branch will be reduced to a single commit. It's not fast-forward of course, but the history is linear.