Mantis Bug Tracker
Main | My View | View Issues | Change Log | Roadmap
  

View Issue Details [ Jump to Notes ] [ Issue History ] [ Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0005437OCamlOCaml generalpublic2011-12-21 16:542012-09-25 20:07
Reporterjohnwhitington 
Assigned Toprotz 
PrioritynormalSeverityfeatureReproducibilityN/A
StatusclosedResolutionfixed 
PlatformOSOS Version
Product Version 
Target VersionFixed in Version3.13.0+dev 
Summary0005437: Patch to allow command line arguments in Arg module to be undocumented
DescriptionHallo.

The Arg module doesn't have any mechanism for developer command line switches which are not exposed to the user.

This patch hides a switch if its help string begins with the characters "ARG-UNDOC". The documentation string in the .mli is modified to explain this change.

We could, of course, choose something more concise than "ARG-UNDOC" like "*", but then it might clash with existing code.

Thanks,

John Whitington
Coherent Graphics Ltd
TagsNo tags attached.
Attached Filespatch file icon arg-undocumented.patch [^] (934 bytes) 2011-12-21 16:54 [Show Content]

- Relationships

-  Notes
(0006467)
protz (manager)
2011-12-21 17:13

 Hi,

First of all, thanks for the patch. However, that looks like quite the hack! Thus, I'm afraid we cannot integrate this patch as-is.

The right way to do this would be to change signature of parse from

val parse :
  (key * spec * doc) list -> anon_fun -> usage_msg -> unit

to

val parse :
  (key * spec * doc * documented) list -> anon_fun -> usage_msg -> unit

type documented = bool

However, this would break backwards compatibility. What you can do instead is add an optional unit argument to the parse function and others, that tells whether arguments with no documentation should be printed out.

Thinking about it, that sounds very ad-hoc, and I tend to think you'd be better off keeping a private (tweaked) copy of arg.ml in your source tree...
(0006472)
gasche (developer)
2011-12-21 21:02

 Maybe the following function could be added:
  val parse_rich : (key * spec * rich_doc) -> anon_fun -> usage_msg -> unit
where rich_doc is an abstract type¹ with
  val doc : string -> rich_doc
  val undocumented : rich_doc

¹: not having "doc" abstract in the first place is what makes it difficult to enrich the behavior now without breaking compatibility.
(0006483)
protz (manager)
2011-12-22 09:36

 Right, but there's a whole lot of functions that take triples (key * spec * doc), are you implying that we should provide an alternative version for each one of them? I can see people asking for more if we were to implement just one...
(0006505)
protz (manager)
2011-12-22 15:05

 After discussing this with others, this has been fixed in svn revision r11939.

To have an option not included in the usage string, just put an empty string for its documentation.
(0006514)
johnwhitington (reporter)
2011-12-23 12:44

 Thanks for this, but the patch isn't right: it conflicts with the padding of help strings. You need to also do:

--- trunk/stdlib/arg.ml 2011-12-22 19:03:46.000000000 +0000
+++ arg.ml 2011-12-23 11:40:17.000000000 +0000
@@ -238,6 +238,7 @@
 
 let add_padding len ksd =
   match ksd with
+ | (_, _, "") -> ksd (* Do not pad undocumented ones. *)
   | (kwd, (Symbol (l, _) as spec), msg) ->
       let cutcol = second_word msg in
       let spaces = String.make (len - cutcol + 3) ' ' in
(0006515)
protz (manager)
2011-12-23 14:34

 Good catch! I'd never used [align] before so I didn't think of it.

svn r11946

- Issue History
Date Modified Username Field Change
2011-12-21 16:54 johnwhitington New Issue
2011-12-21 16:54 johnwhitington File Added: arg-undocumented.patch
2011-12-21 17:13 protz Note Added: 0006467
2011-12-21 21:02 gasche Note Added: 0006472
2011-12-22 09:36 protz Note Added: 0006483
2011-12-22 09:36 protz Assigned To => protz
2011-12-22 09:36 protz Status new => feedback
2011-12-22 15:05 protz Note Added: 0006505
2011-12-22 15:05 protz Status feedback => resolved
2011-12-22 15:05 protz Fixed in Version => 3.13.0+dev
2011-12-22 15:05 protz Resolution open => fixed
2011-12-23 12:44 johnwhitington Note Added: 0006514
2011-12-23 12:44 johnwhitington Status resolved => feedback
2011-12-23 12:44 johnwhitington Resolution fixed => reopened
2011-12-23 14:34 protz Note Added: 0006515
2011-12-23 14:34 protz Status feedback => resolved
2011-12-23 14:34 protz Resolution reopened => fixed
2012-09-25 20:07 xleroy Status resolved => closed

Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker