On 15/10/2010, at 10:34 PM, Steve Ebersole wrote:
> And the loss of backwards compatibility? Existing usages (yes all 3 of them
> :) would break
>
It's certainly possible to do this in a backwards compatible way.
One option is that the plugin adds a default book instance. The
AutoCreateDomainObjectContainer would delegate first to this default instance,
and if the property/method were not found, then continue with what it does now.
It might spit out a deprecation warning too, if you configure the default
instance.
I guess the question is whether it's more pain to change the existing usages or
support backwards compatibility in the plugin.
> On Thursday, October 14, 2010, at 11:00 pm, Adam Murdoch wrote:
>> On 14/10/2010, at 2:56 AM, Steve Ebersole wrote:
>>> The jDocBook plugin currently makes an assumption that you have just a
>>> single book per project. If you have multiple books, you need to create
>>> projects, one per book. I want to change that to allow multiple books
>>> per project.
>>>
>>> However, this change entails some major changes to how configuration gets
>>> defined and handled.
>>>
>>> Currently an example configuration would look like:
>>>
>>> jdocbook {
>>>
>>> masterSourceDocumentName = 'GradleUserGide.xml'
>>> translations = ['de-DE']
>>> format {
>>>
>>> name = 'html_single'
>>> finalName = 'index.html'
>>>
>>> }
>>> format {
>>>
>>> name = 'html'
>>> finalName = 'index.html'
>>>
>>> }
>>> format {
>>>
>>> name = 'pdf'
>>>
>>> }
>>>
>>> }
>>>
>>> Let's say I want to add a guide for plugin development as well. I am
>>> thinking that the config syntax that works the best in term of user feel
>>> is:
>>>
>>> jdocbook {
>>>
>>> translations = ['de-DE']
>>> format {
>>>
>>> name = 'html_single'
>>> finalName = 'index.html'
>>>
>>> }
>>> format {
>>>
>>> name = 'html'
>>> finalName = 'index.html'
>>>
>>> }
>>>
>>> userGuide {
>>>
>>> baseDirectory = 'src/main/jdocbook/userGuide'
>>> masterSourceDocumentName = 'GradleUserGide.xml'
>>> format {
>>>
>>> name = 'pdf'
>>>
>>> }
>>>
>>> }
>>>
>>> pluginDevGuide {
>>>
>>> baseDirectory = 'src/main/jdocbook/pluginDevGuide'
>>> masterSourceDocumentName = 'GradlePluginDevGide.xml'
>>>
>>> }
>>>
>>> }
>>>
>>> We have 2 specific guides here, the user guide and the plugin development
>>> guide. Each have some specific configuration as well as sharing some
>>> common configuration. Both have been translated into German; both
>>> should get rendered
>>> into html and html-single styles.
>>
>> This is a very similar syntax that we use for configurations { } and
>> sourceSets { }, so I think this is a good idea.
>>
>>> So the difficulties... That syntax is extremely difficult (maybe just
>>> given my poor Groovy skillz) to mesh with the existing syntax in terms
>>> of applying it. So the first question is just how important
>>> backwards-compatibility is here. If uber-important, i will need to
>>> adjust the syntax i think accordingly since, as I said, its beyond my
>>> Groovy skills to manage that here.
>>>
>>> Also, I am not sure how the "book names" can be handled since they are
>>> dynamic (not a discrete set). Does this maybe need to be an explicit
>>> Map syntax? Or can I manage converting that syntax above into a Map
>>> structure keyed by book name ("userGuide", "pluginDevGuide")? Maybe via
>>> creative use of delegate?
>>
>> For configurations { } and sourceSets { }, the magic is all packaged up in
>> AutoCreateDomainObjectContainer. It supports the above syntax for defining
>> domain objects of a given type (books, I guess, in the jdocbook case).
>> Plus it supports a bunch additional goodness. Some examples:
>>
>> jdocbook {
>> userGuide {
>> // creates a Book called 'userGuide' if it does not exist then
>> configures the book }
>> }
>>
>> // can get the books in various forms
>> jdocbook.each { book -> println book }
>> jdocbook.asMap
>>
>> // books are available as a dynamic property
>> assert jdocbook.userGuide.name == 'userGuide'
>> assert jdocbook['userGuide'].name == 'userGuide'
>>
>> // can add rules
>> jdocbook.allObjects { book -> book.translations = ['de-DE'] }
>> jdocbook.allObjects { book -> project.task("${book.name}Html") ... }
>>
>> The idea is that (eventually) AutoCreateDomainObjectContainer and friends
>> will take care of implementing the Gradle DSL so that the plugin doesn't
>> need to care and is shielded from changes to the DSL. The plugin would
>> simply declare that it needs a collection of named objects with a
>> particular type.
>>
>> The reality is not quite there, of course, in that
>> AutoCreateDomainObjectContainer is an internal class, and there's no
>> public API for implementing/creating one yet.
>>
>>> Is it better to explicitly group the shared configuration in any way?
>>> jdocbook {
>>>
>>> shared {
>>>
>>> translations = ['de-DE']
>>> format {
>>>
>>> name = 'html_single'
>>> finalName = 'index.html'
>>>
>>> }
>>> ...
>>>
>>> }
>>> ...
>>>
>>> }
>>> Does that gain me anything?
>>
>> Possibly not from a DSL point of view. But it would be very simple to
>> implement:
>>
>> def shared(Closure cl) {
>> allObjects(cl)
>> }
>>
>> and you wouldn't need to do any magic in the Book class to take care of
>> inheritance from the shared configuration.
>>
>> It is also something we could add to AutoCreateDomainObjectContainer, so
>> that the concept of 'shared' configuration would be available to each
>> domain object container.
>>
>>
>> --
>> Adam Murdoch
>> Gradle Developer
>> http://www.gradle.org
>> CTO, Gradle Inc. - Gradle Training, Support, Consulting
>> http://www.gradle.biz
>
> ---
> Steve Ebersole <[email protected]>
> http://hibernate.org
>
> ---------------------------------------------------------------------
> To unsubscribe from this list, please visit:
>
> http://xircles.codehaus.org/manage_email
>
>
--
Adam Murdoch
Gradle Developer
http://www.gradle.org
CTO, Gradle Inc. - Gradle Training, Support, Consulting
http://www.gradle.biz
