Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Patch to allow command line arguments in Arg module to be undocumented #5437

Closed
vicuna opened this Issue Dec 21, 2011 · 6 comments

Comments

Projects
None yet
1 participant
@vicuna
Copy link
Collaborator

commented Dec 21, 2011

Original bug ID: 5437
Reporter: @johnwhitington
Assigned to: @protz
Status: closed (set by @xavierleroy on 2012-09-25T18:07:21Z)
Resolution: fixed
Priority: normal
Severity: feature
Fixed in version: 3.13.0+dev
Category: ~DO NOT USE (was: OCaml general)
Monitored by: @protz @hcarty

Bug description

Hallo.

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

File attachments

@vicuna

This comment has been minimized.

Copy link
Collaborator Author

commented Dec 21, 2011

Comment author: @protz

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...

@vicuna

This comment has been minimized.

Copy link
Collaborator Author

commented Dec 21, 2011

Comment author: @gasche

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.

@vicuna

This comment has been minimized.

Copy link
Collaborator Author

commented Dec 22, 2011

Comment author: @protz

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...

@vicuna

This comment has been minimized.

Copy link
Collaborator Author

commented Dec 22, 2011

Comment author: @protz

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.

@vicuna

This comment has been minimized.

Copy link
Collaborator Author

commented Dec 23, 2011

Comment author: @johnwhitington

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
@vicuna

This comment has been minimized.

Copy link
Collaborator Author

commented Dec 23, 2011

Comment author: @protz

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

svn r11946

@vicuna vicuna closed this Sep 25, 2012

@vicuna vicuna added the feature-wish label Mar 20, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.