-
-
Notifications
You must be signed in to change notification settings - Fork 19
/
documentation.lisp
4380 lines (3117 loc) · 124 KB
/
documentation.lisp
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
(in-package #:org.shirakumo.radiance.core)
;; api.lisp
(docs:define-docs
(variable *api-formats*
"Map from names to api format translator functions.
See API-FORMAT")
(variable *default-api-format*
"The API format to use if no specific one is requested.
See *API-FORMATS*")
(function api-format
"Accessor to the api formats.
The api format function should accept a single argument, the
object to translate, and should configure the response to
output the correct data, or in the very least return an
acceptable value for the response's data.
The name must be a string designator.
See *API-FORMATS*
See REMOVE-API-FORMAT
See LIST-API-FORMATS
See DEFINE-API-FORMAT
See API-OUTPUT")
(function remove-api-format
"Removes the named api format if it exists.
The name must be a string designator.
See *API-FORMATS*
See API-FORMAT")
(function define-api-format
"Define a new api format.
You should configure the *RESPONSE* to output the properly
serialised content of the argument you receive.
Note that the structures must be recursively serialised and
you may not error when encountering any of the types listed
as permitted in API-OUTPUT.
See API-FORMAT
See API-OUTPUT")
(function api-output
"Emits the given data as a response.
This function should be called for any and all return data
from an api endpoint. It ensures the data proper structure,
failure handling, and data translation to the desired output
format.
The proper structure for an API response from an endpoint
should be an object/table/map with the following fields:
status --- The HTTP status code.
message --- A supplied human-readable message that describes
the success or failure.
data --- The data payload of the api output.
The types of objects that can be serialised via this function
are restricted to the following set:
- REAL
- (EQL NIL)
- (EQL T)
- STRING
- LIST (proper ones)
- VECTOR
- HASH-TABLE
An api format may support additional types, but is not
required to. Thus, in order to be conforming, the data you
pass to this function must not reference any values that
have a type outside of this set.
See API-FORMAT")
(function api-serialize
"Cause the object to be serialised into a more favourable structure.
This function should be used by api-format providers to
transform objects that cannot be directly emitted into
a structure that can.
If the object is not serializable, an error of type
API-UNSERIALIZABLE-OBJECT is signalled.")
(variable *api-endpoints*
"A map from names to api-endpoints.
See API-ENDPOINT")
(function api-endpoint
"Accessor to the api-endpoint instances.
See API-ENDPOINT
See REMOVE-API-ENDPOINT
See LIST-API-ENDPOINT")
(function remove-api-endpoint
"Removes the given api page again if it exists.
See API-ENDPOINT")
(function list-api-endpoints
"Lists all known api page instances.
See API-ENDPOINT")
(function ensure-api-endpoint
"Ensures to return the api-endpoint instance for the name.
Accepted types are:
STRING --- Looks up the api page by its name
SYMBOL --- Coerces to string and tries again
API-ENDPOINT --- Returns the argument
If the page cannot be looked up, an error is signalled.
See API-ENDPOINT")
(type api-endpoint
"Container for an api endpoint.
See NAME
See HANDLER
See ARGSLIST
See REQUEST-HANDLER")
(function name
"Accesses the name of the object.
May be a symbol or a string depending on the object.")
(function handler
"Accesses the handler function of the api-endpoint.
The handler-function must have the same lambda-list as
the api-endpoint's ARGSLIST. It must call API-OUTPUT
at some point during its evaluation to emit data.
See API-ENDPOINT")
(function argslist
"Accesses the lambda-list of the api-endpoint's handler.
This describes the public interface's arguments.
Arguments are usually received as GET or POST
parameters of the same name as the argument symbol and it
thus only makes sense for the lambda-list to contain
required and optional arguments.
See API-ENDPOINT")
(function request-handler
"Accesses the function to handle a direct request object and transform it into a proper api call.
This function is usually automatically generated.
It should read out the parameters from the request object
and turn them into arguments for a call to the api-endpoint's
handler function. The function only takes a single argument
namely the request object to handle.
See HANDLER
See API-ENDPOINT")
(function make-request-handler-function
"Constructs a standard request handler function for api-endpoints.
This constructs a lambda expression that extracts the
values from the request's post/get variables and turns
them into arguments for a call to the given function.
See REQUEST-HANDLER")
(function call-api-request
"Calls the given api-endpoint with the given request.
This rebinds *REQUEST*.
See REQUEST-HANDLER
See ENSURE-API-ENDPOINT")
(function call-api
"Calls the given api-endpoint directly with the supplied arguments.
See HANDLER
See ENSURE-API-ENDPOINT")
(function define-api
"Defines a new api endpoint.
NAME --- The name of the endpoint. This also designates
where the endpoint will be reachable. By default
any endpoint can be reached on a /api/[name] path.
ARGS --- The lambda-list for the arguments to the api endpoint.
Usually, unless a specific request-handler is used,
only required and optional arguments can be used.
Their names correspond to the names that will be used
to read out their values from the POST/GET variables of
a request.
OPTIONS --- A list of options that modify the api endpoint in some
way.
BODY --- A number of body forms that compose the actual
functionality of the api endpoint. Should call API-OUTPUT
at some point.
A standard uri-dispatcher called API is responsible for calling the
api pages when the path /api/ is requested.
Api definitions are transformed by options of the type API.
See API-OUTPUT
See API-ENDPOINT
See HANDLER
See REQUEST-HANDLER
See CALL-API
See CALL-API-REQUEST
See EXPAND-OPTIONS")
(function api-error
"Shorthand for (ERROR 'API-ERROR :MESSAGE (FORMAT NIL ..))
See API-ERROR")
(page api
"Standard page to handle and dispatch to API endpoints.
Respects the \"browser\" post/get property, which if set to
the string \"true\", causes a redirect to the referer on
an api-error rather than displaying a machine-readable
error output.
See API-ENDPOINT
See CALL-API-REQUEST"))
;; conditions.lisp
(docs:define-docs
(type radiance-condition
"Base condition class for all conditions related to radiance.
Contains a MESSAGE slot that may hold a string that
explains the reason around the condition in human-
readable format.
See MESSAGE")
(function message
"Accessor to the message of the condition.
See RADIANCE-CONDITION")
(type radiance-error
"Base condition class for all errors related to radiance.
See RADIANCE-CONDITION")
(type radiance-warning
"Base condition class for all warnings related to radiance.
See RADIANCE-CONDITION")
(type definition-for-shared-package
"Warning signalled when a definition is made on a symbol that may lead to unintentional clashes.
This warning gives you an indication for when you might be
accidentally exposing your definition to overrides by other
systems.
See RADIANCE-WARNING")
(type system-has-no-version
"Error signalled when an ASDF system does not store a version string.
Without a version string, Radiance is incapable of tracking what the
current version of a system is and is thus unable to automatically
migrate it.
This error should be continuable.
See MIGRATE
See RADIANCE-ERROR")
(type backwards-migration-not-allowed
"Error signalled when a migration from a later version to an earlier version is attempted.
See MIGRATE
See RADIANCE-ERROR")
(type environment-not-set
"Error signalled when an action was performed that requires an initialised environment, but no environment has been configured yet.
See ENVIRONMENT
See RADIANCE-ERROR")
(type internal-error
"Base condition class for internal errors that are unrecoverable.
See RADIANCE-ERROR")
(type request-error
"Base condition class for errors related to requests.
Contains a REQUEST slot that holds the request that caused
the issue.
See RADIANCE-ERROR")
(type request-empty
"Error signalled when the reply body to the request was empty.
See REQUEST-ERROR")
(type request-not-found
"Error signalled when a resource was requested that does not exist.
See REQUEST-ERROR")
(type request-denied
"Error signalled when a resource was requested that cannot be displayed to the requestor as they do not have sufficient permission.
See REQUEST-ERROR")
(type api-error
"Base condition class for api related errors.
See REQUEST-ERROR")
(type api-auth-error
"Error signalled when a request to an api endpoint was unauthorised.
See API-ERROR")
(type api-argument-missing
"Error signalled when a required argument for the api endpoint was not supplied.
Contains an ARGUMENT slot that holds the name of the missing
argument.
See API-ERROR")
(type api-argument-invalid
"Error signalled when an argument was not of a permitted value.
Contains an ARGUMENT slot that holds the name of the invalid
argument.
See API-ERROR")
(type api-call-not-found
"Error signalled when an api endpoint was requested that does not exist.
See API-ERROR")
(type api-unknown-format
"Error signalled when an api format was required that is unknown.
Contains a FORMAT slot that holds the name of the requested
but missing api format.
See API-FORMAT
See API-ERROR")
(type api-unserializable-object
"Error signalled when an object was attempted to be serialized that cannot be.
Contains an OBJECT slot that holds the object that could not
be serialized.
See API-ERROR")
(type interface-condition
"Base condition class for interface related problems.
Contains an INTERFACE slot that holds an interface designator
to the interface that encountered a problem.
See RADIANCE-CONDITION")
(type interface-implementation-not-set
"Error signalled when an implementation for an interface was attempted to be loaded, but no corresponding implementation is configured.
See INTERFACE-CONDITION
See RADIANCE-ERROR")
(type interface-implementation-not-present
"Error signalled when an implementation for an interface was required for an action to be performed, but no implementation had been loaded.
See INTERFACE-CONDITION
See RADIANCE-ERROR")
(type unparsable-uri-string
"Error signalled when a string was attempted to be turned into an URI object that could not be parsed according to the URI rules.
Contains a STRING slot that holds the string that was attempted
to be parsed.
See URI
See RADIANCE-ERROR")
(type no-such-post-parameter
"Error signalled when a post parameter was requested that does not exist.
Contains a PARAMETER slot that holds the name of the requested
slot.
See REQUEST-ERROR")
(type post-parameter-not-a-file
"Error signalled when a post parameter was attempted to be interpreted as a file, while it is not actually one.
Contains a PARAMETER slot that holds the name of the requested
slot.
See REQUEST-ERROR")
(type file-to-serve-does-not-exist
"Error signalled when a file is attempted to be served that does not exist on the filesystem.
Contains a FILE slot that holds the pathname of the requested
file.
See REQUEST-ERROR"))
;; defaults.lisp
(docs:define-docs
(option (page :hook)
"Adds a hook that is automatically triggered when the page is called.
Unless otherwise specified, the hook is named the same as the page.")
(option (page :uri-groups)
"Allows capturing the regex groups in the URI's path as variables.
See CL-PPCRE:REGISTER-GROUPS-BIND")
(function transform-access-body
"Transforms the body to be protected from access by the permission branch.")
(option (page :access)
#1="Ensures that the page is only accessible if the user requesting it has the appropriate permission branch.")
(option (api :access)
#1#)
(option (admin:panel :access)
#1#)
(option (profile:panel :access)
#1#)
(api-endpoint ||
"Fallback api endpoint that signals an API-CALL-NOT-FOUND error.")
(page favicon
"Standard page for the favicon.ico root image.")
(page robots
"Standard page for the robots.txt root file.")
(page static
"Standard delegate for static files.
The address must be of the form /static/module/path
where the path is translated to one relative to the
module's static resource directory.
See STATIC-FILE")
(variable *domain-internalizers*
"A list of functions that potentially capture and remove known domain parts from the URI.")
(function add-domain
"Adds a new top-level domain to the list of recognised domains.
Adds the name to (MCONFIG :RADIANCE :SERVER :DOMAINS)
The top-level domain as thought of by radiance is any
domain that does not contain any subdomains in its name.
For example, if your website is hosted on example.com
then that would be a top-level domain. Or, if your domain
is some.deep.thing.network.internal then that too would be
a top-level domain.
Radiance needs to know this in order to be able to distinguish
when subdomains for its own purposes start and end since it
is not generally predictable for an arbitrary domain name.
See MCONFIG
See REMOVE-DOMAIN")
(function remove-domain
"Removes a known top-level domain.
See ADD-DOMAIN")
(function compile-domain-internalizers
"Compiles the known top-level domain to optimised recogniser functions.
If the domain does not have an internalizer, it will not
be properly stripped from the request.
See ADD-DOMAIN
See REMOVE-DOMAIN
See *DOMAIN-INTERNALIZERS*")
(route (domain :mapping)
"Ensures that top-level domains are stripped from the uri.
Depends on *DOMAIN-INTERNALIZERS*")
(route (domain :reversal)
"Ensures that the appropriate top-level domain is added to the uri.")
(route (virtual-module :mapping)
"Allows using a path of /!/module/path to simulate a call to a subdomain.
This translates the path by prepending the module to the subdomains
of the uri and resetting the path to the sub-path. The module is also
stored in the request's data field called VIRTUAL-MODULE.")
(route (virtual-module :reversal)
"Properly reverses the uri if the current request context was made under a virtual-module.
Uses the request's data field called VIRTUAL-MODULE to know
where we came from."))
;; dispatch.lisp
(docs:define-docs
(type uri-dispatcher
"Container object for a link between a uri and a page function.
A uri-dispatcher should be called from a request and is then
responsible for generating the content of the response.
See NAME
See DISPATCH-FUNCTION
See PRIORITY
See DISPATCH
See URI-DISPATCHER")
(function dispatch-function
"Accessor to the function that performs the actual response building of the dispatch.
The function should not take any arguments.
The body should either set the data of the *RESPONSE*
object or return suitable data for it.
See URI-DISPATCHER")
(function priority
"Accessor to the priority, which may be NIL or an INTEGER.
See URI-DISPATCHER
See DISPATCH
See ROUTE")
(variable *uri-registry*
"Map from names to uri-dispatcher instances.
See URI-DISPATCHER")
(variable *uri-priority*
"An automatically generated vector containing the properly ordered sequence of uri-dispatchers.
See URI-DISPATCHER
See REBUILD-URI-PRIORITY
See DISPATCH")
(variable *uri-fallback*
"The fallback function to call when no matching uri-dispatcher could be found.
The function should not take any arguments and
otherwise act just like a uri-dispatcher dispatch-
function.
See DISPATCH")
(function uri-dispatcher
"Accessor to the registered uri-dispatcher instances.
Setting this automatically invokes a rebuild of the
*uri-priority* vector.
See *URI-REGISTRY*
See URI-DISPATCHER
See REMOVE-URI-DISPATCHER
See LIST-URI-DISPATCHERS
See REBUILD-URI-PRIORITY")
(function remove-uri-dispatcher
"Removes the named uri-dispatcher, if any.
See *URI-REGISTRY*
See URI-DISPATCHER")
(function list-uri-dispatchers
"Returns a list of all uri-dispatchers that are registered.
See *URI-REGISTRY*
See URI-DISPATCHER")
(function uri-dispatcher>
"Returns true if the uri-dispatcher A has a higher priority than B.
If neither A nor B have a priority set, the
comparison is the same as URI>. If only A has a
priority set, then T is returned. If only B has a
priority set, then NIL is returned. Otherwise T
is returned if the priority of A is greater or equal
to that of B.
See URI>")
(function rebuild-uri-priority
"Rebuilds the optimised and sorted vector of uri-dispatchers.
Sorting is done according to URI-DISPATCHER>.
Only uri-dispatchers that are registered are considered.
See URI-DISPATCHER>
See *URI-PRIORITY*
See *URI-REGISTRY*")
(function define-uri-dispatcher
"Defines a new uri-dispatcher.
The body forms will be evaluated if DISPATCH is called
with a URI object that matches the URI given in the
definition and if no other uri-dispatcher precedes this
one in their priority.
See URI-DISPATCHER
See URI-DISPATCHER>
See DISPATCH-FUNCTION
See DISPATCH")
(function dispatch
"Calls the appropriate uri-dispatcher that is set up to handle the given uri.
Usually, only a single uri-dispatcher will be called, if any.
In order for a dispatcher to be called, the uri must match
the dispatcher's by URI-MATCHES. In the case where two
uri-dispatchers have a matching uri, then the one with the
higher priority will be executed. This is achived by simply
following the order present in the *URI-PRIORITY* vector.
A uri-dispatcher that has been dispatched may call the
ABORT-HANDLING restart, in which case it is considered as
not having matched, and the dispatching continues.
If no matching uri-dispatcher is available, the function
in *URI-FALLBACK* will be called instead.
See URI-MATCHES
See URI-DISPATCHER>
See DISPATCH-FUNCTION
See ABORT-HANDLING
See *URI-PRIORITY*
See *URI-FALLBACK*")
(function abort-handling
"Aborts the current handling and continues dispatch.
This is a wrapper function that simply invokes the
ABORT-HANDLING restart.
See DISPATCH"))
;; documentable.lisp
(docs:define-docs
(type documentable
"Superclass for all classes that can be documented.
Use DOCUMENTATION to access the docstring.
See CL:DOCUMENTATION
See DEFINE-DOCUMENTABLE")
(function define-documentable
"Defines a new documentable class.
If the class-option :FIND-FUNCTION is given, shortcut
functions for DOCUMENTATION are additionally created
that allow using just the name of an instance to
access the docstring. The find-function is called
with a single argument, the name of the instance to find.
See DOCUMENTABLE"))
;; environment.lisp
(docs:define-docs
(variable *environment*
"Holds the currently configured environment name, if any.
See ENVIRONMENT")
(hook environment-change
"This hook is triggered after the environment has been changed.
At this point the environment is already set up and the
configuration has been reloaded or purged as necessary.")
(function environment-directory
"Returns the base directory for the given environment and file kind.
If the ENVIRONMENT parameter is T, it is treated as if it were
the value of (ENVIRONMENT).
The administrator is encouraged to provide specialised methods
on this generic function in order to redefine the base directories
used for the environment's files.
The following KINDs are currently recognised internally, though
the user may supply further kinds.
:CONFIGURATION --- The base for configuration files. The
MCONFIG/CONFIG functions access files in
this base directory.
:CACHE --- The base for temporary cache files that
may be cleared out without consequence.
:DATA --- The base for data files. Modules may use
this directory to store data files for
runtime caches, user data, etc.
:TEMPLATE --- The base for template files. Administrators
may use this directory to provide overrides
for a module's template files.
:STATIC --- The base for static files. Administrators
may use this directory to provide overrides
for a module's static files.
By default the base paths are determined as follows:
:CONFIGURATION
1. A root is discovered as one of the following alternatives:
1.1. The XDG_CONFIG_HOME environment variable is consulted.
1.2. On Windows the AppData environment variable is consulted.
1.3. On Windows the directory ~/Application Data/ is used.
1.4. The directory ~/.config/ is used.
2. A subdirectory called \"radiance\" is added to the root.
3. A subdirectory with the environment name is added to the root.
:CACHE
1. A root is discovered as one of the following alternatives:
1.1 The XDG_CACHE_HOME environment variable is consulted.
1.2 On Windows the TEMP environment variable is consulted.
1.3 On Windows the directory ~/Local Settings/Temp/ is used.
1.4 The directory ~/.cache/ is used.
2. A subdirectory called \"radiance\" is added to the root.
3. A subdirectory with the environment name is added to the root.
:DATA/:TEMPLATE/:STATIC
1. A root is discovered as one of the following alternatives:
1.1 The XDG_DATA_HOME environment variable is consulted.
1.2 On Windows the LocalAppData environment variable is consulted.
1.3 On Windows the directory ~/Local Settings/ is used.
1.4 The directory ~/.local/share/ is used.
2. A subdirectory called \"radiance\" is added to the root.
3. A subdirectory with the environment name is added to the root.
4. A subdirectory with the name of the type (data/template/static)
is added to the root.
For instance, the environment directory on a clean Linux system
for the \"default\" environment and :configuration kind would be:
~/.config/radiance/default/
The same on a recent (Vista+) Windows system would be:
~/AppData/Roaming/radiance/default/
And on an older (XP-) Windows system it would be:
~/Application Data/radiance/default/")
(function environment-module-directory
"Returns the base directory for the given module and file kind.
The administrator is allowed to supply custom methods to this
function that specialise on specific modules to tightly control
the behaviour.
If the environment is unset, this function will signal an error.
By default this simply retrieves the environment root directory
for the requested file kind and adds a subdirectory named after
the downcased module name.
For instance, the module directory for the radiance-core
module in the default environment for the :configuration kind
on Linux would be:
~/.config/radiance/default/radiance-core/
See ENVIRONMENT-DIRECTORY
See ENVIRONMENT
See CHECK-ENVIRONMENT")
(function environment-module-pathname
"Returns a path within the module's file directory for the given kind.
This simply performs a merge-pathnames call on the given pathname
and the corresponding ENVIRONMENT-MODULE-DIRECTORY.
See ENVIRONMENT-MODULE-DIRECTORY")
(function environment
"Accessor to the current environment.
The environment decides the namespace for the configuration
and data files of Radiance and all modules that use its system.
Note that changing the environment after one has already
been loaded and modules have been loaded with it, is currently
not supported and will lead to strange behaviour.
See *ENVIRONMENT*
See CHECK-ENVIRONMENT
See MCONFIG-PATHNAME")
(function check-environment
"Checks whether the environment is properly configured.
If no environment is present, an error of type
ENVIRONMENT-NOT-SET is signalled. Two restarts will
be present at the time:
CONTINUE --- Sets the environment to \"default\"
SET-ENVIRONMENT --- Sets the environment to the one
passed in the argument.
See ENVIRONMENT")
(function reload-environment
"Reloads the current environment from disk.
Note that configuration files are reloaded lazily, with the
exception of the radiance-core configuration.
See CHECK-ENVIRONMENT
See ENVIRONMENT")
(function sync-environment
"Forces the writing of all configuration files.
This will cause the configuration file for every loaded module to
be written to disk. Note that this will /not/ necessarily first
try to load the files from disk, so changes to the files may be
overwritten and lost by this operation.
Typically configuration files are automatically synced to disc
on write, so this function should not be necessary most of the
time.
See MODULARIZE:LIST-MODULES
See MCONFIG-STORAGE")
(function mconfig-pathname
"Returns the proper pathname to the module according to the current environment.
The path is constructed according to:
:NAME Set to the downcased module-name.
:TYPE Set to conf.TYPE with type downcased.
:DEFAULTS ENVIRONMENT-MODULE-DIRECTORY for the
given module and the :CONFIGURATION kind.
An environment must have been configured prior to calling
this function.
See ENVIRONMENT-MODULE-DIRECTORY
See ENVIRONMENT")
(function mconfig-storage
"Returns the storage object for the given module.
The storage object is cached and will only be loaded
if it has not previously been loaded. This means that
unless explicit cache purging occurs, changes to the
underlying configuration file will be lost on
subsequent writes.
The object is cached in the module-storage slot :CONFIG
See MODULARIZE:MODULE-STORAGE
See MCONFIG-PATHNAME
See UBIQUITOUS:RESTORE
See UBIQUITOUS:OFFLOAD")
(function mconfig
"Accesses a configuration variable for the given module's storage.
See UBIQUITOUS:VALUE
See MCONFIG-STORAGE")
(function defaulted-mconfig
"Sets the configuration variable to the given default if it has not been set previously and returns the value.
See UBIQUITOUS:DEFAULTED-VALUE
See MCONFIG-STORAGE")
(function remmconfig
"Removes the configuration place from the given module's configuration.
See UBIQUITOUS:REMVALUE
See MCONFIG-STORAGE")
(function config
"Shorthand to access the current module's configuration.
This has to be a macro so that the current package can be
captured.
See MCONFIG")
(function defaulted-config
"Shorthand to set/retrieve a defaulted value from the module's configuration.
This has to be a macro so that the current package can be
captured.
See DEFAULTED-MCONFIG")
(function remconfig
"Shorthand to remove a place from the module's configuration
This has to be a macro so that the current package can be
captured.
See REMMCONFIG")
(function static-file
"Returns the static file for the given base.
The base will usually be your local module. This function will return
the path returned by ENVIRONMENT-MODULE-PATHNAME for the given base,
:STATIC type, and namestring if the file exists, or otherwise merge
the namestring with the static/ subdirectory within your module's
source directory.
For instance, a module named FOO asking for the BAR static file while
the file is overridden would return a path like the following under
default setups:
~/.local/share/radiance/default/static/foo/bar
If this override file did not exist, the following path would be
returned instead assuming FOO's project root is at ~/Projects/:
~/Projects/foo/static/bar
See @STATIC")
(function @static
"Expands to a pathname to the static file in the current module.
This expands to a load-time-value form if the namestring is constant,
ensuring that no expensive lookups are done at runtime.
See STATIC-FILE")
(function template-file
"Returns the template file for the given base.
The base will usually be your local module. This function will return
the path returned by ENVIRONMENT-MODULE-PATHNAME for the given base,
:TEMPLATE type, and namestring if the file exists, or otherwise merge
the namestring with the template/ subdirectory within your module's
source directory.
For instance, a module named FOO asking for the BAR template file while
the file is overridden would return a path like the following under
default setups:
~/.local/share/radiance/default/template/foo/bar
If this override file did not exist, the following path would be
returned instead assuming FOO's project root is at ~/Projects/:
~/Projects/foo/template/bar
See @TEMPLATE")
(function @template
"Expands to a pathname to the template file in the current module.
This expands to a load-time-value form if the namestring is constant,
ensuring that no expensive lookups are done at runtime.
See TEMPLATE-FILE"))
;; handle.lisp
(docs:define-docs
(variable *debugger*