db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Army <qoz...@gmail.com>
Subject Re: dblook and lower-case table names created with double-quotes, doc bug or "bug" bug?
Date Wed, 06 Sep 2006 21:07:21 GMT
Susan Cline wrote:
> In reviewing the dblook examples in the Tools and Utilities Guide:
> http://db.apache.org/derby/docs/dev/tools/rtoolsdblookexamples.html
> I noticed the output from using the -t flag with  dblook to specify
> a particular  table created using lower case names and double-quotes
> is inconsistent when creating tablenames in upper case and double-
> quoting the name.

I think the issue here is the way the command-line handles quotes.  Different 
command lines handle quotes differently.  When the documentation for dblook was 
first being written, there were all kinds of notes and explanations and 
exceptions in the documentation about how and when to use single vs double vs 
escaped quotes, and they became more and more complex with every draft.  It was 
eventually decided that proper use of the quotes for a specific command line was 
the responsibility of the user--trying to give examples of how to use quotes 
seemed like it could cause more confusion than anything because the examples 
would inevitably work for one command-line but not another.

> Testing these combinations, case 3 and 5 do not work as expected.
> 3) create table "lower_case_quoted_word"(id integer); 

java -jar ... dblook -d myDB -z APP -t "lower_case_quoted_word"

With K-shell on Windows the double-quotes are stripped off before before they 
ever make it to dblook.  So this ends up looking for a table named 
LOWER_CASE_QUOTED_WORD, which doesn't exist.  In order for this to work you have 
to ensure that the quotes actually make it to dblook--i.e. that the command-line 
doesn't strip them off.  One way to do this is to escape them:

java -jar ... dblook -d myDB -z APP -t \"lower_case_quoted_word\"

> 5)  create table "lower_case quoted three_words"(id integer); 

In this you again need to escape the quotes:

java -jar ... dblook -d myDB -z APP -t \"lower_case quoted three_words\"

but that's not all--K-shell looks at the space as an argument delimiter and thus 
  the above command will look for tables named '"lower_case', 'quoted', and 
'three_words"'--i.e. won't find any of them.  So you have to tell K-shell to 
treat the whole thing as a single argument, which you do by putting ADDITIONAL 
quotes around the whole thing:

java -jar ... dblook -d myDB -z APP -t "\"lower_case quoted three_words\""

And that's just one way to do it; I'm sure there are others.  But to try to 
document this just seems like it's asking for user confusion, so I think the 
assumption is that the user will figure out how his/her command-line deals with 
quotes (and spaces).

If you think specific examples of using quotes/spaces would be more helpful than 
confusing, you should certainly feel free to add them!

 > Is this a doc bug or a bug in the code?

I would say "doc bug", but that does't mean the examples are wrong.  Instead, we 
should probably add a note to the documentation explaining that the quotes shown 
in the examples are *part* of the argument and need to be passed to dblook; how 
that happens depends on the command-line being used.  Then, as mentioned above, 
if anyone thinks some specific examples would be helpful, then s/he/they should 
definitely follow-up to get some examples into the doc...


View raw message