dcli library Null safety

Classes

Ansi
Helper class to assist in printing text to the console with a color. [...]
AnsiColor
Helper class to assist in printing text to the console with a color. [...]
ArgParser
A class for taking a list of raw command line arguments and parsing out options and flags from them.
ArgResults
The results of parsing a series of command line arguments using ArgParser.parse(). [...]
Ask
Class for ask and related code.
AskValidator
Base class for all AskValidators. You can add your own by extending this class.
AskValidatorIPAddress
Validates that input is a IP address By default both v4 and v6 addresses are valid Pass a version to limit the input to one or the other. If passed version must be ipv4 or ipv6.
Assets
This class provides access to 'assets' packaged in your application. [...]
BashShell
Provides a number of helper functions when dcli needs to interact with the Bash shell.
Column
Defined a column to sort by for the FileSort class.
DartProject
Encapsulates the idea of a dart project which is made up of a pubspec.yaml, dart files ....
DartScript
Used to manage a DCli script. [...]
DartSdk
The DartSdk provides access to a number of the dart sdk tools as well as details on the active sdk instance.
DCliPaths
platform specific names of the dcli commands.
DCliZone
This class is highly experimental - use at your own risk.
Dependency
Defines a pubspec.yaml dependency.
Digest
A message digest as computed by a Hash or HMAC function.
Env
Sets gets an environment variable for the current process. [...]
Executable
Represents a path to an executable listed in the 'executables' section of the pubsec.yaml.
Fetch
Types used by the fetch method.
FetchProgress
Passed to the progress method to indicate the current progress of a download.
FetchUrl
Used to describe a url that is being downloaded including the location where it is going to be stored.
FileSort
FileSort provides the ability to sort files based on their columns. [...]
FileSync
Provides a set of methods to read/write a file synchronisly. [...]
Find
Implementation for the _find function.
Format
provides a random collection of formatters EXPERIMENTAL
NamedLock
A NamedLock can be used to control access to a resource across processes and isolates. [...]
Option
A command-line option. [...]
OptionType
What kinds of values an option accepts.
ProcessDetails
Represents a running Process. As processes are transitory by the time you access these details the process may no longer be running.
ProcessHelper
EXPERIMENTAL [...]
Progress
central class that provides progress information about a running process.
PubCache
Used to locate and manipulate the dart pub cache [...]
PubSpec
Used to read a pubspec.yaml file
Remote
Provides remote access methods for posix based systems.
Settings
Holds all of the global settings for DCli including dcli paths and any global flags passed on the command line to DCli.
Shell
an abstract class which allows each shell (bash, zsh) to provide specific implementation of features required by DCli.
Terminal
Provides access to the Ansi Terminal.
UnknownShell
Used by dcli to interacte with the shell environment when we are unable to detect what shell is active. This may simply be the parent process of the dart app so not a shell at all.
Which
Returned from the which funtion to provide the details we discovered about appname.
ZshShell
Provides a number of helper functions when dcli needs to interact with the Zsh shell.

Mixins

PosixShell
Provides a number of helper functions for posix based shells. [...]
WindowsMixin
Common code for Windows shells.

Extensions

PlatformEx
Extensions for the Platform class
StringAsProcess
A set of String extensions that lets you execute the contents of a string as a command line application. [...]

Properties

env Env
Provides access to shell environment variables.
read / write
envs Map<String, String>
Returns a map of all the environment variables inherited from the parent as well as any changes made by calls to env[]=. [...]
read-only
fileList List<String>
returns the list of files and directories in the current directory. [...]
read-only
HOME String
returns the path to the OS specific HOME directory
read-only
PATH List<String>
Returns the list of directory paths that are contained in the OS's PATH environment variable. They are returned in the same order that they appear within the PATH environment variable (as order is important.)
read-only
pwd String
Returns the current working directory. [...]
read-only
rootPath String
returns the root path. On Linux and MacOS this will be '/' On Windows this will be r'C:'. The drive letter will depend on the drive of your present working directory (pwd).
read-only
separator String
Gets the path separator for the current platform. This is \ on Windows and / on other platforms (including the browser).
read-only

Functions

