Proposal, Heirarchical module structure for tools

[Neil Mitchell]

Hi,

The current hattools directory has 38 Haskell files in it, and 34
.h/.c files. It would be nice if these were split so it was easy to
determine the files in one program, and what is a tool versus what is
a library.

The following is a draft proposal:

Hat - global module in which all Hat stuff resides

(this clashes with the hat-trans output, does this matter?)

Hat.Lib - directory for libraries, which export a nice API for using
in the tools - for example HatCover as Hat.Lib.Cover.

Hat.Tool - directory for the tools, for example HatCoverText, as Hat.Tool.Cover

Hat.Common - Common functions which are unrelated to Hat tracing, but
are used by the Tools, for example HighlightStyle as
Hat.Common.HighlightStyle

Within Hat.Tool, I would expect some simpler (one module) tools to be
Hat.Tool.ToolName, but more complex tools would be
Hat.Tool.ToolName.Modules, with a single Hat.Tool.ToolName module
which imports the others.

To keep the structure of having a Main module at the root which is the
tool for each given tool, for each tool a file would be created:

-- file HatCover.hs
import Hat.Tool.Cover

This file gives an easy module Main to be located for each tool.

The advantages of this scheme:
* Easier to differentiate between libraries and tools
* Easier to find a particular tool and all its given code
* Clearer separation of Hat code vs general Haskell

Thanks

Neil
_______________________________________________
Hat mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/hat

[Thomas Davie-2]

Interesting.  Okay, so my question then is, where would something like EDT.hs or SExp.hs go?  They aren't libraries for one tool, they aren't commonly used and they aren't one tool.

Bob

_______________________________________________
Hat mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/hat

[Neil Mitchell]

Hi,

> Interesting.  Okay, so my question then is, where would something like EDT.hs or SExp.hs go?  They aren't libraries for one tool, they aren't commonly used and they aren't one tool.

Hat.Lib.SExp and Hat.Lib.EDT, they are libraries - things in Hat.Lib
don't have to be for one tool, they just have to be libraries. Part of
the hope of this exercise would be that the one tool - one library
model goes away slowly, as the tools start to share more and more
library code.

Thanks

Neil
_______________________________________________
Hat mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/hat

[Malcolm Wallace]

"Neil Mitchell" <[hidden email]> wrote:

> The current hattools directory has 38 Haskell files in it, and 34
> .h/.c files. It would be nice if these were split so it was easy to
> determine the files in one program, and what is a tool versus what is
> a library.

In principle, I agree that using the hierarchical namespace to separate
concerns would be nice.

> Hat - global module in which all Hat stuff resides
> (this clashes with the hat-trans output, does this matter?)

Yes, it matters a great deal.  We have reserved the 'Hat' top-level
namespace for the exclusive use of trace-transformed programs.  No-one
should ever use that namespace intentionally for anything else.

My suggestion is to reserve Tracing.Hat as the root of a hierarchy for
Hat-related trace-viewing (or transforming?) libraries.

> Hat.Lib - directory for libraries, which export a nice API for using
> in the tools - for example HatCover as Hat.Lib.Cover.
>
> Hat.Tool - directory for the tools, for example HatCoverText, as
> Hat.Tool.Cover

I don't like this division much.  How should I decide whether I'm
looking for a Lib or a Tool, or a Common?  In principle, everything can
be treated more or less as a library.  Lib/Tool/Common is a
meta-category, not a name chosen to reflect the underlying
functionality.

My suggestion would be just to drop that part.  So, e.g.

   Tracing.Hat.Observe
   Tracing.Hat.Trail
   Tracing.Hat.SExp
   Tracing.Hat.HighlightStyle

Then, other modules used exclusively by a single "tool" (or style of
interaction I suppose) would be placed directly under the relevant
category, e.g.

   Tracing.Hat.Observe.FileAccess
   Tracing.Hat.Observe.TextUI
   Tracing.Hat.Observe.GUI
   Tracing.Hat.Trail.Navigation

Regards,
    Malcolm
_______________________________________________
Hat mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/hat

[Neil Mitchell]

Hi

> Yes, it matters a great deal.  We have reserved the 'Hat' top-level
> namespace for the exclusive use of trace-transformed programs.  No-one
> should ever use that namespace intentionally for anything else.

Fair enough, seems reasonable. Although then I wonder if we need the
"Hat" part, just Tracing.Observe should be enough, since its just as
unique, and its in the Hat repo so makes it clear enough.

> My suggestion would be just to drop that part.  So, e.g.
>
>    Tracing.Hat.Observe
>    Tracing.Hat.Trail
>    Tracing.Hat.SExp
>    Tracing.Hat.HighlightStyle

It would be nice to indicate in some way "this exports some gunk that
happened to be useful", and "this exports a nice clean API that I
expect to be used" - although I guess that can go in the
documentation.

I still think its nice to have a some sort of classification as to
what libaries are "general Haskell libraries" and which are "Hat
Tracing stuff" - for example Tracing.Hat.HighlightStyle isn't really
anything to do with Hat or Tracing.

