Running the gauntlet: Volume 1

I began work on open-ils.supercat this weekend, and things are going swimmingly so far. I created the open-ils.supercat.record.marcxml.retrieve and open-ils.supercat.metarecord.mods.retrieve methods with no problem, and added open-ils.supercat.record.mods.retrieve as well. The metarecord building code is mostly a big pile of DOM, but you can see the code here in the sub called retrieve_metarecord_mods if you are so inclined. The record methods, both marcxml and MODS, are much leaner, so I’ll show those inline:

sub retrieve_record_marcxml {
	my $self = shift;
	my $client = shift;
	my $rid = shift;

	return
	entityize(
		$_storage
			->request( 'open-ils.storage.direct.biblio.record_entry.retrieve' => $rid )
			->gather(1)
			->marc
	);
}

__PACKAGE__->register_method(
	method    => 'retrieve_record_marcxml',
	api_name  => 'open-ils.supercat.record.marcxml.retrieve',
	api_level => 1,
	argc      => 1,
	signature =>
		{ desc     => < <"		  DESC",
Returns the MARCXML representation of the requested bibliographic record
		  DESC
		  params   =>
		  	[
				{ name => 'bibId',
				  desc => 'An OpenILS biblio::record_entry id',
				  type => 'number' },
			],
		  'return' =>
		  	{ desc => 'The bib record in MARCXML',
			  type => 'string' }
		}
);

sub retrieve_record_mods {
	my $self = shift;
	my $client = shift;
	my $rid = shift;

	my $marc = $_storage->request(
		'open-ils.storage.direct.biblio.record_entry.retrieve',
		$rid
	)->gather(1)->marc;

	return entityize($_mods_sheet->transform( $_parser->parse_string( $marc ) )->toString);
}

__PACKAGE__->register_method(
	method    => 'retrieve_record_mods',
	api_name  => 'open-ils.supercat.record.mods.retrieve',
	api_level => 1,
	argc      => 1,
	signature =>
		{ desc     => < <"		  DESC",
Returns the MODS representation of the requested bibliographic record
		  DESC
		  params   =>
		  	[
				{ name => 'bibId',
				  desc => 'An OpenILS biblio::record_entry id',
				  type => 'number' },
			],
		  'return' =>
		  	{ desc => 'The bib record in MODS',
			  type => 'string' }
		}
);

As you can see, in both cases the method registration call containing the method signature is larger than the actual sub even with a great deal of whitespace in the code. I will take that as a good sign, since that signature allows scripted API documentation, basic argument checking (that I don’t have to handle inside the method) and quick-glance documentation inline in the code.