{"size": 2139, "ext": "scrbl", "max_stars_repo_path": "scribblings/config.scrbl", "max_stars_repo_name": "alan-turing-institute/whatnow", "max_stars_repo_stars_event_min_datetime": "2021-01-04T15:12:59.000Z", "max_stars_repo_stars_event_max_datetime": "2021-01-04T15:12:59.000Z", "max_issues_repo_path": "scribblings/config.scrbl", "max_issues_repo_name": "alan-turing-institute/whatnow", "max_issues_repo_issues_event_min_datetime": "2020-08-17T12:21:06.000Z", "max_issues_repo_issues_event_max_datetime": "2021-08-25T14:13:59.000Z", "max_forks_repo_path": "scribblings/config.scrbl", "max_forks_repo_name": "alan-turing-institute/whatnow", "max_forks_repo_forks_event_min_datetime": null, "max_forks_repo_forks_event_max_datetime": null}
{"max_stars_count": 1, "max_issues_count": 12, "max_forks_count": null, "avg_line_length": 36.8793103448, "max_line_length": 109, "alphanum_fraction": 0.7568957457}
#lang scribble/manual

@require[
  @for-label[racket/base]
  @for-label[basedir]
  @for-label["../config.rkt"]]
             
@title{Configuration}

There are three kinds of configuration data in Whatnow:
@itemlist[#:style 'ordered

  @item{Defaults for various program options.}

  @item{Data that is required for a local installation of Whatnow, such as the
  specifics of where to find the various servers. This kind of data is held in
  Racket modules. See @secref["local-configuration"].}

  @item{Data that should not be made public, such as authentication keys. These
  settings are stored in configuration files that must be created by the user
  and stored in a directory following the XDG standard. See @secref["secrets"].}
  ]   


@section[#:tag "local-configuration"]{Local configuration}

@defmodule[whatnow/api/local-config]{The
@racketmodname[whatnow/api/local-config] library exports settings specific to a
local installation.}

@defthing[FORECAST-SERVER string? #:value "api.forecastapp.com"]{The web address of the Forecast API servier}

@section[#:tag "secrets"]{Secrets}

@defmodule[whatnow/config]{The @racketmodname[whatnow/config] library retrieves
local configuration information from a config file. This information is mainly
account authentication details which should not be stored with the source code.}

@defstruct*[server-account ([id string?] [token string?]) #:transparent]{A
structure type for internet @deftech{server account}s. A @tech{server account}
consists of an account identifier and an authentication token. The details of
@racket{id} and @racket{token} are specific to the server.}

@defproc[(config-get-accounts [secret-file-name string? "secrets.txt"]) (listof
pair?)]{Retrieve secrets from a configuration file. The configuration file is
looked for in the directories specified by the
@secref["XDG_Basedir_Specification" #:doc '(lib "basedir/basedir.scrbl")] using
@racket[list-config-files].}

Calling @racket[config-get-accounts] returns an association list. Presently there is a single key,
@racket['forecast], and the value is a @tech{server account} structure.





                    
