entropyreduction wrote:
>> >
>> > There are lots of properties to specify for each possible
> parameter:
>> Let me give you my own preference.
>> > short form
>> Must have.
>> > long form
>> Must have.
>> > is it optional
I thought about this some more, and if your C++ classes already support
this, then the plugin should implement it.
Add syntax ':' <optional> ':' where <optional> ::= '0'|'1'
>
>> > how many arguments follow it (0/1, maybe more than 1?)
>> Just one. That's enough for me.
zero or one.
>>
>> > if you allow only one argument, what's it type?
>> x:xlong:i;y:ylong:s:z:zlong:: means
>> -x <int> || -xlong <int> || -y <string> || -ylong <string> || -z
>|| -zlong
>
> Shall we keep it simple and drip type-checking within plugin then?
>
Plugin does type checking, at least :i: for integer, what else is really
needed?
>> > default value if missing
>> let the script deal with that. Just optionally raise error if
>> x:xlong:i: isn't followed by <integer>
>
> okay, anything for easy life.
>> So, summarizing and factoring in all our ideas, I propose the
> following
>> service and syntax:
>>
>> error_message = options.eval(<option syntax>,<arguments>)
>> // option.eval returns a properly formatted error message
>> // (whose parts are specified in the <option syntax>) if a
>> // parsing error was encountered, otherwise it returns "".
>> // Optionally the plugin can be configured to automatically
>> // raise an error message box.
>
> actually I was thinking of returning "OK: n" where n was the number
> of parameters found.
>
What's the use of n?
I think the error message is more useful. Note that this error message
is not the whole usage message, it includes just the <usage msg> fields
of the options that didn't parse correctly. This makes it easy to focus
the user's attention on just the syntax errors that he actually made.
>> usage_message = options.usage(<option syntax>)
>> // option.usage returns a properly formatted usage message
>> // (whose parts are specified in the <option syntax>). This
>> // is the complete usage message, not just an error message.
>> // No parsing is involved here.
>>
>> // Option Definition Syntax
>>
>> <option syntax> ::= <option> [ ';' <option> ]*
>> <option> ::= <output name>:<short>':'<long>':'<type>':'<usage msg>
Adding <optional> this now becomes
<option> ::= <output name>
':' <optional>
':' <short>
':' <long>
':' <type>
':' <usage msg>
<optional> ::= '0' | '1'
>> <output name> ::= <PowerPro expression> // see comments below
>> // any PP expression that evaluates to the name of a global variable
>> // INCLUDING the name of a map element, i.e., m["x"]
>> <short> ::= <single letter> // can't be ':' or ';'
>> <long> ::= <string> // can't include ':' or ';'
>> <type> :: 'i' | 's' | 'b' //possibly others except ':' or ';'
>> // integer, string, boolean, ...
>> <usage msg> ::= <string> // can't include ':' or ';'
>>
>> // keep the <option syntax> string as short as possible, PPro has
> string
>> length limits
Here we go, stealing the idea from the keymap plugin, I'd like to
propose to use an external file to specify the option syntax, instead of
a string. I can see several advantages:
1. overcome string length limitations--modified syntax: one <option> per
line
2. easy to prototype and change
3. no need to change the script itself--great when one didn't author the
script
4. easy to localize usage messages in another language--important, since
options parsing is part of the user interface
>> error_message = options.eval(<option syntax>,<arguments>)
>> // option.eval returns a properly formatted error message
>> // (whose parts are specified in the <option syntax>) if a
>> // parsing error was encountered, otherwise it returns "".
>> // Optionally the plugin can be configured to automatically
>> // raise an error message box.
>
> actually I was thinking of returning "OK: n" where n was the number
> of parameters found.
>
What's the use of n? I think the error message is more useful. Note that
this error message is not the whole usage message, it includes just the
<usage msg> fields of the options that didn't parse correctly. This
makes it easy to focus the user's attention on just the errors that the
user made when keying in a long list of options.
>> usage_message = options.usage(<option syntax>)
>> // option.usage returns a properly formatted usage message
>> // (whose parts are specified in the <option syntax>). This
>> // is the complete usage message, not just an error message.
>> // No parsing is involved here.
>>
>> // Option Definition Syntax
>>
>> <option syntax> ::= <option> [ ';' <option> ]*
>> <option> ::= <output name>:<short>':'<long>':'<type>':'<usage msg>
Adding <optional> this now becomes
<option> ::= <output name>
':' <optional>
':' <short>
':' <long>
':' <type>
':' <usage msg>
<optional> ::= '0' | '1'
>> <output name> ::= <PowerPro expression> // see comments below
>> // any PP expression that evaluates to the name of a global variable
>> // INCLUDING the name of a map element, i.e., m["x"]
>> <short> ::= <single letter> // can't be ':' or ';'
>> <long> ::= <string> // can't include ':' or ';'
>> <type> :: 'i' | 's' | 'b' //possibly others except ':' or ';'
>> // integer, string, boolean, ...
>> <usage msg> ::= <string> // can't include ':' or ';'
>>
>> // keep the <option syntax> string as short as possible, PPro has
> string
>> length limits
Here we go, stealing the idea from the keymap plugin, I'd like to
propose to use an external file to specify the option syntax, instead of
a string. I can see several advantages:
1. overcome string length limitations--modified syntax: one <option> per
line
2. easy to prototype and change
3. no need to change the script itself--great when one didn't author the
script
4. easy to localize usage messages in another language--important, since
options parsing is part of the user interface
Revised Sample Script
=====================
; define option syntax
global opt = map.create(2)
local r1 r2
setstring r1 opt["x"]:0:x:xlong:i:mandatory -x|-xlong followed by <int>
setstring r1 opt["y"]:1:y:ylong::optional -y|-ylong
; create options file if it doesn't already exist
local rulefile=scriptfolder++"\"++scriptname++".opt"
local nl
setstring nl 'r
if( not validpath rulefile )
file.writeall(rulefile,r1++nl++r2)
; test the plugin
local test = "-xlong 3"
local message = options.eval(rulefile, test)
; assume the plugin is set NOT to raise an error message box
if ( message ) do
messagebox("error", message)
quit(-1)
endif
win.debug("parsed -x=3 and no -y (optional). Check:",opt["x"],opt["y"])
quit(0)
Revised Service definition
==========================
error_message = options.eval(<syntax file>,<arguments>)
// Option.eval parses <arguments> and sets return values
// according to an <option syntax> specified in a <syntax file>
// It returns "" if no syntax error occurred.
// It returns a properly formatted error message
// (whose parts are specified in the <option syntax> when
// one or parsing errors are found.
// Optionally the plugin can be configured to automatically
// raise an error message box.
usage_message = options.usage(<syntax file>)
// Option.usage returns a properly formatted usage message
// (whose parts are specified in a <syntax file> according
// to an <option syntax>. This is the complete usage message,
// as if all possible parsing errors were encountered. However,
// no actual parsing takes place.
Revised Option Definition Syntax
================================
<option syntax> ::= <option> [ ';' <option> ]*
<option> ::= <output name>
':' <optional>
':' <short>
':' <long>
':' <type>
':' <usage msg>
[ ':' <reserved> ':' <reserved> ':' <reserved> ':' <comments> ]
<output name> ::= <PowerPro expression> // see comments below
// any PP expression that evaluates to the name of a global variable
// INCLUDING the name of a map element, i.e., m["x"]
<optional> ::= '0' | '1' // flag
<short> ::= <single letter> // can't be ':' or ';'
<long> ::= <string> // can't include ':' or ';'
<type> :: 'i' //possibly others except ':' or ';'
// i=integer
<usage msg> ::= <string> // can't include ':' or ';'
<reserved> ::= NULL // reserved for future use
<comments> ::= ANY STRING // user comments
>
>
> How about this?
>
> local optionsVecTest = vec.create(10)
> local puddle_value
> optionsVecTest[0]=map.create(4)
>
> ;this ain't legal syntax, sadly
> ;optionsVecTest[0]["short"] = "p"
>
> map.set(optionsVecTest[0],"short","p")
> map.set(optionsVecTest[0],"long","puddle")
> map.set(optionsVecTest[0],"comment","no duck")
> map.set(optionsVecTest[0],"retvar","puddle_value")
>
> win.debug(map.get(optionsVecTest[0],"long"))
>
> ;this works okay, I can get map elements of the vector element
> ;inside the plugin using ppsv->EvalExpr, even though the vec
> ;is local
>
> ;I can test to make sure thew arg is a vector, and I can test to see
> ;I can find the lengh of the vector
> ;I can iterate through vector from 0 until I hit an item that isn't a
> map, at which point I quit
>
> options.eval("optionsVecTest", "-puddle ""oh my dear said the
> duck""")
>
> ;and yippie this works, the plugin sets var found in "retvar"
> ;element, even though its a local var
>
> win.debug(puddle_value)
>
> vec.destroy(optionsVecTest)
> optionsVecTest = ""
> options.unload
>
>
> How's that strike you?
>
Complicated for the novice script writer who is forced to learn vectors
of maps just to say .Script("-x 1"). Sorry.
Also, I think the external syntax file is a more flexible approach, the
keytrap plugin is a living example.
I understand you'd prefer to not parse strings, but basically the above
syntax can be parsed by simply breaking a line at ':' field dividers.
> BTW you willing to act as documentation editor and tester for this
> thing?
>
Yes, but honestly if it's kept simple for the user, and your last
proposal seems complicated.
--sgp
------------------------ Yahoo! Groups Sponsor ---------------------~-->
Make a clean sweep of pop-up ads. Yahoo! Companion Toolbar.
Now with Pop-Up Blocker. Get it for free!
http://us.click.yahoo.com/L5YrjA/eSIIAA/yQLSAA/JV_rlB/TM
---------------------------------------------------------------------~->
Yahoo! Groups Links
<*> To visit your group on the web, go to:
http://groups.yahoo.com/group/power-pro/
<*> To unsubscribe from this group, send an email to:
[EMAIL PROTECTED]
<*> Your use of Yahoo! Groups is subject to:
http://docs.yahoo.com/info/terms/