absolute(String part1, [String? part2, String? part3, String? part4, String? part5, String? part6, String? part7]) String
Returns a new path with the given path parts appended to current. [...]
ask(String prompt, {bool toLower = false, bool hidden = false, bool required = true, String? defaultValue, AskValidator validator = Ask.dontCare}) String
Reads a line of text from stdin with an optional prompt. [...]
backupFile(String pathToFile, {bool ignoreMissing = false}) → void
Provide a very simple mechanism to backup a single file. [...]
basename(String path) String
Gets the part of path after the last separator. [...]
basenameWithoutExtension(String path) String
Gets the part of path after the last separator, and without any trailing file extension. [...]
black(String text, {AnsiColor background = AnsiColor.white, bool bold = true}) String
Wraps the passed text with the ANSI escape sequence for the color red. Use this to control the color of text when printing to the console. [...]
blue(String text, {AnsiColor background = AnsiColor.none, bool bold = true}) String
Wraps the passed text with the ANSI escape sequence for the color red. Use this to control the color of text when printing to the console. [...]
calculateHash(String path) Digest
Calculates the sha256 hash of a file's content. [...]
canonicalize(String path) String
Canonicalizes path. [...]
cat(String path, {LineAction stdout = print}) → void
Prints the contents of the file located at path to stdout. [...]
chmod(int permission, String path) → void
Wrapper for the linux chmod command. [...]
chown(String path, {String? user, String? group, bool recursive = true}) → void
Provides similar functionality to the posix chmod command. [...]
confirm(String prompt, {bool? defaultValue}) bool
confirm is a specialized version of ask that returns true or false based on the value entered. [...]
copy(String from, String to, {bool overwrite = false}) → void
Copies the file from to the path to. [...]
copyTree(String from, String to, {bool overwrite = false, bool includeHidden = false, bool recursive = true, bool filter(String file) = _allowAll}) → void
Copies the contents of the from directory to the to path with an optional filter. [...]
createDir(String path, {bool recursive = false}) String
Creates a directory as described by path. Path may be a single path segment (e.g. bin) or a full or partial tree (e.g. /usr/bin) [...]
createTempDir() String
Creates a temporary directory under the system temp folder. The temporary directory name is formed from a uuid. It is your responsiblity to delete the directory once you have finsihed with it.
createTempFile({String? suffix}) String
Generates a temporary filename in the system temp directory that is guaranteed to be unique. [...]
createTempFilename({String? suffix, String? pathToTempDir}) String
Generates a temporary filename in pathToTempDir or if inTempDir os not passed then in the system temp directory. The generated filename is is guaranteed to be globally unique. [...]
cyan(String text, {AnsiColor background = AnsiColor.none, bool bold = true}) String
Wraps the passed text with the ANSI escape sequence for the color red. Use this to control the color of text when printing to the console. [...]
delete(String path, {bool ask = false}) → void
Deletes the file at path. [...]
deleteDir(String path, {bool recursive = true}) → void
Deletes the directory located at path. [...]
Deletes the symlink at linkPath [...]
devNull(String? line) → void
devNull is a convenience function which you can use if you want to ignore the output of a LineAction. Its typical useage is a forEach where you don't want to see any stdout but you still want to see errors printed to stderr. [...]
dirname(String path) String
Gets the part of path before the last separator. [...]
echo(String text, {bool newline = false}) → void
Writes text to stdout including a newline. [...]
equals(String path1, String path2) bool
Returns true if path1 points to the same location as path2, and false otherwise. [...]
exists(String path, {bool followLinks = true}) bool
Returns true if the given path exists. It may be a file, directory or link. [...]
extension(String path, [int level = 1]) String
Gets the file extension of path: the portion of basename from the last . to the end (including the . itself). [...]
fetch({required String url, required String saveToPath, HttpMethod method = Fetch.get, OnFetchProgress fetchProgress = _devNull}) → void
Fetches the given resource at the passed url. [...]
fetchMultiple({required List<FetchUrl> urls}) → void
Fetches the list of of resources indicated by urls; [...]
fileLength(String pathToFile) int
Returns the length of the file at pathToFile in bytes.
find(String pattern, {bool caseSensitive = false, bool recursive = true, bool includeHidden = false, String workingDirectory = '.', Progress? progress, List<FileSystemEntityType> types = const [Find.file]}) Progress
Returns the list of files in the current and child directories that match the passed glob pattern. [...]
green(String text, {AnsiColor background = AnsiColor.none, bool bold = true}) String
Wraps the passed text with the ANSI escape sequence for the color red. Use this to control the color of text when printing to the console. [...]
grey(String text, {double level = 0.5, AnsiColor background = AnsiColor.none, bool bold = true}) String
Wraps the passed text with the ANSI escape sequence for the color red. Use this to control the color of text when printing to the console. [...]
Returns count lines from the file at path. [...]
isAbsolute(String path) bool
Returns true if path is an absolute path and false if it is a relative path. [...]
isDirectory(String path) bool
Returns true if the given path is a directory. [...]
isEmpty(String pathToDirectory) bool
Returns true if the passed pathToDirectory is an empty directory. For large directories this operation can be expensive.
isExecutable(String path) bool
checks if the passed path (a file or directory) is executable by the user that owns this process
isFile(String path) bool
Returns true if the given path points to a file. [...]
Returns true if the given path is a symlink [...]
isOnPATH(String path) bool
Tests if the given path is contained in the OS's PATH environment variable. An canonicalized match of path is made against each path on the OS's path.
isReadable(String path) bool
checks if the passed path (a file or directory) is readable by the user that owns this process
isRelative(String path) bool
Returns true if path is a relative path and false if it is absolute. On POSIX systems, absolute paths start with a / (forward slash). On Windows, an absolute path starts with \\, or a drive letter followed by :/ or :\.
isRootRelative(String path) bool
Returns true if path is a root-relative path and false if it's not. [...]
isWithin(String parent, String child) bool
Returns true if child is a path beneath parent, and false otherwise. [...]
isWritable(String path) bool
checks if the passed path (a file or directory) is writable by the user that owns this process
join(String part1, [String? part2, String? part3, String? part4, String? part5, String? part6, String? part7, String? part8]) String
Joins the given path parts into a single path using the current platform's separator. Example: [...]
joinAll(Iterable<String> parts) String
Joins the given path parts into a single path using the current platform's separator. Example: [...]
lastModified(String path) DateTime
Returns the datetime the path was last modified [...]
magenta(String text, {AnsiColor background = AnsiColor.none, bool bold = true}) String
Wraps the passed text with the ANSI escape sequence for the color red. Use this to control the color of text when printing to the console. [...]
Displays a menu with each of the provided options, prompts the user to select an option and returns the selected option. [...]
move(String from, String to, {bool overwrite = false}) → void
Moves the file from to the location to. [...]
moveDir(String from, String to) → void
Moves or renames the from directory to the to the to path. [...]
moveTree(String from, String to, {bool overwrite = false, bool includeHidden = false, bool filter(String file) = _allowAll}) → void
Recursively moves the contents of the from directory to the to the to path with an optional filter. [...]
normalize(String path) String
Normalizes path, simplifying it by handling .., and ., and removing redundant path separators whenever possible. [...]
orange(String text, {AnsiColor background = AnsiColor.none, bool bold = true}) String
Wraps the passed text with the ANSI escape sequence for the color red. Use this to control the color of text when printing to the console. [...]
printerr(String? line) → void
printerr provides the equivalent functionality to the standard Dart print function but instead writes the output to stderr rather than stdout. [...]
privatePath(String part1, [String? part2, String? part3, String? part4, String? part5, String? part6, String? part7]) String
Removes the users home directory from a path replacing it with ~
read(String path, {String delim = '\n'}) Progress
Reads lines from the file at path. [...]
readStdin() Progress
Read lines from stdin
red(String text, {AnsiColor background = AnsiColor.none, bool bold = true}) String
Wraps the passed text with the ANSI escape sequence for the color red. Use this to control the color of text when printing to the console. [...]
relative(String path, {String? from}) String
Attempts to convert path to an equivalent relative path from the current directory. [...]
replace(String path, Pattern existing, String replacement, {bool all = false}) int
Does an insitu replacement on the file located at path. [...]
Resolves the a symbolic link pathToLink to the ultimate target path. [...]
restoreFile(String pathToFile, {bool ignoreMissing = false}) → void
Designed to work with backupFile to restore a file from backup. The existing file is deleted and restored from the .bak/.bak file created when you called backupFile. [...]
rootPrefix(String path) String
Returns the root of path, if it's absolute, or the empty string if it's relative. [...]
run(String commandLine, {bool runInShell = false, bool nothrow = false, bool privileged = false, String? workingDirectory, bool extensionSearch = true}) int?
Runs the given cli commandLine writing any output from both stdout and stderr to the console. [...]
setExtension(String path, String extension) String
Returns path with the trailing extension set to extension. [...]
setLastModifed(String path, DateTime lastModified) → void
Sets the last modified datetime on the given the path. [...]
showEditor(String path) → void
Launches the systems default cli editor on Linux and MacOS using the EDITOR environment variable. [...]
sleep(int duration, {Interval interval = Interval.seconds}) → void
sleeps for the provided duration of the given interval. [...]
split(String path) List<String>
Splits path into its components using the current platform's separator. [...]
start(String commandLine, {Progress? progress, bool runInShell = false, bool detached = false, bool terminal = false, bool nothrow = false, bool privileged = false, String? workingDirectory, bool extensionSearch = true}) Progress
Allows you to execute a cli commandLine. [...]
startFromArgs(String command, List<String> args, {Progress? progress, bool runInShell = false, bool detached = false, bool terminal = false, bool privileged = false, bool nothrow = false, String? workingDirectory, bool extensionSearch = true}) Progress
Allows you to execute a command by passing a command and a list of args in args. [...]
stat(String path) FileStat
Returns a FileStat instance describing the file or directory located by path.
Creates a link at linkPath which points to an existing file or directory at existingPath [...]
tail(String path, int lines) Progress
Returns count lines from the end of the file at path. [...]
touch(String path, {bool create = false}) String
Updates the last modified time stamp of a file. [...]
translateAbsolutePath(String absolutePath, {String? workingDirectory, Context? context}) String
Windows, an absolute path starts with \\, or a drive letter followed by :/ or :\. This method will strip the prefix so the path start with a \ or / and the prepend the drive letter so that it becomes a valid path. If the absolutePath doesn't contain a drive letter then we take the drive letter from the workingDirectory. If this is a linux absolute path it is returned unchanged. [...]
truepath(String part1, [String? part2, String? part3, String? part4, String? part5, String? part6, String? part7]) String
truepath creates an absolute and normalized path. [...]
waitForEx<T>(Future<T> future) → T
Wraps the standard cli waitFor but rethrows any exceptions with a repaired stacktrace. [...]
which(String appname, {bool first = true, bool verbose = false, bool extensionSearch = true, Progress? progress}) Which
Searches the PATH for the location of the application give by appname. [...]
white(String text, {AnsiColor background = AnsiColor.none, bool bold = true}) String
Wraps the passed text with the ANSI escape sequence for the color red. Use this to control the color of text when printing to the console. [...]
withFileProtection<R>(List<String> protected, R action(), {String? workingDirectory}) → R
EXPERIMENTAL - use with caution and the api may change. [...]
withOpenFile<R>(String pathToFile, R action(FileSync), {FileMode fileMode = FileMode.writeOnlyAppend}) → R
Opens a File and calls action passing in the open file. When action completes the file is closed. Use this method in preference to directly callling FileSync()
withoutExtension(String path) String
Removes a trailing extension from the last part of path. [...]
withTempDir<R>(R action(String tempDir), {bool keep = false}) → R
Creates a temp directory and then calls action. Once action completes the temporary directory will be deleted. [...]
withTempFile<R>(R action(String tempFile), {String? suffix, String? pathToTempDir, bool create = true, bool keep = false}) → R
Creates a temp file and then calls action. [...]
yellow(String text, {AnsiColor background = AnsiColor.none, bool bold = true}) String
Wraps the passed text with the ANSI escape sequence for the color red. Use this to control the color of text when printing to the console. [...]

