Ode to Camelia

»ö« 〜 Learning Raku 〜 »ö«

[ode-to-camelia]

Template::Mustache Module in Perl 6

November Yak Shaving

I started Template::Mustache as a quick little hack. I have a goal of reviving the November wiki, relying as much as possible on the growing modules.perl6.org ecosystem. I started working with Web::App::Ballet, and got distracted by the supported template options, none of which I'm fond of. I thought the Mustache format would be perfect, and decided to throw it together. It's logic-less, and should be pretty simple, right?

Actually, one of the great things about Mustache, which I was completely unaware of when I started, is its thorough spec test suite. It makes test-driven development a piece of cake when all the tests are already written! On the other hand, I was unwilling to implement a stripped-down version that wouldn't pass all the tests, so the final project became more ambitious that I'd originally planned. It's a good thing, because it has forced me to learn a bunch more about Perl 6, and I hope I can pass some of that on to you here. Yak shaving at its best.

Template::Mustache

Usage is best described in the mustache(5) man page, the Template::Mustache README, and the above-mentioned spec tests.

Here's a sample:

use Template::Mustache; my @people = { :name('James T. Kirk'), :title<captain> }, { :name('Wesley'), :title('Dread Pirate'), :emcee }, { :name('Dana Scully'), :title('Special Agent') }, ; my %data = event => 'Masters of the Universe Convention', :@people, ; my %partials = welcome => q:b{Welcome to the {{event}}! We’re pleased to have you here.\n}, ; Template::Mustache.render(q:to/EOF/, {{> welcome}} {{> roster}} Dinner at 7PM in the Grand Ballroom. Bring a chair! EOF %data, :from([%partials, './views']) ).say;

Combined with the rosters.mustache template, this produces:

Welcome to the Masters of the Universe Convention! We’re pleased to have you here. Our esteemed guests: - The honorable James T. Kirk (Captain) - The honorable Wesley (Dread Pirate) *TONIGHT’S EMCEE* - The honorable Dana Scully (Special Agent) Enjoy! Dinner at 7PM in the Grand Ballroom. Bring a chair!

While the module is mostly complete at this point, and passes all of the spec tests, there may yet be a change to the calling convention once I implement getting data directly from any objects, not just hashes. In particular, I think I may convert Template::Mustache itself into a role, which can easily be added to any object or class.

Lessons Learned

I won't get to them all in a single post, but I want to share a few lessons learned through this. The first one is, spend a bit of time with the rakudo Perl6 Grammar (and associated Actions). There are so many good tricks used there, and it helped me a lot to have concrete, full-scale examples of pretty much any Grammar features I could want to use.

At first a lot of it felt too complicated and I didn't understand what the bits were doing. But going back and forth between Synopsis 05, Grammar.pm and Actions.pm quickly cleared most of it up.

One feature that is new to me, which I really like, is the proto regex. It allows me to write separate, specific rules to match different kinds of template construct, but then treat them all similarly elsewhere in the code.

I think I am not quite understanding backtracking control sufficiently. I really don't like how the <linething> regex is defined and used, for example. It parses all the way through it's sub-thing, and then if it finds a non-whitespace it fails, returns to where linething started, and will re-parse as a normal thing. I haven't traced it, but I think this is double-parsing every {{foo}} thing that starts a line! Clearly there must be a better way, but I haven't thought of it yet. (Other than doing .lines() on the template at the beginning and parsing one line at a time, but I want to avoid that if I can.) Despite this, it works, and is fast enough for now – thanks, Rakudo! Caching will help (not yet implemented), too, for long-running processes.

Documentation

I decided to not shave another yak by writing Pod::To::Markdown.pm, so I generate the docs as plain text. It's a little sloppy, and a little boring, but it gets the job done. It seems that much of the Pod handling is incomplete, so this is an area where someone relatively new could come in and make some good improvements. I'd actually like to see Pod::To::Text generate Markdown (or RsT, asciidoc, or whatever) directly. Markdown is probably the simplest and most like plain text. Why create an ad-hoc write-only format instead of using something general?

Well, that's all for now, I hope this has been interesting. Let me know if there's anything you'd like to know more about in my next post.

[ode-to-camelia]

Interactive Fiction in Perl 6

