Skip to content

Commit 14f8af2

Browse files
author
Paul Nathan
committed
Merge pull request #26 from pnathan/devel
Merging to master
2 parents 851f409 + 6e8bcd6 commit 14f8af2

File tree

3 files changed

+223
-85
lines changed

3 files changed

+223
-85
lines changed

‎README.org‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,3 +48,30 @@ Please pull off the top of the `devel` branch for your contributions and use git
4848
My home Jenkins instance deploys that branch out to articulate-lisp.com/devel. This allows me to merge your PR and
4949
see the result quickly without being at a development machine: e.g., I can use my mobile phone to merge your work and
5050
keep the awesome flowing as fast as possible.
51+
52+
** License information & legalities.
53+
54+
My opinion on articulate-lisp.com's licencing is this: it should be easy to grab bits and pieces and easy to fork if
55+
the author disappears. After some careful reading, I selected...
56+
57+
- GPL3 for the documentation itself.
58+
59+
- Snippets and other samples embedded in the documentation should be considered public domain a.k.a CC0.
60+
61+
- The full-size examples in src/ are more substantial and, are licensed as AGPL3. This is denoted in their comment header.
62+
63+
I do not believe that these terms are onerous and I have sought to structure them to permit both free use of small things
64+
and continuity of information.
65+
66+
AGPL3 is a very strict copyleft license and I feel obligated to justify its choice.
67+
68+
Simply put, I believe that software developers have a moral obligation to allow their users to repair the software that
69+
they provide. This facility is usual for physical items: we can fix our bikes, chairs, cars, etc. I believe that we
70+
ought to let our users fix the software they use, or hire other people to make that fix. I also have profound issues with
71+
the software patent industry. AGPL3 is the best license I know of to ensure that what I create gives users these
72+
capabilities and will not be patented. As these are ridiculously small examples, I am fairly positive that any
73+
serious work will not use them. So it should not be onerous on you.
74+
75+
If your corporate lawyers refuse to let example AGPL3 code exist in your development environment, please write in and -
76+
for my part - I will make a good faith effort to negotiate with you for you a less strict license for your company. And I
77+
will doubtlessly say rude things about lawyers.

