Yesterday, Andy Lester opened an issue for vim-perl on github about adding an automated test suite. I’ve thought about doing something like this before, so last night got busy with prototyping a test harness.
What I’ve got so far (in my fork) is a test file that uses Text::VimColor to generate HTML and compare it against a reference HTML document to determine if the syntax file is doing its job. If a reference file can’t be found, it will create it and skip that test. Here’s what it looks like:
$ make test
prove -rv t
t/01_highlighting.t ..
ok 1 - Correct output for t_source/perl/basic.t
ok 2 # skip Created t_source/perl/advanced.t.html
ok 3 - Correct output for t_source/perl6/basic.t
1..3
ok
All tests successful.
In case of failure, it will use Test::Differences to show you what’s wrong, and write the incorrect output to disk for you to inspect:
$ vim syntax/perl6.vim # make a bad change
$ make test
prove -rv t
t/01_highlighting.t ..
ok 1 - Correct output for t_source/perl/basic.t
ok 2 - Correct output for t_source/perl/advanced.t
not ok 3 - Correct output for t_source/perl6/basic.t
# Failed test 'Correct output for t_source/perl6/basic.t'
# at t/01_highlighting.t line 77.
#
?output from Test::Differences showing the offending lines?
# You can inspect the incorrect output at t_source/perl6/basic.t_fail.html
1..3
# Looks like you failed 1 test of 3.
Dubious, test returned 1 (wstat 256, 0x100)
Failed 1/3 subtests
The only big downside to this is that 01_highlighting.t tests all the source files in one go. You currently can’t tell it to only test one specific file.
I’ve added Jonathan Scott Duff’s introduction to Perl 6 regexes to Perl6-Doc as perlreintro. In addition I put in a first draft of a perlobjintro. Neither of these correspond to names from the set of Perl 5 man pages, which is fitting since they are not directly based on them. So, Perl6-Doc now has 4 man pages, the aforementioned two as well as perlintro and perlsyn. I’ll be carefully adding to and polishing these in the near future. I’m hesitant to start on man pages relating to modules, IO, laziness/iterators, and other very important features, as the specs (and implementation) for those are still shifting heavily from month to month.
I’ve been thinking about using the Perl Table Index as initial source material for the magical syntax recognition feature, the implementation of which has remained elusive for a while. The current implementation is just a proof-of-concept with only a few terms as of yet. However, Damian Conway just published a significant update to Synopsis 26 on Perl documentation, focused on tying docs to code, so it might be time to figure out some Pod-ish source format for the terms to be stored in. Writing Pod is a breeze, so it should be easy to contribute new terms.
grok also needs more love. I’m not as happy as I’d like to be with some of its implementation details, most notably how it picks out functions from Synopses 29 and 32, using simple regexes (to be fair, this is exactly what good ol’ perldoc -f does). It should parse the Pod and pick out parts of the document tree instead, I think. There are also still a few visual differences between textual output of Pod 5 and Pod 6 that I have to address. Pod 5 textual output is pleasingly indented (gradually depending on the current heading level), which makes it very easy to follow, while Pod 6 is not.
As a sidenote, I believe I’ve found what was causing intermittent FAIL reports from CPAN testers. Some machines had a pretty old version of Pod::Simple which didn’t take well to subclassing. Another failure was caused by an old Pod::Parser (deprecated, but relied on by Pod::Xhtml) version which didn’t recognize =encoding directives. The relevant distributions now depend on newer versions of those troublesome modules.
I’m currently working on making grok index all X<> (and maybe C<>) tags in Pod documents. The user will then be able to look them up and see which docs contain the search term in question.
(more…)
As the title suggests, I reorganized the grok a bit, in addition to adding a few new features.
(more…)
This week I’ve been working on the perlintro document found in the pugs repository, as well as porting Perl 5’s perlsyn. These are the most “basic” man pages about the language, and should be ported first (especially since many of the more specific bits in Perl 6 are still in flux).
(more…)
I just uploaded grok 0.13 to PAUSE. It has the things I mentioned in my last post, plus some bug fixes.
(more…)
With Summer of Code’s mid-term evaluations coming up, some interesting things are about to happen to grok. I was contacted by Herbert Breunung, author of Perl6::Doc (formerly Perl6::Bible), which is a project that shares some of grok’s goals.
(more…)
The code is starting to take a more stable form. I’ve prepended an underscore to all private/internal subroutines and documented the rest. Perl authors wishing to use grok’s functionality will now have an easier time doing so.
(more…)
Some things have kept me very busy lately and I’m a bit behind on my GSoC schedule. I’m starting to catch up now, though.
(more…)
I officially started on my Google Summer of Code project (project details here) last weekend.
I’ve been tasked with writing a perldoc equivalent for Perl 6. I’ve decided to write it in Perl 5 for now, since it’s already got Perl6::Perldoc, which is a fast and feature-complete parser for the Perl 6 version of Pod (see specification), as well as lots of other useful CPAN modules which I won’t have to rewrite in Perl 6 (yet).
(more…)
