Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-sandbox Reference Manual, version 0.0.4, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 12:45:21 2020 GMT+0.
• Introduction | What cl-sandbox is all about | |
• Systems | The systems documentation | |
• Modules | The modules documentation | |
• Files | The files documentation | |
• Packages | The packages documentation | |
• Definitions | The symbols documentation | |
• Indexes | Concepts, functions, variables and data types |
Sandbox is a small package, which allows you to easily create a almost identical environment like you had in your REPL, where you can experiment and try out different things without worrying about breaking anything in original place, or polluting global namespace.
Sandobx is licensed with MIT license, which means that you can do pretty much everything with it.
I am trying to build the library on as many compilers that I can. I have encountered some problems with UIOP on CLISP; therefore, CLISP is not supported.
Let's say that you are working inside your own package, which uses Drakma.
CL-USER> (defpackage :my-package
(:use :cl :drakma))
#<PACKAGE "MY-PACKAGE">
CL-USER> (in-package :my-package)
#<PACKAGE "MY-PACKAGE">
Now you want to test something (e.g. querying google translate) and use helper variables, but you don't want to pollute your package. Therefore, you use sandbox package:
MY-PACKAGE> (ql:quickload :cl-sandbox)
To load "cl-sandbox":
Load 1 ASDF system:
cl-sandbox
; Loading "cl-sandbox"
(:CL-SANDBOX)
MY-PACKAGE> (sandbox:start)
SANDBOX::SUCCESS
|sandbox-home640|>
Note that the system's name is cl-sandbox, but package can use both cl-sandbox and sandbox.
The above code creates a unique and fresh package for sandbox. The package uses all the symbols exported from the previous package (here it would be "MY-PACKAGE"), as well as symbols exported by all packages used by your package. If you do not wish to import these packages, use keyword argument import-used-packages
:
MY-PACKAGE> (sandbox:start :import-used-packages nil)
SANDBOX::SUCCESS
|sandbox-home640|> nil ; NIL comes from CL package
; Evaluation aborted on #<UNBOUND-VARIABLE NIL {1001C92773}>.
You can also use the same argument to provide your list of packages to use instead:
MY-PACKAGE> (sandbox:start :import-used-packages (list (find-package :cl)))
SANDBOX::SUCCESS
|sandbox-home640|> nil
NIL
Now let's head back to the http example. Since our package "MY-PACKAGE" used drakma, we would like to see if we can access its external symbols:
|sandbox-home640|> *drakma-version*
"2.0.2"
So far so good! Now let's call the google query:
|sandbox-home640|> (defparameter *local-external-format* :utf-8)
*LOCAL-EXTERNAL-FORMAT*
|sandbox-home640|> (defparameter *local-content-types* (cons '("application" . "json")
*text-content-types*))
*LOCAL-CONTENT-TYPES*
|sandbox-home640|> (ql:quickload :cl-html-parse)
To load "cl-html-parse":
Load 1 ASDF system:
cl-html-parse
; Loading "cl-html-parse"
(:CL-HTML-PARSE)
|sandbox-home640|> (defun get-translation (html)
(cadr (sixth (third (car (cl-html-parse:parse-html html))))))
GET-TRANSLATION
|sandbox-home640|> (defun translate (query lang-to lang-from)
(drakma:http-request "http://translate.google.com/m"
:parameters `(("hl" . ,lang-to)
("sl" . ,lang-from)
("q" . ,query))))
TRANSLATE
|sandbox-home640|> (get-translation (translate "Hello, world!" "pl" "en"))
"Witaj świecie!"
Works fine! Now, you sometimes might want to do something else and might need to change special variables:
|sandbox-home640|> (print (drakma:http-request "http://reddit.com/user/cliffwarden/about.json"))
#(123 34 107 105 110 100 34 58 32 34 116 50 34 44 32 34 100 97 116 97 34 58 32
123 34 110 97 109 101 34 58 32 34 99 108 105 102 102 119 97 114 100 101 110
34 44 32 34 105 115 95 102 114 105 101 110 100 34 58 32 102 97 108 115 101 44
32 34 99 114 101 97 116 101 100 34 58 32 49 49 53 49 56 48 53 57 54 51 46 48
44 32 34 104 105 100 101 95 102 114 111 109 95 114 111 98 111 116 115 34 58
32 102 97 108 115 101 44 32 34 99 114 101 97 116 101 100 95 117 116 99 34 58
32 49 49 53 49 55 55 55 49 54 51 46 48 44 32 34 108 105 110 107 95 107 97 114
109 97 34 58 32 56 51 51 44 32 34 99 111 109 109 101 110 116 95 107 97 114
109 97 34 58 32 53 54 48 44 32 34 105 115 95 103 111 108 100 34 58 32 102 97
108 115 101 44 32 34 105 115 95 109 111 100 34 58 32 116 114 117 101 44 32 34
115 117 98 114 101 100 100 105 116 34 58 32 110 117 108 108 44 32 34 104 97
115 95 118 101 114 105 102 105 101 100 95 101 109 97 105 108 34 58 32 116 114
117 101 44 32 34 105 100 34 58 32 34 57 52 52 48 34 125 125)
No good! We want text! However, since it depends on special variables, you can shadow them using LET(note that changing any variables that are external will modify them!):
|sandbox-home640|> (defparameter *local-external-format* :utf-8)
*LOCAL-EXTERNAL-FORMAT*
|sandbox-home640|> (defparameter *local-content-types* (cons '("application" . "json")
*text-content-types*))
*LOCAL-CONTENT-TYPES*
(defparameter *my-result* (let ((*drakma-default-external-format* *local-external-format*)
(*text-content-types* *local-content-types*))
(print (drakma:http-request "http://reddit.com/user/cliffwarden/about.json"))))
"{\"kind\": \"t2\", \"data\": {\"name\": \"cliffwarden\", \"is_friend\": false, \"created\": 1151805963.0, \"hide_from_robots\": false, \"created_utc\": 1151777163.0, \"link_karma\": 833, \"comment_karma\": 560, \"is_gold\": false, \"is_mod\": true, \"subreddit\": null, \"has_verified_email\": true, \"id\": \"9440\"}}"
*MY-RESULT*
The code above has been inspired by the blog post that you can find here.
Finally, let us exit the sandbox and ensure that our environment is clean:
|sandbox-home640|> (prog1 *package* (sandbox:exit))
#<PACKAGE (deleted) {100209E5D3}>
MY-PACKAGE> *my-result*
; Evaluation aborted on #<UNBOUND-VARIABLE *MY-RESULT* {1006CBCC63}>.
Here we returned *package*
to see if it is still there. As you can see, it is not. Moreover, variables defined in sandbox are also not present in the origin package(the package we came from; here, it is "MY-PACKAGE"), and we are back to the package that we started sandbox from.
If you want, you can import internal symbols to the sandbox too. Here is an example of how to do so:
CL-USER> (defpackage :my-package
(:use :cl :drakma))
#<PACKAGE "MY-PACKAGE">
CL-USER> (in-package :my-package)
#<PACKAGE "MY-PACKAGE">
MY-PACKAGE> (defparameter *five* 5)
*FIVE*
MY-PACKAGE> *five*
5
MY-PACKAGE> (sandbox:start :import-internal-symbols t)
SANDBOX::SUCCESS
|sandbox-home594|> *five*
5
MY-PACKAGE> *five*
5
You can test the package the following way:
CL-USER> (ql:quickload :cl-sandbox)
To load "cl-sandbox":
Load 1 ASDF system:
cl-sandbox
; Loading "cl-sandbox"
(:CL-SANDBOX)
CL-USER> (asdf:test-system 'cl-sandbox)
; compiling file "/home/malice/Programming/Lisp/cl-sandbox/t/sandbox-tests.lisp" (written 22 FEB 2017 04:24:42 AM):
; compiling (DEFPACKAGE #:CL-SANDBOX/TESTS ...)
; compiling (IN-PACKAGE #:CL-SANDBOX/TESTS)
; compiling (DEFPARAMETER %%TESTING-VALUE%% ...)
; compiling (DEFUN RUN-TESTS ...)
; compiling (DEF-SUITE CL-SANDBOX-SUITE ...)
; compiling (IN-SUITE CL-SANDBOX-SUITE)
; compiling (TEST IN-AND-OUT ...)
; compiling (TEST OUTER-VARS-AVAILABLE? ...)
; compiling (TEST TEST-PAUSING ...)
; compiling (TEST PAUSING-CORNER-CASES1 ...)
; compiling (TEST PAUSING-CORNER-CASES2 ...)
; /home/malice/.cache/common-lisp/sbcl-1.3.14-linux-x64/home/malice/Programming/Lisp/cl-sandbox/t/sandbox-tests-TMP.fasl written
; compilation finished in 0:00:00.002
Running test suite CL-SANDBOX-SUITE
Running test IN-AND-OUT ....
Running test OUTER-VARS-AVAILABLE? .....
Running test TEST-PAUSING .........
Running test PAUSING-CORNER-CASES1 ......
Running test PAUSING-CORNER-CASES2 .....
Did 29 checks.
Pass: 29 (100%)
Skip: 0 ( 0%)
Fail: 0 ( 0%)
T
If tests failed on your machine and it looks like my fault, please, contact me or file an issue.
Feel free to contact me by my e-mail (which can be found in cl-sandbox.asd), or by creating an issue.
This package has been created by Mateusz Malisz.
Next: Modules, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The cl-sandbox system |
Mateusz Malisz <maliszmat@gmail.com>
MIT
Utility package for creating safe experimental environment.
0.0.4
cl-sandbox.asd (file)
src (module)
Modules are listed depth-first from the system components tree.
• The cl-sandbox/src module |
cl-sandbox (system)
src/
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files |
• The cl-sandbox.asd file | ||
• The cl-sandbox/src/package.lisp file | ||
• The cl-sandbox/src/sandbox.lisp file |
Next: The cl-sandbox/src/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
cl-sandbox.asd
cl-sandbox (system)
Next: The cl-sandbox/src/sandbox․lisp file, Previous: The cl-sandbox․asd file, Up: Lisp files [Contents][Index]
Previous: The cl-sandbox/src/package․lisp file, Up: Lisp files [Contents][Index]
src (module)
src/sandbox.lisp
%change-name (function)
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The sandbox package |
package.lisp (file)
cl-sandbox
common-lisp
%change-name (function)
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions | ||
• Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported functions |
Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Close sandbox session, returning to the previous package and deleting the sandbox package..
sandbox.lisp (file)
Pause sandbox session, leaving pacakge for future use.
sandbox.lisp (file)
Resume paused sandbox session.
sandbox.lisp (file)
Start Sandbox session. The Sandbox package will use all packages from the origin package and this package.
If you do not wish for this to happen, either provide NIL as an argument to import-used-packages
to not import anything except symbols from origin package,
or provide your list of packages to import-used-packages;
any packages you specify there will be used.
By default, only exported symbols are imported.
To import internal symbols from orign package,
provide T to import-internal-symbols
sandbox.lisp (file)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal functions |
Previous: Internal definitions, Up: Internal definitions [Contents][Index]
Change name of sandbox package to NEW-NAME.
sandbox.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
• Concept index | ||
• Function index | ||
• Variable index | ||
• Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | C F L M |
---|
Jump to: | C F L M |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | %
E F P R S |
---|
Jump to: | %
E F P R S |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | C P S |
---|
Index Entry | Section | ||
---|---|---|---|
| |||
C | |||
cl-sandbox : | The cl-sandbox system | ||
| |||
P | |||
Package, sandbox : | The sandbox package | ||
| |||
S | |||
sandbox : | The sandbox package | ||
System, cl-sandbox : | The cl-sandbox system | ||
|
Jump to: | C P S |
---|