mirror of https://github.com/sbt/sbt.git
Streamline and update help messages for built-in commands
This commit is contained in:
Indrajit Raychaudhuri
parent
62355c3e1e
commit
15177e92a2
|
|
@ -47,8 +47,8 @@ object CommandSupport
|
|||
val evalBrief = (EvalCommand + " <expression>", "Evaluates the given Scala expression and prints the result and type.")
|
||||
val evalDetailed =
|
||||
EvalCommand + """ <expression>
|
||||
Evaluates the given Scala expression and prints the result and type.
|
||||
"""
|
||||
|
||||
Evaluates the given Scala expression and prints the result and type."""
|
||||
|
||||
def showHelp = Help(ShowCommand, (ShowCommand + " <key>", actBrief), actDetailed)
|
||||
def actBrief = "Displays the result of evaluating the setting or task associated with 'key'."
|
||||
|
|
@ -65,21 +65,23 @@ ShowCommand + """ <setting>
|
|||
val LastGrepCommand = "last-grep"
|
||||
|
||||
val lastGrepBrief = (LastGrepCommand + " <pattern> <key>", "Shows lines from the last output for 'key' that match 'pattern'.")
|
||||
val lastGrepDetailed =
|
||||
val lastGrepDetailed =
|
||||
LastGrepCommand + """ <pattern> [key]
|
||||
|
||||
<pattern> is a regular expression interpreted by java.util.Pattern.
|
||||
Lines that match 'pattern' from the last streams output associated with the key are displayed.
|
||||
If no key is specified, the global streams output is used.
|
||||
See also """ + LastCommand + "."
|
||||
|
||||
See also '""" + LastCommand + "'."
|
||||
|
||||
val lastBrief = (LastCommand + " <key>", "Prints the last output associated with 'key'.")
|
||||
val lastDetailed =
|
||||
val lastDetailed =
|
||||
LastCommand + """ <key>
|
||||
|
||||
Redisplays the last streams output associated with the key (typically a task key).
|
||||
If no key is specified, the global streams output is displayed.
|
||||
See also """ + LastGrepCommand + "."
|
||||
|
||||
See also '""" + LastGrepCommand + "'."
|
||||
|
||||
val InspectCommand = "inspect"
|
||||
val inspectBrief = (InspectCommand + " <key>", "Prints the value for 'key', the defining scope, delegates, related definitions, and dependencies.")
|
||||
|
|
@ -88,7 +90,7 @@ InspectCommand + """ <key>
|
|||
|
||||
For a plain setting, the value bound to the key argument is displayed using its toString method.
|
||||
Otherwise, the type of task ("Task" or "Input task") is displayed.
|
||||
|
||||
|
||||
"Dependencies" shows the settings that this setting depends on.
|
||||
"Reverse dependencies" shows the settings that depend on this setting.
|
||||
|
||||
|
|
@ -97,9 +99,8 @@ InspectCommand + """ <key>
|
|||
"Delegates" shows the scopes that are searched for the key.
|
||||
"Provided by" shows the scope that contained the value returned for the key.
|
||||
|
||||
"Related" shows all of the scopes in which the key is defined.
|
||||
"""
|
||||
|
||||
"Related" shows all of the scopes in which the key is defined."""
|
||||
|
||||
val SetCommand = "set"
|
||||
val setBrief = (SetCommand + " <setting-expression>", "Evaluates the given Setting and applies to the current project.")
|
||||
val setDetailed =
|
||||
|
|
@ -111,13 +112,12 @@ SetCommand + """ <setting-expression>
|
|||
3) Re-evaluates the build's settings.
|
||||
|
||||
This command does not rebuild the build definitions, plugins, or configurations.
|
||||
It does not automatically persist the setting.
|
||||
This is done by running 'session save' or 'session save-all'.
|
||||
"""
|
||||
It does not automatically persist the setting(s) either.
|
||||
To persist the setting(s), run 'session save' or 'session save-all'."""
|
||||
|
||||
def SessionCommand = "session"
|
||||
def sessionBrief = (SessionCommand + " ...", "Manipulates session settings. For details, run 'help " + SessionCommand + "'..")
|
||||
|
||||
def sessionBrief = (SessionCommand + " <session-command>", "Manipulates session settings. For details, run 'help " + SessionCommand + "'.")
|
||||
|
||||
/** The command name to terminate the program.*/
|
||||
val TerminateAction: String = Exit
|
||||
|
||||
|
|
@ -126,14 +126,15 @@ SetCommand + """ <setting-expression>
|
|||
def tasksPreamble = """
|
||||
This is a list of tasks defined for the current project.
|
||||
It does not list the scopes the tasks are defined in; use the 'inspect' command for that.
|
||||
Tasks produce values. Use the 'show' command to run the task and print the resulting value.
|
||||
"""
|
||||
Tasks produce values. Use the 'show' command to run the task and print the resulting value."""
|
||||
|
||||
def tasksBrief = "Displays the tasks defined for the current project."
|
||||
def tasksDetailed = TasksCommand + "\n\t" + tasksBrief
|
||||
def tasksDetailed = "Displays the tasks defined directly or indirectly for the current project."
|
||||
|
||||
def helpBrief = (HelpCommand + " command*", "Displays this help message or prints detailed help on requested commands.")
|
||||
def helpDetailed = "If an argument is provided, this prints detailed help for that command.\nOtherwise, this prints a help summary."
|
||||
def helpBrief = (HelpCommand + " [command]*", "Displays this help message or prints detailed help on requested commands.")
|
||||
def helpDetailed = """
|
||||
If an argument is provided, this prints detailed help for that command.
|
||||
Otherwise, this prints a help summary."""
|
||||
|
||||
def aboutBrief = "Displays basic information about sbt and the build."
|
||||
def aboutDetailed = aboutBrief
|
||||
|
|
@ -142,20 +143,25 @@ Tasks produce values. Use the 'show' command to run the task and print the resu
|
|||
def projectDetailed =
|
||||
ProjectCommand +
|
||||
"""
|
||||
|
||||
Displays the name of the current project.
|
||||
|
||||
""" + ProjectCommand + """ name
|
||||
|
||||
Changes to the project with the provided name.
|
||||
This command fails if there is no project with the given name.
|
||||
|
||||
""" + ProjectCommand + """ /
|
||||
|
||||
Changes to the initial project.
|
||||
|
||||
""" + ProjectCommand + """ ..
|
||||
|
||||
Changes to the parent project of the current project.
|
||||
If there is no parent project, the current project is unchanged.
|
||||
|
||||
Use n+1 dots to change to the nth parent.
|
||||
For example, 'project ....' is equivalent to three consecutive 'project ..' commands.
|
||||
"""
|
||||
For example, 'project ....' is equivalent to three consecutive 'project ..' commands."""
|
||||
|
||||
def projectsBrief = projectsDetailed
|
||||
def projectsDetailed = "Displays the names of available projects."
|
||||
|
|
@ -168,19 +174,19 @@ ProjectCommand +
|
|||
|
||||
def ReadCommand = "<"
|
||||
def ReadFiles = " file1 file2 ..."
|
||||
def ReadBrief = (ReadCommand + " file*", "Reads command lines from the provided files.")
|
||||
def ReadDetailed = ReadCommand + ReadFiles +
|
||||
"""
|
||||
def ReadBrief = (ReadCommand + " <file>*", "Reads command lines from the provided files.")
|
||||
def ReadDetailed =
|
||||
ReadCommand + ReadFiles + """
|
||||
|
||||
Reads the lines from the given files and inserts them as commands.
|
||||
Any lines that are empty or that start with # are ignored.
|
||||
All empty lines or the ones that start with '#' are ignored.
|
||||
If a file does not exist or is not readable, this command fails.
|
||||
|
||||
All commands are read before any are executed.
|
||||
Therefore, if any file is not readable, no commands from any files will be
|
||||
run.
|
||||
All the lines from all the files are read before any of the commands
|
||||
are executed. Thus, if any file is not readable, none of commands
|
||||
from any of the files (even the existing ones) will be run.
|
||||
|
||||
You probably need to escape this command if entering it at your shell.
|
||||
"""
|
||||
You probably need to escape this command if entering it at your shell."""
|
||||
|
||||
def DefaultsCommand = "add-default-commands"
|
||||
def DefaultsBrief = (DefaultsCommand, DefaultsDetailed)
|
||||
|
|
@ -191,44 +197,48 @@ ProjectCommand +
|
|||
def RebootBrief = (RebootSummary, "Reboots sbt and then executes the remaining commands.")
|
||||
def RebootDetailed =
|
||||
RebootSummary + """
|
||||
|
||||
This command is equivalent to exiting sbt, restarting, and running the
|
||||
remaining commands with the exception that the jvm is not shut down.
|
||||
If 'full' is specified, the `project/boot` directory is deleted before
|
||||
restarting. This forces an update of sbt and Scala and is useful when
|
||||
working with development versions of sbt or Scala.
|
||||
"""
|
||||
remaining commands with the exception that the JVM is not shut down.
|
||||
|
||||
If 'full' is specified, the boot directory (`~/.sbt/boot` by default)
|
||||
is deleted before restarting. This forces an update of sbt and Scala
|
||||
and is useful when working with development versions of sbt or Scala."""
|
||||
|
||||
def Multi = ";"
|
||||
def MultiBrief = ("( " + Multi + " command )+", "Runs the provided semicolon-separated commands.")
|
||||
def MultiBrief = (Multi + " <command> (" + Multi + " <command>)*", "Runs the provided semicolon-separated commands.")
|
||||
def MultiDetailed =
|
||||
Multi + " command1 " + Multi + """ command2 ...
|
||||
Runs the specified commands.
|
||||
"""
|
||||
|
||||
Runs the specified commands."""
|
||||
|
||||
def AppendCommand = "append"
|
||||
def AppendLastBrief = (AppendCommand + " command", AppendLastDetailed)
|
||||
def AppendLastDetailed = "Appends `command` to list of commands to run."
|
||||
def AppendLastBrief = (AppendCommand + " <command>", AppendLastDetailed)
|
||||
def AppendLastDetailed = "Appends 'command' to list of commands to run."
|
||||
|
||||
val AliasCommand = "alias"
|
||||
def AliasBrief = (AliasCommand, "Adds, removes, or prints command aliases.")
|
||||
def AliasDetailed =
|
||||
AliasCommand + """
|
||||
|
||||
Prints a list of defined aliases.
|
||||
|
||||
""" +
|
||||
AliasCommand + """ name
|
||||
|
||||
Prints the alias defined for `name`.
|
||||
|
||||
""" +
|
||||
AliasCommand + """ name=value
|
||||
|
||||
Sets the alias `name` to `value`, replacing any existing alias with that name.
|
||||
Whenever `name` is entered, value is run.
|
||||
If any arguments are provided to `name`, those are appended to `value`.
|
||||
Whenever `name` is entered, the corresponding `value` is run.
|
||||
If any argument is provided to `name`, it is appended as argument to `value`.
|
||||
|
||||
""" +
|
||||
AliasCommand + """ name=
|
||||
Removes the alias for `name`.
|
||||
"""
|
||||
|
||||
Removes the alias for `name`."""
|
||||
|
||||
def Discover = "discover"
|
||||
def DiscoverBrief = (DiscoverSyntax, "Finds annotated classes and subclasses.")
|
||||
|
|
@ -237,15 +247,15 @@ AliasCommand + """ name=
|
|||
DiscoverSyntax + """
|
||||
|
||||
Looks for public, concrete classes that match the requested query using the current sbt.inc.Analysis instance.
|
||||
|
||||
|
||||
-module
|
||||
Specifies whether modules (true) or classes (false) are found.
|
||||
The default is classes/traits (false).
|
||||
|
||||
|
||||
-sub
|
||||
Specifies comma-separated class names.
|
||||
Classes that have one or more of these classes as an ancestor are included in the resulting list.
|
||||
|
||||
|
||||
-annot
|
||||
Specifies comma-separated annotation names.
|
||||
Classes with one or more of these annotations on the class or one of its non-private methods are included in the resulting list.
|
||||
|
|
@ -258,11 +268,11 @@ DiscoverSyntax + """
|
|||
CompileSyntax + """
|
||||
|
||||
Incrementally compiles Scala and Java sources.
|
||||
|
||||
|
||||
<paths> are explicit paths separated by the platform path separator.
|
||||
|
||||
|
||||
The specified output path will contain the following directory structure:
|
||||
|
||||
|
||||
scala_<version>/
|
||||
classes/
|
||||
cache/
|
||||
|
|
@ -272,7 +282,7 @@ CompileSyntax + """
|
|||
"""
|
||||
|
||||
val FailureWall = "---"
|
||||
|
||||
|
||||
def Load = "load"
|
||||
def LoadLabel = "a project"
|
||||
def LoadCommand = "load-commands"
|
||||
|
|
@ -294,15 +304,17 @@ CompileSyntax + """
|
|||
def OnFailureBrief = (OnFailure + " command", "Registers 'command' to run if a command fails.")
|
||||
def OnFailureDetailed =
|
||||
OnFailure + """ command
|
||||
|
||||
Registers 'command' to run when a command fails to complete normally.
|
||||
Only one failure command may be registered at a time, so this
|
||||
command replaces the previous command if there is one.
|
||||
The failure command is reset when it runs, so it must be added again
|
||||
if desired.
|
||||
"""
|
||||
|
||||
Only one failure command may be registered at a time, so this command
|
||||
replaces the previous command if there is one.
|
||||
|
||||
The failure command resets when it runs once, so it must be added
|
||||
again if desired."""
|
||||
|
||||
def IfLast = "iflast"
|
||||
def IfLastBrief = (IfLast + " command", IfLastCommon)
|
||||
def IfLastBrief = (IfLast + " <command>", IfLastCommon)
|
||||
def IfLastCommon = "If there are no more commands after this one, 'command' is run."
|
||||
def IfLastDetailed =
|
||||
IfLast + """ command
|
||||
|
|
@ -327,4 +339,4 @@ load-commands -base ~/.sbt/commands
|
|||
< .sbtrc
|
||||
Runs commands from ~/.sbtrc and ./.sbtrc if they exist
|
||||
"""
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ object SessionSettings
|
|||
|
||||
def reapply(session: SessionSettings, s: State): State =
|
||||
BuiltinCommands.reapply(session, Project.structure(s), s)
|
||||
|
||||
|
||||
def clearSettings(s: State): State =
|
||||
withSettings(s)(session => reapply(session.copy(append = session.append - session.current), s))
|
||||
def clearAllSettings(s: State): State =
|
||||
|
|
@ -91,7 +91,7 @@ object SessionSettings
|
|||
val adjustedLines = if(appendTo.isFile && hasTrailingBlank(IO readLines appendTo) ) baseAppend else "" +: baseAppend
|
||||
IO.writeLines(appendTo, adjustedLines, append = true)
|
||||
}
|
||||
def hasTrailingBlank(lines: Seq[String]) = lines.takeRight(1).exists(_.trim.isEmpty)
|
||||
def hasTrailingBlank(lines: Seq[String]) = lines.takeRight(1).exists(_.trim.isEmpty)
|
||||
def printAllSettings(s: State): State =
|
||||
withSettings(s){ session =>
|
||||
for( (ref, settings) <- session.append if !settings.isEmpty) {
|
||||
|
|
@ -117,23 +117,27 @@ Manipulates session settings, which are temporary settings that do not persist p
|
|||
Valid commands are:
|
||||
|
||||
clear, clear-all
|
||||
|
||||
Removes temporary settings added using 'set' and re-evaluates all settings.
|
||||
For 'clear', only the settings defined for the current project are cleared.
|
||||
For 'clear-all', all settings in all projects are cleared.
|
||||
|
||||
list, list-all
|
||||
|
||||
Prints a numbered list of session settings defined.
|
||||
The numbers may be used to remove individual settings or ranges of settings using 'remove'.
|
||||
For 'list', only the settings for the current project are printed.
|
||||
For 'list-all', all settings in all projets are printed.
|
||||
|
||||
remove <range-spec>
|
||||
|
||||
<range-spec> is a comma-separated list of individual numbers or ranges of numbers.
|
||||
For example, 'remove 1,3,5-7'.
|
||||
The temporary settings at the given indices for the current project are removed and all settings are re-evaluated.
|
||||
Use the 'list' command to see a numbered list of settings for the current project.
|
||||
|
||||
save, save-all
|
||||
|
||||
Makes the session settings permanent by writing them to a '.sbt' configuration file.
|
||||
For 'save', only the current project's settings are saved (the settings for other projects are left alone).
|
||||
For 'save-all', the session settings are saved for all projects.
|
||||
|
|
@ -165,4 +169,4 @@ save, save-all
|
|||
case c: Clear => if(c.all) clearAllSettings(s) else clearSettings(s)
|
||||
case r: Remove => removeSettings(s,r.ranges)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue