[ruby-core:25496] [Bug #2054] Onigurma Isn't Documented

Issue #2054 has been updated by Run Paint Run Run.


>> + *  literally backslash-escape that: <tt>\\\\\\</tt>.
> Why 6 times?

I didn't know how else to persuade RDoc to render two consecutive literal backslashes in a fashion suitable for `ri` and HTML.

>> + *  * <tt>/\d/</tt> - A digit character (<tt>[0-9]</tt>)
>> + *  * <tt>/\D/</tt> - A non-digit character (<tt>[^0-9]</tt>)
> Add following:
>> *  * <tt>/\h/</tt> - A hexdigit character (<tt>[0-9a-fA-F]</tt>)
>> *  * <tt>/\H/</tt> - A non-hexdigit character (<tt>[^0-9a-fA-F]</tt>)

>> + *  * <tt>{n,}</tt> - n or more times
> Add *  * <tt>{,m}</tt> - m or less times

Done.

>> == Grouping

> (?: ..) should be introduced also in this chapter.

I can't introduce non-capturing parentheses until I've explained capturing, so I've merged the two sections and left the explanation where it is.

>> + *  Capture groups can be referred to by name when defined with the
>> + *  <tt>(?<name>)</tt> construct.

> Don't mention an alias (?'name'subexp) ?

It didn't seem worth it. The material is already dense, without describing alternative syntax which appears to have little merit of its own.

>> + *      /贈(?<pounds>\d+)\.(?<pence>\d+)/.match("贈3.67")
> Pound Sign (U+00A3) is non-ASCII.
> Dollar Sign (U+0024) is in ASCII (but Cent Sign is non-ASCII).

We need to re-think the ASCII restriction. Documenting a Unicode regular expression library without being able to use Unicode in the examples is somewhat limiting. See below for an alternative.

>> *  A regexp can be matched only against a string whose encoding is the
>> + *  same as, or a superset of, the regexp's encoding. If a match between

> The word "superset" is misleading.
>  In Ruby 1.9, this relation is only US-ASCII and other ASCII-compatible encodings.
> So "or regexp's encoding is US-ASCII and string's encoding is ASCII-compatible".

Programming Ruby uses the term in this context, and during other encoding discussions, which was why I'd adopted it. :-)

Changed to:

  A regexp can be matched against a string when they either share an encoding, or the regexp's encoding
  is  _US-ASCII_ and the string's encoding is ASCII-compatible.

I'm not keen on the phrasing, but hopefully it's more accurate.

>> + *  The <tt>Regexp#fixed_encoding?</tt> predicate indicates whether the regexp
> Needs encoding modifiers set FIXED_ENCODING.

I don't understand that part. Regexp::FIXED_ENCODING is a constant, so how can an encoding option "set" it? I think the current text makes clear that a non-ASCII encoding, i.e. one set by an encoding option, is "fixed". That is, the modifiers change the state to fixed, which the predicate queries. I'll play around with

> Don't mention following?

I didn't know I was writing a book. :-) It's already far more comprehensive that O'Reilly's Programming Ruby...

> * reluctant and possessive quantifier

I mentioned both of these under repetition. I used the more standard term of "lazy" for "reluctant".

> * subexp call \g<..>

This seemed particularly arcane; even Friedl doesn't mention it in his tome. ;-) I'll try and come up with an example use.

> * substitution by literarl regexp matching
>  /(?<foo>b\w+)/ =~ 'bar' #=> 0
>  foo #=> "bar"

Yes, I meant to mention that.

Given the scope of this tutorial, the character set limitations, the degree to which it's bloating re.c, and the way this text obscures the existing API documentation for Regexp, how about we move it to its own file? This could, presumably, either be included in re.c with RDoc's _include_ option, or, better, live separately from the API documentation yet still be accessible from `ri`. `ri Regexp` could display the API documentation and mention the existence of this document; `ri regexp` could display the current document. I can commit at least the rest of this week to writing some initial content, if necessary.
 
> If you can describe about  /(a|b+)*/ , it will be helpful.
> http://www.ruby-forum.com/topic/70726

Hmm... Constructing accurate, performant, and optimal regexps is a significant topic... I suppose I could add a "Top 10 Pitfalls" callout. 
----------------------------------------
http://redmine.ruby-lang.org/issues/show/2054

----------------------------------------
http://redmine.ruby-lang.org