However, what you propose is close enough that I'm not overly fussed
and would happily accept it.

Thanks

Neil
_______________________________________________
Hat mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/hat

[Thomas Davie]

I have a feeling I'm about to get shouted down because Hat is not  
just a debugger... But...

The Debug. namespace already exists, why not Debug.Hat?

Directly in response to Neil - we do need Hat in the structure  
whichever we choose - what if there's another Debugging/Tracing tool  
with an Observe module?

Bob

On 10 Oct 2006, at 16:32, Neil Mitchell wrote:

> Hi
>
>> Yes, it matters a great deal.  We have reserved the 'Hat' top-level
>> namespace for the exclusive use of trace-transformed programs.  No-
>> one
>> should ever use that namespace intentionally for anything else.
>
> Fair enough, seems reasonable. Although then I wonder if we need the
> "Hat" part, just Tracing.Observe should be enough, since its just as
> unique, and its in the Hat repo so makes it clear enough.
>
>> My suggestion would be just to drop that part.  So, e.g.
>>
>>    Tracing.Hat.Observe
>>    Tracing.Hat.Trail
>>    Tracing.Hat.SExp
>>    Tracing.Hat.HighlightStyle

_______________________________________________
Hat mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/hat

[Colin Runciman]

Bob,

> I have a feeling I'm about to get shouted down because Hat is not
> just a debugger... But...
>
> The Debug. namespace already exists, why not Debug.Hat?

Shout! Shout! Shout! :-)

Tracing -- or Trace if you prefer.  Please.

Colin R

_______________________________________________
Hat mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/hat

[Neil Mitchell]

Hi,

> > Hat.Lib - directory for libraries, which export a nice API for using
> > in the tools - for example HatCover as Hat.Lib.Cover.
> >
> > Hat.Tool - directory for the tools, for example HatCoverText, as
> > Hat.Tool.Cover
>
> I don't like this division much.  How should I decide whether I'm
> looking for a Lib or a Tool, or a Common?  In principle, everything can
> be treated more or less as a library.  Lib/Tool/Common is a
> meta-category, not a name chosen to reflect the underlying
> functionality.

So where would the library half of HatCover vs the program half of HatCover go?

Thanks

Neil

PS. Debug.Trace is already a module, perhaps we could put things under that ;)
_______________________________________________
Hat mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/hat

[Malcolm Wallace]

"Neil Mitchell" <[hidden email]> wrote:

> > I don't like this division much.  How should I decide whether I'm
> > looking for a Lib or a Tool, or a Common?
>
> So where would the library half of HatCover vs the program half of
> HatCover go?

    HatCover     -> Tracing.Hat.Coverage
    HatCoverText -> Tracing.Hat.Coverage.Textual
    hypothetical -> Tracing.Hat.Coverage.HTML
    hypothetical -> Tracing.Hat.Coverage.Gtk

Regards,
    Malcolm
_______________________________________________
Hat mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/hat

[Neil Mitchell]

> > So where would the library half of HatCover vs the program half of
> > HatCover go?
>
>     HatCover     -> Tracing.Hat.Coverage
>     HatCoverText -> Tracing.Hat.Coverage.Textual
>     hypothetical -> Tracing.Hat.Coverage.HTML
>     hypothetical -> Tracing.Hat.Coverage.Gtk

Hmm, I don't like that much. I'm not entirely sure about this whole
calling console programs "Textual", they aren't, they are Console
programs (I object to HatCoverText as well). It also obscures the fact
that HTML should be an API (so the Console and Gui can use it), but
Gtk will probably be a viewer.

Thanks

Neil
_______________________________________________
Hat mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/hat

[Malcolm Wallace]

"Neil Mitchell" <[hidden email]> wrote:

> > > So where would the library half of HatCover vs the program half of
> > > HatCover go?
> >
> >     HatCover     -> Tracing.Hat.Coverage
> >     HatCoverText -> Tracing.Hat.Coverage.Textual
> >     hypothetical -> Tracing.Hat.Coverage.HTML
> >     hypothetical -> Tracing.Hat.Coverage.Gtk
>
> Hmm, I don't like that much. I'm not entirely sure about this whole
> calling console programs "Textual", they aren't, they are Console
> programs (I object to HatCoverText as well).

Well, "console" is the wrong word as well.  On a unix machine, there is
only one console, but there may be many textual terminals or terminal
emulators.

I intended the word "textual" to indicate an API that produces Strings,
not something that interacts per se with a terminal.  However, I now
realise that your objection is probably that the text strings produced
are not pure - they have ANSI terminal colour codes.  Fair enough.

        HatCoverText -> Tracing.Hat.Coverage.ANSIterm

> It also obscures the fact
> that HTML should be an API (so the Console and Gui can use it), but
> Gtk will probably be a viewer.

Well, I intended that all of these should be APIs, the ANSI coloured
text as much as the HTML.  As you say, the actual rendering of these
belongs elsewhere.  So if there is no particular role for a GTK API
for hat-cover, it should not exist as a module Tracing.Hat.Coverage.Gtk.

