Module appdirs

Appdirs is a small module that finds the dirs for you to app in.

More specifically, appdirs contains a number of functions that will return the correct directory for the platform you are on. (All functions also allow you to override the platform.) Note that these directories are simply strings naming possible directories. You will need to ensure that the directory you wish to use is available yourself.

There are generally three procs for each type of directory. The first will return the base directory, whilst the other two will return the specific directory for a given application. Of the more specialised procs, one takes a TAppl object (initialised using the application() proc) and the other takes all the arguments required to create a TAppl object, creates and initialises one under the hood, and then uses that in this function. It is generally recommended to use the TAppl proc in most circumstances.

This module assumes that the available OSs are either Windows or Mac OSX, or otherwise a "UNIX-y" variant. This should cover most operating systems. There are no checks in place for systems that don't fall into the standard range of operating systems, but if you're in that situation you probably don't need this module.

Types

TAppl = object of TObject
  name*: string
  author*: string
  version*: string
  use_roaming*: bool

Procs

proc application(name: string; author: string = nil; version: string = nil; 
                 roaming: bool = false): TAppl {.raises: [], tags: [].}

Constructs a TAppl object with given args.

The only required arg is name. If author is not given, it defaults to name. This is only used on Windows machines, in which case the application directory will sit inside the author directory. On other platforms, author is ignored.

If version is given, it is appended to any resultant directory. This allows an application to have multiple versions installed on one computer.

The roaming arg is also for Windows systems only, and decides if the directory can be shared on any computer in a Windows network (roaming=true) or if it will be kept locally (roaming=false). Note that the cache and logs directory will always be kept locally.

proc user_data(roaming: bool = false; platform: string = nil): string {.
    raises: [], tags: [FReadEnv].}
Returns the generic user data directory for a given platform. The platform defaults to the current platform. 
proc user_data(appl: TAppl; platform: string = nil): string {.raises: [], 
    tags: [FReadEnv].}
Returns the user data directory for a given app for a given platform. The platform defaults to the current platform. 
proc user_data(name: string; author: string = nil; version: string = nil; 
               roaming: bool = false; platform: string = nil): string {.
    raises: [], tags: [FReadEnv].}
Gets the data directory given the details of an application. This proc creates an application from the arguments, and uses it to call the user_data(TAppl) proc. 
proc user_config(roaming: bool = false; platform: string = nil): string {.
    raises: [], tags: [FReadEnv].}
Returns the generic user config directory for a given platform. The platform defaults to the current platform. 
proc user_config(appl: TAppl; platform: string = nil): string {.raises: [], 
    tags: [FReadEnv].}
Returns the user config directory for a given app for a given platform. The platform defaults to the current platform. 
proc user_config(name: string; author: string = nil; version: string = nil; 
                 roaming: bool = false; platform: string = nil): string {.
    raises: [], tags: [FReadEnv].}
Gets the config directory given the details of an application. This proc creates an application from the arguments, and uses it to call the user_config(TAppl) proc. 
proc user_cache(appl: TAppl; force_cache: bool = true; platform: string = nil): string {.
    raises: [], tags: [FReadEnv].}

Gets the cache directory for a given application.

Note, on Windows there is no "official" cache directory, so instead this procedure returns this application's Application Data folder. If force_cache = true (the default) this procedure will add an artificial Cache directory inside the app's appdata folder. Otherwise, this just returns the user's app data directory.

On all other platforms, there is a cache directory to use.

proc user_cache(name: string; author: string = nil; version: string = nil; 
                roaming: bool = false; force_cache: bool = true; 
                platform: string = nil): string {.raises: [], tags: [FReadEnv].}
Gets the cache directory given the details of an application. This proc creates an application from the arguments, and uses it to call the user_cache(TAppl) proc. 
proc user_logs(appl: TAppl; force_logs: bool = true; platform: string = nil): string {.
    raises: [], tags: [FReadEnv].}

Gets the logs directory for a platform given application details.

Note that the only platform for which there is an official user logs directory is macosx. Otherwise, this returns the user data directory (for Windows) or the user cache directory (UNIX-y platforms), with a "logs" directory appended.

If force_logs is passed in and evaluates to false, this proc does not append the extra "logs" directory.

proc user_logs(name: string; author: string = nil; version: string = nil; 
               roaming: bool = false; force_logs: bool = true; 
               platform: string = nil): string {.raises: [], tags: [FReadEnv].}
Gets the logs directory given the details of an application. This proc creates an application from the arguments, and uses it to call the user_logs(TAppl) proc.
Generated: 2014-10-30 13:14:23 UTC