Namespace: joker.os

v1.0

Contents

• Summary
• Index
• Constants
• Variables
• Functions, Macros, and Special Forms

Summary

Provides filesystem, process, environment, and watcher helpers backed by the host operating system.

Index

• SIGABRT
• SIGALRM
• SIGFPE
• SIGHUP
• SIGILL
• SIGINT
• SIGKILL
• SIGPIPE
• SIGQUIT
• SIGSEGV
• SIGTERM
• SIGTRAP
• args
• chdir
• chmod
• chown
• chtimes
• clearenv
• close
• create
• create-temp
• cwd
• egid
• env
• euid
• exec
• executable
• exists?
• exit
• expand-env
• get-env
• gid
• groups
• hostname
• kill
• lchown
• link
• ls
• lstat
• mkdir
• mkdir-all
• mkdir-temp
• open
• pagesize
• path-separator?
• pid
• ppid
• read-link
• remove
• remove-all
• rename
• set-env
• sh
• sh-from
• signal
• start
• stat
• symlink
• temp-dir
• truncate
• uid
• unset-env
• user-cache-dir
• user-config-dir
• user-home-dir
• watch

Constants

Constants are variables with :const true in their metadata. Joker currently does not recognize them as special; as such, it allows redefining them or their values.

• SIGABRT

  Int v1.0.1

  SIGABRT

• SIGALRM

  Int v1.0.1

  SIGALRM

• SIGFPE

  Int v1.0.1

  SIGFPE

• SIGHUP

  Int v1.0.1

  SIGHUP

• SIGILL

  Int v1.0.1

  SIGILL

• SIGINT

  Int v1.0.1

  SIGINT

• SIGKILL

  Int v1.0.1

  SIGKILL

• SIGPIPE

  Int v1.0.1

  SIGPIPE

• SIGQUIT

  Int v1.0.1

  SIGQUIT

• SIGSEGV

  Int v1.0.1

  SIGSEGV

• SIGTERM

  Int v1.0.1

  SIGTERM

• SIGTRAP

  Int v1.0.1

  SIGTRAP

Variables

(None.)

Functions, Macros, and Special Forms

• args

  Function v1.0

  (args)
  

  Returns a sequence of the command line arguments, starting with the program name (normally, joker).

• chdir

  Function v1.0

  (chdir dirname)(chdir ^String dirname)
  

  Changes the current working directory to the named directory.

  show types

• chmod

  Function v1.0

  (chmod name mode)(chmod ^String name ^Int mode)
  

  Changes the mode of the named file to mode. If the file is a symbolic link, it changes the mode of the link's target.

  show types

• chown

  Function v1.0

  (chown name uid gid)(chown ^String name ^Int uid ^Int gid)
  

  Changes the numeric uid and gid of the named file. If the file is a symbolic link,
  it changes the uid and gid of the link's target. A uid or gid of -1 means to not change that value.

  show types

• chtimes

  Function v1.0

  (chtimes name atime mtime)(chtimes ^String name ^Time atime ^Time mtime)
  

  Changes the access and modification times of the named file, similar to the Unix utime() or utimes() functions.

  show types

• clearenv

  Function v1.0

  (clearenv)
  

  Deletes all environment variables.

• close

  Function v1.0

  (close f)(close ^File f)
  

  Closes the file, rendering it unusable for I/O.

  show types

• create

  Function v1.0

  (create name)(create ^String name)
  

  Creates the named file with mode 0666 (before umask), truncating it if it already exists.

  show types

• create-temp

  Function v1.0

  (create-temp dir pattern)(create-temp ^String dir ^String pattern)
  

  Creates a new temporary file in the directory dir, opens the file for reading and writing,
  and returns the resulting File. The filename is generated by taking pattern and adding a
  random string to the end. If pattern includes a "*", the random string replaces the last "*".
  If dir is the empty string, uses the default directory for temporary files (see joker.os/temp-dir).
  Multiple programs calling joker.os/make-temp-file simultaneously will not choose the same file.
  The caller can use (name f) to find the pathname of the file.
  It is the caller's responsibility to remove the file when no longer needed.

  show types

