Proposed API Breakage for Ruport 1.4

1 view
Skip to first unread message

Gregory Brown

unread,
Nov 10, 2007, 12:05:47 AM11/10/07
to Ruby Reports
Hi folks,

Mike and I got out the axe and took it to Ruport (at least in our
minds). What follows here is a set of proposed features to hit the
chopping block come Ruport 1.4

You of course have the right to remain silent, but please keep in mind
that now is the time to argue, not after the release some N weeks from
now. :)

Also, after you've read through this, if you have suggestions for
feature removal you don't see on this list, let us know.

FEATURES TO BE REMOVED FROM RUPORT 1.4 (tentative)

== Database Stuff ==

-- Move acts_as_reportable into it's own gem so it can follow it's own
release schedule.

It will still be loaded by require "ruport" so long as it is
installed and ActiveRecord has been loaded.
require "ruport/acts_as_reportable" will also act as expected. Doing
' gem install acts_as_reportable' will install both ruport and AAR.

-- Move Ruport::Query into ruport-util

This would make core a lot cleaner, and let me do forward development
on Ruport::Query as needed.

== PDF ==

--- Remove watermark() helper, as it doesn't really make watermarks

== Data Manipulations ==

-- Remove Table#swap_column

I don't hate this method, just have never used it, and never seen it
used in code posted here.
Seems like a special case to me

-- Remove Array#to_table

This would force you to use: Table(%w[my col names], :data => my_arr)
instead of my_arr.to_table(%w[my col names]) but would remove an
ambiguous method name from our core extensions and generally be a
little softer on the eyes. This used to be my favorite method, but it
seems to be past its prime.

-- Make Group#create_subgroups private

This is mainly a helper function for the Grouping class, and not much
more. Is anyone using it directly?

== Renderer / Formatter ==

-- Get rid of prepare / finalize

We'd make up for removing these two special declarations from your
renderer by giving you before_filter and after_filter in your
formatters. Details:

http://stonecode.svnrepository.com/ruport/trac.cgi/ticket/370

-- Get rid of option in Renderer definition

In this example, you can see us using option()

class Foo < Ruport::Renderer
option :bar
end

This creates an attribute *writer* but not a reader on your renderer
instance, which can only really be used in the block form of rendering
stuff, such as:

Foo.render_something { |r| r.bar = 'kittens' }

Many of us don't use the block form often, so this is next-to-useless.
Without it, the above would look like:

Foo.render_something { |r| r.options.bar = 'kittens' }

And in both cases, this would still work:

Foo.render_something(:bar => 'kittens')

Keep in mind that we're not suggesting we should remove
required_option(), that is here to stay. (Though I personally seldom
use it)

-- Get rid of AutoRunner and make _run_ the default run behavior for Renderer.

Don't know what I'm talking about? Then you don't need this feature!
If you do have a bit of experiences with the internals, this means
you'd need to call super to get the same effect, like:

class MyRenderer < Ruport::Renderer
def run
# do some stuff
super
end
end

now that I think of it, that looks cleaner than the present:

class MyRenderer < Ruport::Renderer
def run
#do something
end
include Ruport::Renderer::AutoRunner
end

-- Make Renderer::build private

Is anyone using this feature at all? It builds you a renderer
instance, and does some semi-complex bootstrapping of the formatting
system.
I think we will make this private, as if you're doing hairy enough
stuff to require using this, you can use send() ;)

-- Remove options.io from formatter special behavior

Is anyone using something like:

table.as(:csv, :io => my_io_object)

There are some benefits to this... it allows data streaming directly
to that object instead of building up a string first... but maybe
YAGNI?

--- Remove Formatter#clear_output

This means you'd need to do @output.clear, though I don't really see
the harm in leaving this one in if people like it.


That's pretty much it for now. Thoughts?

Gregory Brown

unread,
Nov 11, 2007, 11:57:52 PM11/11/07
to Ruby Reports
On Nov 10, 2007 12:05 AM, Gregory Brown <gregory...@gmail.com> wrote:
> Hi folks,
>
> Mike and I got out the axe and took it to Ruport (at least in our
> minds). What follows here is a set of proposed features to hit the
> chopping block come Ruport 1.4
>
> You of course have the right to remain silent, but please keep in mind
> that now is the time to argue, not after the release some N weeks from
> now. :)