‎examples~snippets.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
% Snippets
2+
%
3+
%
4+
5+
One of the great resources we can have as developers is snippets and
6+
example code to understand how the idiom of a language is spoken and
7+
written.
8+
9+
10+
11+
### Defining a function:
12+
13+
~~~~Commonlisp
14+
(defun function-name (param1 param2 &key (keyword1 default-value))
15+
;; implicit progn
16+
)
17+
~~~~
18+
19+
### Defining a method on a type:
20+
21+
22+
~~~~Commonlisp
23+
(defmethod method-name ((object class-name)
24+
;; implicit progn
25+
)
26+
~~~~
27+
28+
### Defining a class
29+
30+
31+
Note that DEFCLASS accessor functions for slots can be SETF'd and serve as both getters and setters for the slot.
32+
33+
:INITARG is the keyword used in MAKE-INSTANCE to denote the value of the initial argument (see below).
34+
35+
:INITFORM is the form used to initialize the slot. Without this, it defaults to `nil`. I favor using nil, 0, "", or
36+
`(error "You must set slot <slotname> to a value")` as the usual initform set.
37+
38+
Note that `(:documentation ...)` is the standard documentation mechanism, which can be vuew in the running image with
39+
DESCRIBE (at least in SBCL).
40+
41+
~~~~Commonlisp
42+
43+
;; no superclass, no slots.
44+
(defclass superclass-1 nil nil)
45+
46+
(defclass my-class (superclass-1)
47+
((variable
48+
:accessor accessor-function
49+
:initarg :variable
50+
:initform form-for-initializition.)
51+
another-variable)
52+
(:documentation "a class snippet!"))
53+
~~~~
54+
55+
56+
57+
### Creating an instance
58+
59+
~~~~Commonlisp
60+
(make-instance 'my-class :variable value)
61+
~~~~
62+
63+
64+
### Adding a constructor
65+
66+
This function runs after the instance is initialized.
67+
68+
~~~~Commonlisp
69+
(defmethod initialize-instance :after ((obj my-class) &key)
70+
(setf (accessor-function obj) 10))
71+
~~~~
72+
73+
### Defining a constant:
74+
75+
Note that the convention is that constants are surrounded with +
76+
77+
```Commonlisp
78+
(defconstant +name+ value "docstring")
79+
```
80+
81+
### Defining a global variable:
82+
83+
Note that the convention is that globals are surrounded with *
84+
85+
~~~~Commonlisp
86+
(defparameter *name* value "docstring")
87+
~~~~
88+
89+
90+
### Creating local variables.
91+
92+
~~~~Commonlisp
93+
(let ((variable1 value-form)
94+
(variable2 value-again))
95+
;; implicit progn where variable[12] are valid
96+
)
97+
98+
~~~~
99+
100+
### LOOP
101+
102+
LOOP is a contentious form in Common Lisp: some people love its
103+
imperative style, others hate it. Regardless, its really handy! Here
104+
are my favorite LOOPs
105+
106+
~~~~Commonlisp
107+
108+
(loop for i from 0 upto 10
109+
collect i)
110+
111+
(loop for i from 0 upto 10
112+
do
113+
(side-effect i))
114+
115+
(loop for ele in list
116+
collect
117+
(operate-on ele))
118+
119+
(loop for ele in list
120+
collect
121+
(operate-on ele))
122+
~~~~
123+
124+
### Lambda functions
125+
126+
The lambda functions is an anonymous function, i.e., unnamed.
127+
128+
Here we map over `numeric-list` and increment each element in it by 1
129+
with `INCF`, returning the incremented list.
130+
131+
~~~~Commonlisp
132+
133+
(mapcar
134+
#'(lambda (x)
135+
(incf x))
136+
numeric-list)
137+
138+
~~~~
139+
140+
### Macro
141+
142+
Note that Lisp macros should be used with care: they read source code
143+
and emit source code.
144+
145+
~~~~Commonlisp
146+
(defmacro with-resource ((resource) &body body)
147+
(allocate-resource ,resource)
148+
(unwind-protect
149+
(progn
150+
,@body)
151+
(deallocate-resource ,resource)))
152+
~~~~
153+
154+
See [UNWIND-PROTECT](http://www.lispworks.com/documentation/HyperSpec/Body/s_unwind.htm)
155+
for details on this very useful form.
156+
157+
### Writing a text file
158+
159+
160+
```Commonlisp
161+
(defun write-file (filename data)
162+
(with-open-file (stream
163+
filename
164+
:direction :output
165+
:if-exists :supersede
166+
:if-does-not-exist :create)
167+
(write-sequence
168+
data
169+
stream)))
170+
```
171+
172+
### Reading a text file
173+
174+
```Commonlisp
175+
176+
(defun read-file (filename)
177+
"Reads `filename` as a sequence of unsigned 8-bit bytes, no
178+
encoding"
179+
(with-open-file (fin filename
180+
:direction :input
181+
:if-does-not-exist :error)
182+
(let ((seq (make-array (file-length fin)
183+
:fill-pointer t)))
184+
(setf (fill-pointer seq)
185+
(read-sequence seq fin))
186+
seq)))
187+
188+
```
189+
190+
Please feel free to contribute your examples or library information to
191+
this page! Send in those pull requests and file those bugs!
192+
193+

‎initial~abcs.md‎

Lines changed: 3 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -100,94 +100,12 @@ Popular libraries that the author have not used include:
100100

101101
* log5 - a log facility
102102

103-
* parentscript - a CL -> javascript emitter
103+
* parenscript - a CL -> javascript emitter
104104

105105
* lparallel - a library for parallel programming
106106

107107
* usocket - TCP socket libary
108108

109109

110-
## Snippets
111-
112-
Common templates for modifying to your needs.
113-
114-
### Defining a function:
115-
116-
~~~~Commonlisp
117-
(defun function-name (param1 param2 &key (keyword1 default-value))
118-
;; implicit progn
119-
)
120-
~~~~
121-
122-
### Defining a method on a type:
123-
124-
125-
~~~~Commonlisp
126-
(defmethod method-name ((object class-name)
127-
;; implicit progn
128-
)
129-
~~~~
130-
131-
132-
### Defining a constant:
133-
134-
Note that the convention is that constants are surrounded with +
135-
136-
```Commonlisp
137-
(defconstant +name+ value "docstring")
138-
```
139-
140-
### Defining a global variable:
141-
142-
Note that the convention is that globals are surrounded with *
143-
144-
~~~~Commonlisp
145-
(defparameter *name* value "docstring")
146-
~~~~
147-
148-
149-
### Creating local variables.
150-
151-
~~~~Commonlisp
152-
(let ((variable1 value-form)
153-
(variable2 value-again))
154-
;; implicit progn where variable[12] are valid
155-
)
156-
157-
~~~~
158-
159-
### Writing a text file
160-
161-
162-
```Commonlisp
163-
(defun write-file (filename data)
164-
(with-open-file (stream
165-
filename
166-
:direction :output
167-
:if-exists :supersede
168-
:if-does-not-exist :create)
169-
(write-sequence
170-
data
171-
stream)))
172-
```
173-
174-
### Reading a text file
175-
176-
```Commonlisp
177-
178-
(defun read-file (filename)
179-
"Reads `filename` as a sequence of unsigned 8-bit bytes, no
180-
encoding"
181-
(with-open-file (fin filename
182-
:direction :input
183-
:if-does-not-exist :error)
184-
(let ((seq (make-array (file-length fin)
185-
:fill-pointer t)))
186-
(setf (fill-pointer seq)
187-
(read-sequence seq fin))
188-
seq)))
189-
190-
```
191-
192-
Please feel free to contribute your examples or library information to
193-
this page! Send in those pull requests and file those bugs!
110+
For snippets and code samples, please see the Snippets in the Examples
111+
submenu.

0 commit comments

Comments
 (0)