### Plagiarism in the Name of Education I enjoyed following Carl Mäsak's [adventure in blogging](http://strangelyconsistent.org/) as he built an interactive fiction game in Perl 6. He did it two years in a row, and the implementation (and associated blogs) are quite different in the two versions. It made me want to try my hand at implementing the game, titled _Crypt_, to play around with Perl 6 and some ideas about the game engine. I started writing it, and shared the code on the Perl 6 IRC channel (#perl6 on freenode.net), and Carl encouraged me to blog about my experience. I can't say no, since I'm leeching off his idea in the first place. ### Jumping In So there's a chunk of code already there to talk about. The code can be found at [my p6-if repository](http://github.com/softmoth/p6-if) on Github. Feel free to fork it there and play along. I especially liked Mäsak's idea of an event-driven game, so that's where I started my implementation. The [`IF::Events`][events] class provides a central event stream that every other part of the system shares. I use it as a singleton, but don't bother to enforce that anywhere. Events are created by the `.emit()` method on the stream. The `.listen()` method registers event listeners. [events]: https://github.com/softmoth/p6-if/blob/master/lib/IF/Events.pm Example code ### Implementing Events I think most all of this is pretty straightforward Perl. I'm not using any meta-object programming, introspection, etc. Perl has had first-class subs for a long time, and they're quite familiar here. But I love how consistent Perl 6 blocks are. An `if` block can take arguments, either as a _pointy sub_ (our version of the functional lambda), or implicitly with the `^` twigil. Example code I first implemented `emit()`to just call the listeners for the event directly. But that doesn't work really well when listeners themselves emit events—the new event hijacks the currently running event. To fix this, I use the @.log attribute that tracks all events that have been emitted anyways; keep a pointer to the currently firing event, and when that one's done, move on to the events later in the queue. Along with this is a trick to fire a fake EOF event when the event queue is empty. In the interactive fiction context, hooks on EOF can prompt for the next command, run `tick` listeners for actions that happen before every prompt, etc. I'm pretty happy with the basic event system. It's the first time I've written code like this, and it is fun to kick off the whole game by just emitting a 'begin' event, and the rest of the whole game is just reacting to that. ### Things that I Learned the Hard Way #### Object Initialization Working with objects is a real pleasure in Perl 6. Classes can be `my` (lexical scope) if I want a little somethin' even just inside an `if` block, for example. There are a few gotchas that I didn't easily understand, though. First was just getting my mind around `new`, `BUILD`, and `bless`, and how those interact during inheritance. I'll have to write a little post on that, but I think understanding the following sentence [from Synopsis 12][S12] is the best way to clear it up: [S12]: http://perlcabal.org/syn/S12.html#Construction_and_Initialization > Other than the candidate object and any autovivifying type objects, all arguments to `bless` must be named arguments, not positional. > Hence, **the main purpose of custom constructors is to turn positional arguments into named arguments for `bless`**. Usually it's best to just write a `submethod BUILD` and use the default `new` inherited from `Mu`. Public attributes will automatically be initialized from matching named parameters to BUILD. Private attributes (with the `!` twigil) will not be, you'll have to write your own `BUILD` submethod to do that. #### Implicit Named-parameter Slurpy on All Methods Another gotcha for me was learning that methods always allow any named parameters, _with no warning for unused parameters_. So if you misspell a named parameter to a method, it'll likely go unnoticed and be treated as if you hadn't specified it at all. The reason for this is to enable `callnext` and so forth to work along the inheritance chain. That's how I understand it, anyways. A common example is for submethod BUILD, which is called for any roles and classes that an object composes, all from a single constructor call. One BUILD method may care about a `:foo` param, and another may not. Each one binds whatever named parameters it wants. Everything else goes into the implicit `*%_` named slurpy parameter. I can inspect the contents of `%_`, and die with an exception if I don't like what I see there. But the language doesn't provide any checks or tools for doing that consistently. It's too easy to misspell a parameter name and not notice it, and that makes me sad. #### Pair Literals versus Named Parameters A final related gotcha is the syntax and behavior for passing named parameters versus pair literals. In list context, such as assignment to an array or hash variable, all of the following are equivalent, and specify three Pair literals: Example code When passed into a method or routine, though, the first one is not like the others. The quoted key and fat arrow syntax makes it a Pair literal, even in the Capture of the routine call. But the other two forms are named-parameters. So: Example code I've done my best to write tests first, although it's very hard. I have probably over-engineered this already, and in some places it feels too heavy and overwrought. I am pretty happy with the tests, though, and they are providing a parallel use case for all the code, so that once the tests are written, it is trivial to get the actual Crypt game working with the new functionality. I think the testing code deserves its own blog post, so I'll tie this one up here. So far, I'm pleased in following Mäsak's lead on using events as a core feature of the design.