benn has asked for the wisdom of the Perl Monks concerning the following question:

Esteemed brethren,

I'm in the middle of writing a Parse::RecDescent module to handle ABC music files - reading them in, converting to other formats etc. The question is, how far should I go in providing 'helper' functions?

For instance, a 'convert-to-MIDI' function is obviously useful, but should this be "$tune->write_midi_file($filename)" or "@mididata = $tune->get_as_midi()", or both?

It goes as far as inputs too. ABC files can contain multiple tunes, comments etc. - it took a long time to decide between throwing a complete file at P::RD, and splitting the file up beforehand and just passing individual tunes to the parser. (I opted for the latter, but only because it seemd easier at the time - or I was still scared of P::RD :)).

Again though, should I bother providing a complete "my @tunes = read_file()" routine (thus duplicating the ubiquitous while(<FILE>) or should I just leave it at "my $tune = ABC->new($datalines)"?

Eagerly wating opinions
Ben

Replies are listed 'Best First'.
Re: Limits of module functionality
by perlplexer (Hermit) on Apr 11, 2003 at 16:34 UTC
    You could have ABC::Reader and ABC::Writer classes. ABC's constructor -- new() -- would accept ABC::Reader as input. ABC's export() or write() method would take ABC::Writer as its argument. This way ABC's core functions would always deal with the same interface. You can provide basic functionality in ABC::Reader and ABC::Writer to read/write from/to scalars and files. The end user will always be able to expand the functionality by extending ABC::Reader and ABC::Writer classes.

    My 2c.

    --perlplexer
[reply]
      Sweeet - that's the baby - thanks.
      Ben
[reply]
Re: Limits of module functionality
by hardburn (Abbot) on Apr 11, 2003 at 16:27 UTC

    There are no hard and fast rules for helper methods. The minimilists would say you shouldn't have any at all, but Perl is not a minimilistic language.

    That doesn't mean you need to go overboard with writing helper methods. The only guideline is: implement the ones you expect to be used a lot. You often won't know what will be used a lot until you actually use the module, so there is no sense spending too much time on helper methods in the first version of the module.

    ----
    I wanted to explore how Perl's closures can be manipulated, and ended up creating an object system by accident.
    -- Schemer

    Note: All code is untested, unless otherwise stated

[reply]
Re: Limits of module functionality
by crouchingpenguin (Priest) on Apr 11, 2003 at 19:21 UTC

    perlplexer makes a good point. I would also like to direct you to You Aren't Gonna Need It, which says: "Always implement things when you actually need them, never when you just foresee that you need them."


    cp
    ----
    "Never be afraid to try something new. Remember, amateurs built the ark. Professionals built the Titanic."
[reply]
Re: Limits of module functionality
by Mr. Muskrat (Canon) on Apr 11, 2003 at 16:31 UTC

    Perhaps you should ask yourself some questions about how you plan on using it. Would you find it helpful to be able to:

    • convert an ABC file to a MIDI file (or series of MIDI files)?
    • convert an ABC file to a MIDI stream?
    • read one tune from an ABC file?
    • read all the tunes from an ABC file?

    If I were writing it, I'd give it only as much functionality as I would need. You can always update it in the future.

    Updated: perlplexer has a better idea below!

[reply]
      Well in that case, it's finished then... <g> No - this is all useful. I think I'm probably thinking more in terms of other people - I already have the 'split a file into bits' or 'write some MIDI data' bits of code in various test routines etc. - I'm more trying to work out how much of that stuff I should bother putting into a nice 'clean' module.

      Cheers,
      Ben
[reply]

        I've never even seen an ABC file but if I saw the module on CPAN, I'd find some just to test it out. Go "whole hog"!

[reply]

Back to Seekers of Perl Wisdom