Usage: Use define-global to define global variables (possibly in different modules) with cross-module getters and setters. globals->command-line automatically generates a command line parser for all the globals defined in modules that are transitively required, and globals-interact generates and textual interaction for reading and writing globals.

Here’s a minimal expample that defines the global *burgers* and generates a command-line parser:

Globals can be used without a command-line parser.

"burger.rkt"
#lang racket/base
(require global)

(define-global *burgers*;name
1;initial value
"Number of burgers";help string for the command line
exact-nonnegative-integer? ;validation
string->number );conversion from input string

(void (globals->command-line ))

(printf "You ordered ~a burgers.\n"(*burgers*))

Save this example as burger.rkt, then on the command line (in the corresponding directory), type:

racketburger.rkt--help

then try

racketburger.rkt--burgers10

and maybe

racketburger.rkt--burgersa

Note: A similar example is included with the package and can be run with

racket-lglobal/examples/minimal----help

For a more extensive example, including a use of globals-interact , try

racket-lglobal/examples/example----help

Additional remarks:

A global variable defined with define-global in a module A is shared between all modules that require A.

Note that a global defined in module A that is transitively required by module B can be fully accessed in module B even if A does not export any identifier. Globals can be removed from the command line with (globals->command-line (remove *my-global*(get-globals ))).

By convention, globals’ identifiers are surrounded by *. The value of a global *my-global* can be retrieved with (*my-global*) and set with (*my-global*some-new-value).

By contrast to parameters, globals

always have a single value at any time,
are not thread safe.

Suggestions, questions or issues? File an issue.

1Globals🔗 i

procedure
( make-global name
init
help
valid?
string->value
[ more-commands]) → global?
name:symbol?
init:any/c
help:(or/cstring? (listofstring? ))
valid?:(->any/cany/c)
string->value:(->any/cany/c)
more-commands:(listofstring? )='()

Returns a global variable with initial value init. The name is for printing purposes.

The procedure valid? is used when setting or updating the value of the global to check if the new value is valid. Note that valid? is not used on init: this can be useful to set the initial value to #f for example while only allowing certain values when set by the user.

The procedure string->value is used to convert command line arguments to values that are checked with valid? before setting the corresponding global to this value. (They could also be used for example in text-field% in GUI applications.)

more-commands is an optional list of additional command-line flags, which can be used in particular to specify short flags.

syntax
( define-global varinithelpvalid?string->value[more-commands])

Shorthand for (define var(make-global 'var....)).

syntax
( define-global:boolean idinithelpmaybe-more-commands)

syntax
( define-global:string idinithelpmaybe-more-commands)

syntax
( define-global:natural0 idinithelpmaybe-more-commands)

syntax
( define-global:natural1 idinithelpmaybe-more-commands)

syntax
( define-global:integer idinithelpmaybe-more-commands)

syntax
( define-global:real idinithelpmaybe-more-commands)

syntax
( define-global:rational idinithelpmaybe-more-commands)

Like define-global but specialize valid? to be, respectively, boolean? , string? , exact-nonnegative-integer? , exact-positive-integer? , exact-integer? , real? , rational? , and specializes string->value to string->boolean , values , and string->number .

syntax
( define-global:category idinitvalshelpmaybe-more-commands)

vals = (listexpr...)

Like define-global but specializes (valid?x) to (member xvals) where vals is a list of values, and uses read for string->value. The help string is also augmented to display the available set of values.

procedure
( global? g)→boolean?
g:any/c
( global-name g)→symbol?
g:global?
( global-help g)→(or/cstring? (listofstring? ))
g:global?
( global-valid? g)→(->any/cboolean? )
g:global?
( global-string->value g)→(->string? any/c)
g:global?
( global-more-commands g)→(listofstring? )
g:global?

Predicate and accessors. See make-global .

procedure
( global-getg)→any/c
g:global?
( global-set! gv)→void?
g:global?
v:any/c
( global-update! gupdater)→void?
g:global?
updater:(->any/cany/c)

(global-get*g*) is equivalent to (*g*) and returns the value of the global. (global-set! *g*v) is equivalent to (*g*v). global-update! updates the value of the global based on its previous value. global-set! and global-update! raise an exception if global-valid? returns #f for the new value.

procedure
( global-unsafe-set! gv)→void?
g:global?
v:any?
( global-unsafe-update! gupdater)→void?
g:global?
updater:(->any/cany/c)

Forces setting and updating the value of the global without checking its validity with global-valid? .

procedure
( global-set-from-string! gstr)→void?
g:global?
str:string?

Combines global-string->value and global-set! .

procedure
( get-globals )→(listofglobal? )

Returns the list of globals that have not been GC’ed (even if they cannot be read directly by the module calling get-globals ).

procedure
( globals->assoc [globals])→(listof(cons/csymbol? any/c))
globals:(listofglobal? )=(get-globals )

Returns an association list of the global names and their values.

procedure
( string->boolean s)→boolean?
s:string?

Interprets s as a boolean. Equivalent to

(and (member (string-downcase (string-trims))
'("#f""#false""false"))
#t)

syntax
( with-globals ([gv]...)body...)

Changes the value of the global g to v for the dynamic extent of body... . Similar to parameterize , but for globals.

2Command line🔗 i

procedure
( default-name->stringsym)→string?
sym:symbol?

Returns a string made of sym where the surrounding * and spaces have been removed. Used as the default argument for global->cmd-line-rule and globals->command-line .

procedure
( globals->command-line [ #:globalsglobals
#:name->stringname->string
#:boolean-valid?bool?
#:boolean-no-prefixno-prefix
#:mutex-groupsmutex-groups
#:argvargv
#:programprogram
#:usage-helpusage]
trailing-arg-name...) → any
globals:(listofglobal? )=(get-globals )
name->string:(->symbol? string? )=default-name->string
bool?:(->any/cany/c)=boolean?
no-prefix:string? ="--no-~a"
mutex-groups:(listof(listofglobal? ))='()

argv : (vectorof(and/cstring? immutable? ))
= (current-command-line-arguments )
program:string? ="<prog>"
usage:(listofstring? )='()
trailing-arg-name:string?

Produces a command line parser via parse-command-line for all the global variables globals.

See parse-command-line for general information. Each list of globals within mutex-groups are placed in a separate once-any group in parse-command-line . Multi flags are not supported by globals.

See global->cmd-line-rule for some of the keywords and for more information about boolean flags.

3Text interaction🔗 i

procedure
( globals-interact [globals])→void?
globals:(listofglobal? )=(get-globals )

Produces a command-line interaction with the user to read and write values of globals.

top ← prev up next →