Just a heads up that we'll start doing some of these removals
mid-week, so if you've been holding onto comments, it's a good time to
speak up.

Those running off of trunk should join the ruport-dev list as these
changes will likely result in some significant changes to the
internals, and we'll make announcements on that list about it.

-greg

Gufo Pelato

unread,
Nov 15, 2007, 3:48:21 AM11/15/07
to ruby-r...@googlegroups.com
Greetings,

Having started to use Ruport just a couple of weeks ago I'm a bit
green and probably don't understand very well Ruport and how to do
things in the right way, so I don't know if my comments should ever be
sent to the list...

On Nov 10, 2007 6:05 AM, Gregory Brown <gregory...@gmail.com> wrote:
> You of course have the right to remain silent, but please keep in mind
> that now is the time to argue, not after the release some N weeks from
> now. :)

I hope not to be too late :-)

> -- Remove Table#swap_column
>
> I don't hate this method, just have never used it, and never seen it
> used in code posted here.
> Seems like a special case to me

I haven't had enough time to study Ruport's internal, but I used
swap_column at least once and if there is not a better way to handle
that particular action without turning to Table#reorder, I'd vote to
keep it.

> -- Get rid of prepare / finalize
>
> We'd make up for removing these two special declarations from your
> renderer by giving you before_filter and after_filter in your
> formatters. Details:
>
> http://stonecode.svnrepository.com/ruport/trac.cgi/ticket/370

Well, I've successfully used prepare_table in a kludge: I subclassed
Ruport::Formatter::PDF and defined prepare_table to customize PDF
creation (adding a couple of starting paragraph and activating page
numbering) for standard table without taking the hard way of
subclassing also the tabular renderer... it's a kludge, but it works
:-) so if the new before_filter would allow me to take the same
shortcut I'd be very happy.

Gregory Brown

unread,
Nov 15, 2007, 8:06:02 AM11/15/07
to ruby-r...@googlegroups.com

sure, something like:

class PDF < Ruport::Formatter::PDF

before_filter :prepare_table, :only => [:table]

def prepare_table
# ...
end

end

Gregory Brown

unread,
Nov 15, 2007, 8:08:55 AM11/15/07
to ruby-r...@googlegroups.com
On Nov 15, 2007 8:06 AM, Gregory Brown <gregory...@gmail.com> wrote:

> > I hope not to be too late :-)

Nope. I was just getting ready to work on this, but you're in time. :)

> > > -- Remove Table#swap_column
> > >
> > > I don't hate this method, just have never used it, and never seen it
> > > used in code posted here.
> > > Seems like a special case to me
> >
> > I haven't had enough time to study Ruport's internal, but I used
> > swap_column at least once and if there is not a better way to handle
> > that particular action without turning to Table#reorder, I'd vote to
> > keep it.

Having at least one vote for this saves its life for now. We'll
discuss possibly removing it in a later version of Ruport.
If anything, I might want to change the behavior of Table#reorder a
bit to make it accommodate this, but we shall see.

-greg

Gufo Pelato

unread,
Nov 17, 2007, 2:58:45 AM11/17/07
to ruby-r...@googlegroups.com
Hi,

On Nov 15, 2007 2:06 PM, Gregory Brown <gregory...@gmail.com> wrote:
> sure, something like:
>
> class PDF < Ruport::Formatter::PDF
>
> before_filter :prepare_table, :only => [:table]
>
> def prepare_table
> # ...
> end
>
> end

Even if it's still too early, let me ask a simple question about these
before/after_filter: they will be applied only before/after the bulk
processing of stages, there will not be anything like

before_filter :something, :on => a_stage
after_filter :something_else, :on => another_stage

right? Nota Bene: I'm not asking for the latter type of filters, I'm
just curious.

Gregory Brown

unread,
Nov 17, 2007, 3:09:41 AM11/17/07
to ruby-r...@googlegroups.com

They will support each individual stage:

so if you have:

class MyRenderer < Ruport::Renderer
stage :foo, :bar, :baz
end

class MyFormatter < Ruport::Formatter
renders :something, :for => MyRenderer

before_filter :something, :only => :foo

before_filter :something_else, :only => :baz

end

The real reason is for when you're dealing with multiple renderers
using the same formatter.

Reply all
Reply to author
Forward
0 new messages