The rendering might therefore belong in something like
    Tracing.Hat.GtkGUI
which might use APIs from Tracing.Hat.Coverage as well as
Tracing.Hat.Observe, and numerous others as well.

Regards,
    Malcolm
_______________________________________________
Hat mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/hat

[Neil Mitchell]

Hi

> I intended the word "textual" to indicate an API that produces Strings,
> not something that interacts per se with a terminal.  However, I now
> realise that your objection is probably that the text strings produced
> are not pure - they have ANSI terminal colour codes.  Fair enough.

Ah, I thought your intention was to export a "main" from this -
returning Strings (coloured strings at that) is a perfectly reasonable
thing to have as an API.

The way I do terminal codes in Hoogle is to define a type, TagStr:

data TagStr = Str String | Tags [TagStr] | Underline TagStr | Bold
TagStr | Color Int TagStr

Now instead of dumping out escape codes, I dump out TagStr's, and then
have a routine that converts from TagStr -> String with escape codes.
This has the massive advantage that on OS's that don't support escape
codes, I can use exactly the same generation code, and then drop the
escape codes very simply.

Perhaps thats a better way to go instead of having an API that works
in very low level escape code terms.


>         HatCoverText -> Tracing.Hat.Coverage.ANSIterm

The name ANSIterm makes me uneasy, Terminal perhaps? ANSIterm just
looks ugly, and the case of it is weird compared to the rest of
Haskell.

In general we now seem to be pretty much in agreement about the
proposed structure.

Thanks

Neil
_______________________________________________
Hat mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/hat

[Thomas Davie]

>
> The way I do terminal codes in Hoogle is to define a type, TagStr:
>
> data TagStr = Str String | Tags [TagStr] | Underline TagStr | Bold
> TagStr | Color Int TagStr
>
> Now instead of dumping out escape codes, I dump out TagStr's, and then
> have a routine that converts from TagStr -> String with escape codes.
> This has the massive advantage that on OS's that don't support escape
> codes, I can use exactly the same generation code, and then drop the
> escape codes very simply.

You should note that this is in large part what hat already does.  
Look at the Highlight Module.

Bob

>>         HatCoverText -> Tracing.Hat.Coverage.ANSIterm
>
> The name ANSIterm makes me uneasy, Terminal perhaps? ANSIterm just
> looks ugly, and the case of it is weird compared to the rest of
> Haskell.
>
> In general we now seem to be pretty much in agreement about the
> proposed structure.

I can't see any major problems with it.

Bob
_______________________________________________
Hat mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/hat

[Neil Mitchell]

Hi,

> You should note that this is in large part what hat already does.
> Look at the Highlight Module.
>
> >>         HatCoverText -> Tracing.Hat.Coverage.ANSIterm
> >
> > The name ANSIterm makes me uneasy, Terminal perhaps? ANSIterm just
> > looks ugly, and the case of it is weird compared to the rest of
> > Haskell.

In that case how about Tracing.Hat.Coverage.Highlight, exporting a
data structure one step above the low level escape coded strings.
Saves us the issue of making an ugly name, and makes it more useful.

Thanks

Neil
_______________________________________________
Hat mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/hat

[Thomas Davie]

Highlight is used by all the tools though, so Tracing.Hat.Highlight  
would make much more sense.

Bob

On 11 Oct 2006, at 15:04, Neil Mitchell wrote:

> Hi,
>
>> You should note that this is in large part what hat already does.
>> Look at the Highlight Module.
>>
>> >>         HatCoverText -> Tracing.Hat.Coverage.ANSIterm
>> >
>> > The name ANSIterm makes me uneasy, Terminal perhaps? ANSIterm just
>> > looks ugly, and the case of it is weird compared to the rest of
>> > Haskell.
>
> In that case how about Tracing.Hat.Coverage.Highlight, exporting a
> data structure one step above the low level escape coded strings.
> Saves us the issue of making an ugly name, and makes it more useful.
>
> Thanks
>
> Neil
> _______________________________________________
> Hat mailing list
> [hidden email]
> http://www.haskell.org/mailman/listinfo/hat

_______________________________________________
Hat mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/hat

[Malcolm Wallace]

"Neil Mitchell" <[hidden email]> wrote:

> > You should note that this is in large part what hat already does.
> > Look at the Highlight Module.
>
> In that case how about Tracing.Hat.Coverage.Highlight, exporting a
> data structure one step above the low level escape coded strings.

Yeah.  Or
    Tracing.Hat.Coverage.Highlighted
or
    Tracing.Hat.Coverage.Highlit
to make it even clearer.

Regards,
    Malcolm
_______________________________________________
Hat mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/hat

[Neil Mitchell]

Hi

> Highlight is used by all the tools though, so Tracing.Hat.Highlight
> would make much more sense.

For the module that gives an abstract data structure for a
"Highlighted expression"

> > In that case how about Tracing.Hat.Coverage.Highlight

For the module that generates coverage data in a highlighted data structure.

I think everyone agrees pretty much now :)

Thanks

Neil
_______________________________________________
Hat mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/hat