Enums

FetchStatus
Used by FetchProgress to indicate the progress of a download.
Interval
Allows you to specify how the duration argument to sleep is interpreted.
SortDirection
Sets the sort direction.
TableAlignment
Used by Format.row to control the alignment of each column in the table.
TerminalClearMode
Modes available when clearing a screen or line. [...]

Typedefs

DCliZonePrintErr = void Function(String?)
callback used when overloadin printerr in a DCliZone.
OnFetchProgress = void Function(FetchProgress progress)
Typedef for the progress call back used by the fetch function.
RunPrivileged = void Function()
Typedef for the withPrivileges function.

Exceptions / Errors

ArgParserException
An exception thrown by ArgParser.
AskValidatorException
Thrown when an AskValidator detects an invalid input.
AssetException
Throw when trying to access an asset and something goes wrong.
AssetNoFoundException
Thrown if you try to load an asset that can't be found.
BackupFileException
Thrown by the backupFile function when the file to be backed up is missing.
CatException
Thrown if the cat function encouters an error.
CDException
Throw when the cd function encounters an error.
ChModException
Thrown if the chmod function encounters an error.
ChOwnException
Thrown if the chown function encounters an error.
CopyException
Throw when the copy function encounters an error.
CopyTreeException
Throw when the copy function encounters an error.
CreateDirException
Thrown when the function createDir encounters an error
DartProjectException
Exception for issues with DartProjects.
DCliException
Base class for all DCli exceptions.
DeleteDirException
Throw when deleteDir function encounters an error
DeleteException
Thrown when the delete function encounters an error
FetchException
Throw when an error occurs fetching a resource.
FileNotFoundException
Thrown when a file doesn't exist
LockException
MoveDirException
Thrown when the moveDir function encouters an error.
MoveException
Thrown when the move function encouters an error.
MoveTreeException
Thrown when the moveTree function encouters an error.
NotAFileException
Thrown when a path is not a file.
PathException
An exception class that's thrown when a path operation is unable to be computed accurately.
PopException
Thrown when the pop function encouters an error.
PushException
Thrown when the push function encouters an error.
ReadException
Thrown when the read function encouters an error.
RestoreFileException
Thrown by the restoreFile function when the backup file is missing.
RunException
ShellException
Thrown when an exception occurs in the Shell detection and support methods.
TemplateNotFoundException
The requested DCli template does not exists.
TouchException
thrown when the touch function encounters an exception