• cwd

  Function v1.0

  (cwd)
  

  Returns a rooted path name corresponding to the current directory. If the current directory can
  be reached via multiple paths (due to symbolic links), cwd may return any one of them.

• egid

  Function v1.0

  (egid)
  

  Returns the numeric effective group id of the caller.

• env

  Function v1.0

  (env)
  

  Returns a map representing the environment.

• euid

  Function v1.0

  (euid)
  

  Returns the numeric effective user id of the caller.

• exec

  Function v1.0

  (exec name opts)(exec ^String name ^Map opts)
  

  Executes name according to opts and waits for it to finish.
  
  A non-zero program exit is returned as data rather than thrown. Failure to
  start the process throws Error.
  
  opts may contain:
  :args - vector of arguments (all arguments must be strings),
  :dir - if specified, working directory will be set to this value before executing the program,
  :stdin - if specified, provides stdin for the program. Can be either a string or an IOReader.
  If it's a string, the string's content will serve as stdin for the program. IOReader can be, for example,
  *in* (in which case Joker's stdin will be redirected to the program's stdin) or the value returned by (joker.os/open).
  :stdout - if specified, must be an IOWriter. It can be, for example, *out* (in which case the program's stdout will be redirected
  to Joker's stdout) or the value returned by (joker.os/create).
  :stderr - the same as :stdout, but for stderr.
  Returns a map with:
  :success - whether or not the execution was successful,
  :err-msg (present iff :success is false) - string capturing error object returned by Go runtime
  :exit - exit code of program (or attempt to execute it),
  :out - string capturing stdout of the program (unless :stdout option was passed)
  :err - string capturing stderr of the program (unless :stderr option was passed).

  show types

• executable

  Function v1.0

  (executable)
  

  Returns the path name for the executable that started the current process.

• exists?

  Function v1.0

  (exists? path)(exists? ^String path)
  

  Returns true if file or directory with the given path exists. Otherwise returns false.

  show types

• exit

  Function v1.0

  (exit code)(exit ^Int code)
  (exit)
  

  Causes the current program to exit with the given status code (defaults to 0).

  show types

• expand-env

  Function v1.0

  (expand-env s)(expand-env ^String s)
  

  Replaces ${var} or $var in the string according to the values of the current environment variables.
  References to undefined variables are replaced by the empty string.

  show types

• get-env

  Function v1.0

  (get-env key)(get-env ^String key)
  

  Returns the value of the environment variable named by the key or nil if the variable is not present in the environment.

  show types

• gid

  Function v1.0

  (gid)
  

  Returns the numeric group id of the caller.

• groups

  Function v1.0

  (groups)
  

  Returns a list of the numeric ids of groups that the caller belongs to.

• hostname

  Function v1.0

  (hostname)
  

  Returns the host name reported by the kernel.

• kill

  Function v1.0.1

  (kill pid)(kill ^Int pid)
  

  Causes the process with the given PID to exit immediately.
  Only kills the process itself, not any other processes it may have started.

  show types

• lchown

  Function v1.0

  (lchown name uid gid)(lchown ^String name ^Int uid ^Int gid)
  

  Changes the numeric uid and gid of the named file. If the file is a symbolic link,
  it changes the uid and gid of the link itself.

  show types

• link

  Function v1.0

  (link oldname newname)(link ^String oldname ^String newname)
  

  Creates newname as a hard link to the oldname file.

  show types

• ls

  Function v1.0

  (ls dirname)(ls ^String dirname)
  

  Reads the directory named by dirname and returns a list of directory entries sorted by filename.
  Each entry is a map with the following keys:
  :name - name (String)
  :size - size in bytes (Int)
  :mode - mode (Int)
  :dir? - true if the file is a directory (Boolean)
  :modtime - modification time as Unix seconds (Int)

  show types

• lstat

  Function v1.0

  (lstat filename)(lstat ^String filename)
  

  Like stat, but if the file is a symbolic link, the result describes the symbolic link.

  show types

• mkdir

  Function v1.0

  (mkdir name perm)(mkdir ^String name ^Int perm)
  

  Creates a new directory with the specified name and permission bits.

  show types

• mkdir-all

  Function v1.0

  (mkdir-all name perm)(mkdir-all ^String name ^Int perm)
  

  Creates a directory named path, along with any necessary parents, and returns nil, or else throws an error.
  The permission bits perm (before umask) are used for all directories that mkdir-all creates.
  If path is already a directory, mkdir-all does nothing and returns nil.

  show types

• mkdir-temp

  Function v1.0

  (mkdir-temp dir pattern)(mkdir-temp ^String dir ^String pattern)
  

  Creates a new temporary directory in the directory dir.
  The directory name is generated by taking pattern and applying a random string to the end.
  If pattern includes a "*", the random string replaces the last "*".
  Returns the name of the new directory. If dir is the empty string,
  uses the default directory for temporary files (see joker.os/temp-dir).
  Multiple programs calling joker.os/mkdir-temp simultaneously will not choose the same directory.
  It is the caller's responsibility to remove the directory when no longer needed.

  show types

• open

  Function v1.0

  (open name)(open ^String name)
  

  Opens the named file for reading. If successful, the file can be used for reading;
  the associated file descriptor has mode O_RDONLY.

  show types

• pagesize

  Function v1.0

  (pagesize)
  

  Returns the underlying system's memory page size.

• path-separator?

  Function v1.0

  (path-separator? c)(path-separator? ^Char c)
  

  Reports whether c is a directory separator character.

  show types

• pid

  Function v1.0

  (pid)
  

  Returns the process id of the caller.

• ppid

  Function v1.0

  (ppid)
  

  Returns the process id of the caller's parent.

• read-link

  Function v1.0

  (read-link name)(read-link ^String name)
  

  Returns the destination of the named symbolic link.

  show types

• remove

  Function v1.0

  (remove name)(remove ^String name)
  

  Removes the named file or (empty) directory.

  show types

• remove-all

  Function v1.0

  (remove-all path)(remove-all ^String path)
  

  Removes path and any children it contains.
  
  It removes everything it can, then panics with the first error (if
  any) it encountered.

  show types

• rename

  Function v1.0

  (rename oldpath newpath)(rename ^String oldpath ^String newpath)
  

  Renames (moves) oldpath to newpath. If newpath already exists and is not a directory, rename replaces it.

  show types

• set-env

  Function v1.0

  (set-env key value)(set-env ^String key ^String value)
  

  Sets the value of the environment variable named by the key.

  show types

• sh

  Function v1.0

  (sh name & arguments)(sh ^String name & ^String arguments)
  

  Executes name with arguments and waits for it to finish.
  
  A non-zero program exit is returned as data rather than thrown. Failure to
  start the process throws Error. Returns a map with:
  :success - whether or not the execution was successful,
  :err-msg (present iff :success is false) - string capturing error object returned by Go runtime
  :exit - exit code of program (or attempt to execute it),
  :out - string capturing stdout of the program,
  :err - string capturing stderr of the program.

  show types

• sh-from

  Function v1.0

  (sh-from dir name & arguments)(sh-from ^String dir ^String name & ^String arguments)
  

  Executes name with arguments from working directory dir and waits for it to finish.
  
  Behaves like joker.os/sh except for the working directory. A non-zero program
  exit is returned as data; failure to start the process throws Error. Returns:
  :success - whether or not the execution was successful,
  :err-msg (present iff :success is false) - string capturing error object returned by Go runtime
  :exit - exit code of program (or attempt to execute it),
  :out - string capturing stdout of the program,
  :err - string capturing stderr of the program.

  show types

• signal

  Function v1.0.1

  (signal pid signal)(signal ^Int pid ^Int signal)
  

  Sends signal to the process with the given PID.

  show types

• start

  Function v1.0.1

  (start name opts)(start ^String name ^Map opts)
  

  Starts a new process with the program specified by name.
  opts is a map with the same keys as in exec.
  Does not wait for the process to finish and returns its PID. Throws Error if
  the process cannot be started.

  show types

• stat

  Function v1.0

  (stat filename)(stat ^String filename)
  

  Returns a map describing the named file. The info map has the following attributes:
  :name - base name of the file
  :size - length in bytes for regular files; system-dependent for others
  :mode - file mode bits
  :modtime - modification time
  :dir? - true if file is a directory

  show types

• symlink

  Function v1.0

  (symlink oldname newname)(symlink ^String oldname ^String newname)
  

  Creates newname as a symbolic link to oldname.

  show types

• temp-dir

  Function v1.0

  (temp-dir)
  

  Returns the default directory to use for temporary files.
  On Unix systems, it returns $TMPDIR if non-empty, else /tmp.
  On Windows, it uses GetTempPath, returning the first non-empty
  value from %TMP%, %TEMP%, %USERPROFILE%, or the Windows directory.
  The directory is neither guaranteed to exist nor have accessible permissions.

• truncate

  Function v1.0

  (truncate name size)(truncate ^String name ^Int size)
  

  Changes the size of the named file. If the file is a symbolic link, it changes the size of the link's target.

  show types

• uid

  Function v1.0

  (uid)
  

  Returns the numeric user id of the caller.

• unset-env

  Function v1.0

  (unset-env key)(unset-env ^String key)
  

  Unsets a single environment variable.

  show types

• user-cache-dir

  Function v1.0

  (user-cache-dir)
  

  Returns the default root directory to use for user-specific cached data.
  Users should create their own application-specific subdirectory within this one and use that.
  
  On Unix systems, it returns $XDG_CACHE_HOME as specified by https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
  if non-empty, else $HOME/.cache. On Darwin, it returns $HOME/Library/Caches. On Windows, it returns %LocalAppData%.
  On Plan 9, it returns $home/lib/cache.
  
  If the location cannot be determined (for example, $HOME is not defined), then it will throw an error.

• user-config-dir

  Function v1.0

  (user-config-dir)
  

  Returns the default root directory to use for user-specific configuration data.
  Users should create their own application-specific subdirectory within this one and use that.
  
  On Unix systems, it returns $XDG_CONFIG_HOME as specified by https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
  if non-empty, else $HOME/.config. On Darwin, it returns $HOME/Library/Application Support. On Windows, it returns %AppData%.
  On Plan 9, it returns $home/lib.
  
  If the location cannot be determined (for example, $HOME is not defined), then it will throw an error.

• user-home-dir

  Function v1.0

  (user-home-dir)
  

  Returns the current user's home directory.
  
  On Unix, including macOS, it returns the $HOME environment variable. On Windows, it returns %USERPROFILE%.
  On Plan 9, it returns the $home environment variable.

• watch

  Function v1.7.2

  (watch paths ch)(watch ^Seqable paths ^Channel ch)
  (watch paths ch opts)(watch ^Seqable paths ^Channel ch ^Map opts)
  

  Watches paths for file system changes, sends event maps to ch, and returns a
  zero-argument cancel function. paths must be Seqable and each path must be a
  string. opts may contain :recursive? to watch child directories recursively.
  
  Event maps have {:type :event :path path :ops ops}, where ops is a set
  containing one or more of :create, :write, :remove, :rename, and :chmod.
  Runtime watcher errors are sent as {:type :error :error error}.
  
  When :recursive? is true, existing child directories are watched and newly
  created child directories are added automatically. Calling the returned
  cancel function stops the watcher and closes ch. If ch is closed by the
  caller, the watcher stops sending and shuts itself down.

  show types