forked from lokke-org/lokke
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathlokke.1.txt
168 lines (128 loc) · 7.08 KB
/
lokke.1.txt
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
lokke(1) General Commands Manual lokke(1)
NAME
lokke - a Clojure dialect for Guile
SYNOPSIS
lokke [help|--help|-h|-?]
lokke -0
lokke run [-l path] [-e expr] [-a func] [RUN_OPT ...] [-- arg ...]
lok (--help|-h|-?)
lok [-l path] [-e expr] [-a func] [RUN_OPT ...] [-- arg ...]
DESCRIPTION
Lokke is a Clojure dialect for Guile, and may be invoked in two ways.
lokke is the most general command, acting as specified by an initial
subcommand argument (e.g. run), while lok is a convenience for inter-
active use, and behaves exactly as if lokke run had been invoked with
the same arguments. When no arguments are provided, both commands
present an interactive Read-Eval-Print-Loop (REPL) on the terminal, and
the run subcommand acts as if the final arguments had been -e '(clo-
jure.main/repl)' whenever no other -l, -e, -a, -, or FILE arguments are
given.
Any args will be available as *command-line-args* in Clojure, and must
be delimited from the others by --.
The -0 option allows lokke to act as a script interpreter in a flexi-
ble, portable manner, given that the handling of #! interpeter lines
is not standardized across platforms. See SCRIPT EVALUATION below for
additional information.
Unless otherwise specified, and unlike Guile, lokke sets Guile's *ran-
dom-state* at startup to a value generated by Guile's ran-
dom-state-from-platform, meaning that rand-int values, for example,
will usually differ across invocations.
You can invoke lokke run ... -e guile.guile/%load-path or lok ... -e
guile.guile/%load-path to display the Guile load path (including any
dependencies) for a given invocation.
RUN_OPT
-l, --load file
Execute code in file.
-e, --eval code
Evaluate code, printing any values that are not nil or unspeci-
fied.
-a, --apply some.ns/function
Apply some.ns/function to the *command-line-args*.
-m, --main some.ns
Apply some.ns/-main to the *command-line-args*.
- Execute any code provided on standard input.
file Execute code in file, which must not start with a dash (-).
--deps file
Merge the dependencies described in the file into the dependency
map. See the DEPENDENCIES section below for further informa-
tion.
-p Treat the current working directory as a project. At the mo-
ment, this just acts as if --deps deps.edn had been specified
in its place.
--seed sys
Initialize the *random-state* (which affects calls like
rand-int) at startup in a platform-specific way. Insufficient
for security-critical applications.
--seed integer
Initialize the *random-state* at startup using the given inte-
ger.
--no-seed
Suppress the default, implicit --seed sys at startup. The
rightmost seed related argument determines the startup behavior.
SCRIPT EVALUATION
If, and only if, you don't need to specify any additional arguments,
you may begin your scripts like this:
#!/path/to/lokke-0 -0 ;; -*-clojure-*-
!#
(prn :hello-world)
...
When lokke executes the program, the content between the #! !# pair is
ignored as a block comment, just as with Guile itself.
Whenever you do need to specify additional arguments, you should not
put them on the #! line because the handling of additional text on
that line varies from platform to platform. Sometimes the remainder of
the line becomes a single arrgument, sometimes it is split on white-
space, and (more rarely), sometimes part of the line is ignored.
Accordingly, if you need to make adjustments, you may do something like
this:
#!/path/to/lokke-0 -0 ;; -*-clojure-*-
;; We're in a Guile preamble module defining a procedure for each
;; lokke subcommand.
(apply run "-l" %0 "--" %&)
!#
;; Place your Clojure code here, after the !#
(prn :hello-world)
...
This will behave exactly the same as the previous example. When no
code is provided in the block comment, lokke will act as if (apply run
"-l" %0 "--" %&) had been specified, but you can of course adjust the
run invocation to suit your needs, or provide something else entirely.
Everything after the -0 and before the !# is executed as Scheme code by
Guile in a module that has definitions for each of the lokke subcom-
mands. Note that the code Guile executes will begin with the character
immediately after the zero in -0 no matter what it is (i.e. even if it
is not whitespace). The zero actually specifies a compatibility level,
and for now zero is the only valid number.
As you may have guessed, the preamble module binds %0 to the script
path (like $0 in POSIX shells), %& to a list of all of the subsequent
command line arguments, and %1, %2, etc. to the elements of %&.
At the moment lokke is not a binary executable. If the system requires
#! interpreters to be binary executables, or if you'd like to locate
lokke via the current PATH, you may be able to rely on env like this:
#!/usr/bin/env lokke-0 -0
...
DEPENDENCIES
Dependencies may be specified via --deps file. Each file must contain
a subset of the deps.edn syntax
<https://clojure.org/reference/deps_and_cli#_deps_edn>, and at the mo-
ment, only :git/url dependencies are supported. When multiple files
are specified, their dependency maps are merged from left to right. If
you just want to ensure you have acquired all of the dependencies, you
can run lok --deps some.edn -e nil.
READLINE SUPPORT
Assuming your guile was compiled with readline support, it's likely
you'll want to add something like this to ~/.config/lokke/interac-
tive.scm to enable it in the REPL:
;;; -*-scheme-*-
(use-modules (ice-9 readline))
(activate-readline)
ENVIRONMENT
LOKKE_HISTORY
Specifies the path to the REPL history file. Defaults to
$XDG_CACHE_HOME/lokke/history when XDG_CACHE_HOME is set, other-
wise $HOME/.cache/lokke/history.
SEE ALSO
guile(1), and for much more detail, the Guile Reference Manual
<https://www.gnu.org/software/guile/manual/html_node/index.html> which
may also be available via info guile or M-x info in emacs.
0.0.1 2020-08-27 lokke(1)