As a newcomer, I'm often annoyed by Scala's documentation. I spend too much time
searching for info (StackOverflow, search engines). Sometimes, Scala's spartan
API doc is sufficient, but that's not often. I know I could always read the
source, but I'm too lazy!
I apologize for ranting. I know a documentation like Qt's isn't easy to build,
but I think it should be a priority for any language. I'm not qualified enough
to write definitive documentation, but I would be glad to contribute to a wiki.
When I see the many posts on SO and in blogs, I believe the community could
come up with a nice doc.
If you're interested in pratical situations that made me feel bad, here are a
few short cases. Feel free to blame me if I made mistakes.
I used some xml pattern matching, but soon discovered that it does not work with
attributes, so I dropped the whole lot. I got confirmation of this behaviour
from Daniel Spiewak's blog. It was not in the "authoritative reference" book,
nor in any user-friendly documentation I could find on the official site.
I use Jsoup to parse HTML. When I first tried to use a "map" on some iterator
returned by this java library, it failed miserably. I soon discovered that I
just had to add one line to fix this:
import scala.collection.JavaConversions._ // scala 2.8+
This info is not in the tutorials and manuals of scala-lang.org.
The official "Tour of Scala" still announces that "General RegExp patterns
[are] temporarily retracted from Scala". Anyway I needed regexps. The book was
not very detailed on this subject, so I had to rely on the API. It was painful.
Then I switched to Java's Pattern. I found it much easier to use. Probably
because it is well documented (I know very little Java).
A last example is parser combinators. They are indeed wonderful, but after a few
easy examples, I struggled with them until I could read by chance the excellent
PDF "Combinator Parsing in Scala" by Stephan Freund.
In a perfect world, I believe Scala's site would offer a general documentation,
in HTML, with a content similar to current books. The API would show for each
class a full description with perspective and comments. Each non-trivial method
would display at least some examples and "see also" links.
Regards
--
François
best regards
> Fran�ois
I'd like to contribute to the scala documentation -- what would be the best way
to do so? (how to submit scala-doc patches -- what kind of access is required?)
best regards
> François
My 2¢.
MK
http://github.com/michaelklishin
http://twitter.com/michaelklishin
Any chance of getting an English translation of these slides?
> ...
> --
> François
Randall Schulz
Sorry, I mixed 2 references. I meant to write "Combinator Parsing". It is in
English, and it seems to be a chapter of a book (written at the EPFL?).
http://lamp.epfl.ch/teaching/foundations_of_software/docs/combinator_parsing.pdf
--
François
I'm sensing that you're confusing two different uses of regular
expressions. The ones that are in abeyance are for pattern matching in
the sense of Scala's "match" construct, not mere character string
processing. The latter exists with a small but helpful Scala class,
Regex, built over the Java standard library's java.util.regex classes.
I've read again the page "A Tour of Scala: Regular Expression Patterns"
http://www.scala-lang.org/node/122
Now I think I understand what you mean. The "General RegExp patterns" are just
an extension of the "Right-ignoring sequence patterns" described in the first
paragraph. When I read it first, I thought they were totally different. The
first paragraph is about "patterns" on Seq[A] (obviously not a string regexp).
The second one writes about "regular expressions" on XML (looks very similar to
the usual string regexp, no ?). I think it is very easy to misunderstand this.
This is supposed to be a shiny page, showing the good sides of Scala to newbies
and curious programmers. I believe it is counter-productive as it is now. The
induced message "compatibility break with a feature removed" is another big
threat here.
About scala.util.Regex, I had a hard time to handle some simple tasks, like
getting a collection of the groups for all the matches of a pattern in a given
string. Something like ` push @a,$1 for /id=(\d+)/g ` in Perl.
--
François
The official "Tour of Scala" still announces that "General RegExp patterns
[are] temporarily retracted from Scala". Anyway I needed regexps. The book was
not very detailed on this subject, so I had to rely on the API. It was painful.
Then I switched to Java's Pattern. I found it much easier to use. Probably
because it is well documented (I know very little Java).
Not sure it has appeared in other thread, but there is at least two
books available online about Scala:
- Programming In Scala first edition : http://www.artima.com/pins1ed/
- Programming Scala : http://programming-scala.labs.oreilly.com/
They give a really good overall documentation on the langage.
Hope it helps,
--
Francois ARMAND
http://fanf42.blogspot.com
http://www.normation.com
About scala.util.Regex, I had a hard time to handle some simple tasks, like
getting a collection of the groups for all the matches of a pattern in a given
string. Something like ` push @a,$1 for /id=(\d+)/g ` in Perl.
scala> val r = """(?<=id=)(\d+)""".rr: scala.util.matching.Regex = (?<=id=)(\d+)
scala> val m = r.findAllIn("xxid=77xxxid=45fdwgr")m: scala.util.matching.Regex.MatchIterator = non-empty iteratorscala> m.foreach { println }7745
That's a nice trick, but it does not answer my needs.
I reckon it works on my simple Perl example, but it was a bit oversimplified.
As I wrote above, I want to capture the *groups*. Your trick is to make the
first group equal whole match. As soon as there are 2 groups, it fails.
Back to Perl: push @a,[$1,$2] while /id=(\d+):(\d+)/g
--
François
Thanks for this statement. I sounded too negative in my post. I should have
first written that Scala's official site has links to some very good
introductory books and manuals.
The problem is that as soon as one's need is not covered by these general books,
one has to rely on StackOverflow, blogs and the minimalistic documentation of
the API.
I know writing documentation is a tedious process. Many developers hate this.
So I believe scala-lang.org should have some sort of collaborative process
(wiki? dvcs?). It could begin by importing some known resources, if their
authors consent to this.
--
François Gannaz
but what about
val T = """id=(\d+):(\d+)""".r
input match {
case T(g1, g2) => println("group1 %s, group2 %s".format(g1,g2))
case _=> println("no match")
}
2011/7/1 François Gannaz <francoi...@gmail.com>:
Another way to use this regex is
scala> val s="""id=1:2
| id=3:4"""
s: java.lang.String =
id=1:2
id=3:4
scala> T.findAllIn(s).matchData.map(_.subgroups).toList
res3: List[List[String]] = List(List(1, 2), List(3, 4))
Hope that's helpful.
That's it! Thank you!
Had I know this was possible, I would not have bothered with Java's Pattern.
I first wrote a code like Stefan's, but this only finds the first match.
As I wanted to get all the groups for all the matches, I had to write a
tail-recursive function (heavy code for a simple need). Your solution is much
more elegant.
Thanks again, I'm now convinced to use Regex in the future
--
François Gannaz
I missed this comment... Yes, I know *exactly* how you feel. Some ways
of doing it:
val a = for {
matched <- """id=(\d+)""".r.findAllIn(source).matchData.toList
} yield matched.subgroups(0)
val a = for {
matched <- """id=(\d+)""".r.findAllIn(source).matchData.toList
} yield matched.group(1)
val a = for {
matched <- """id=(\d+)""".r.findAllIn(source).matchData.toList
groups <- matched.subgroups
} yield groups
val a = """id=(\d+)""".r.findAllIn(source).matchData.flatMap(_ subgroups).toList
// The following examples need this import
import scala.util.matching.Regex.Groups
val a = for {
matched <- """id=(\d+)""".r.findAllIn(source).matchData.toList
Groups(first, _ @ _*) = matched
} yield first
val a = for {
Groups(first) <- """id=(\d+)""".r.findAllIn(source).matchData.toList
} yield first
// If you have many subgroups, but only care about the first
val a = for {
Groups(first, _ @ _*) <- """id=(\d+)""".r.findAllIn(source).matchData.toList
} yield first
// The following example needs the pattern to be assigned to an identifier
val pattern = """id=(\d+)""".r
val a = for {
pattern(first) <- pattern.findAllIn(source).matchData.toList
} yield first
--
Daniel C. Sobral
I travel to the future all the time.
> As I wrote above, I want to capture the *groups*.
Well, then use the group method on the matches.
> Back to Perl: push @a,[$1,$2] while /id=(\d+):(\d+)/g
scala> """id=(\d+):(\d+)""".r.findAllIn("xxid=77:33xxxid=45:44fdwgr").matchData.toList map (md => (md.group(1), md.group(2)))
res4: List[(String, String)] = List((77,33), (45,44))
Yeah, perl has shorter oneliners.
- Florian.
--
#!/bin/sh -
set - `type -p $0` 'tr [a-m][n-z]RUXJAKBOZ [n-z][a-m]EH$W/@OBM' fu XUBZRA.fvt\
angher echo;while [ "$5" != "" ];do shift;done;$4 "gbhpu $3;fraqznvy sKunef.q\
r<$3&&frq -a -rc "`$4 "$0"|$1`">$3;rpub 'Jr ner Svt bs Obet.'"|$1|`$4 $2|$1`
As it happens, it has a wiki. The old one had a wiki too, with some
esoteric stuff mixed in with some basic stuff, but not in any way
comprehensive. And, then, there's colladoc, which is a way to submit
changes to Scaladoc itself. The tool was never integrated in any way
for these changes to be reliably accepted, however. And, then,t here's
a *fantastic* on-line resource for learning Scala, which is Simply
Scala, because it let you execute and *interact* with all the code it
presents.
Old wiki: http://scala.sygneca.com/
New wiki: https://wiki.scala-lang.org/
Colladoc: http://scala-webapps.epfl.ch/colladoc/
Colladoc project: http://collaborative-scaladoc.github.com/
Simply Scala: http://www.simplyscala.com/
So, here's the deal... there has been a wiki for many years, but it
hasn't been used or updated. There's colladoc to help with API docs
itself too. The question is: why this hasn't been enough?
Personally, I can think of a few things. The wiki, for one thing, is
not on scala-lang or epfl.ch. But, more importantly, it is not *the*
scala-lang! When you look at succesful wiki projects in other
languages, the wiki is not some link hidden somewhere. On PHP.Net, the
link to documentation is topmost, and the documentation *is* the wiki.
It is not the pattern everyone takes -- Ruby is also a huge collection
of links (mind you, Ruby is an old language that took a long time to
become popular *because its documentation sucked*).
But Scala... it's bureaucratic. Documentation is not a link (well, it
is too, but doesn't act like one), it is a menu under which there are
items and submenus. The items taken you to pages with links to other
places. And, then, there's the manuals, which are all PDF-only (and
not particularly searchable or linkable to because of that).
And, for all that, I, for one, didn't see a link to either wiki, to
colladoc, or to simply scala.
Honestly, this all gets me even more depressed. There's so much that's
within easy reach, some stuff that could incredibly exciting -- it is
a simple lack of *action*.
I don't blame the EPFL people. The task of turning scala-lang into a
site where documention is easy to find, to contribute to, and good in
quality is not a research task. Colladoc is research, putting it to
use is not.
*This* is the difference that a company backing makes. This is why
Java has good documentation. This is why I expect Ceylon to have good
documentation. I hope Typesafe can do something about this, but, to be
completely honest, I'm doubtful.