File Coverage

blib/lib/Language/LispPerl.pm
Criterion Covered Total %
statement 15 15 100.0
branch n/a
condition n/a
subroutine 8 8 100.0
pod 0 4 0.0
total 23 27 85.1


line stmt bran cond sub pod time code
1             package Language::LispPerl;
2             $Language::LispPerl::VERSION = '0.006';
3 6     6   143706 use 5.008008;
  6         18  
4 6     6   24 use strict;
  6         13  
  6         129  
5 6     6   21 use warnings;
  6         16  
  6         166  
6              
7 6     6   2722 use Language::LispPerl::Evaler;
  6         13  
  6         791  
8              
9 1     1 0 4 sub true{ return Language::LispPerl::Evaler->true(); }
10 1     1 0 5 sub false{ return Language::LispPerl::Evaler->false(); }
11 1     1 0 5 sub nil{ return Language::LispPerl::Evaler->nil(); }
12 1     1 0 4 sub empty_list{ return Language::LispPerl::Evaler->empty_list(); }
13              
14             1;
15              
16             __END__
17              
18             =head1 NAME
19              
20             Language::LispPerl - A lisp in pure Perl with perl bindings.
21              
22             =head1 SYNOPSIS
23              
24             use Language::LispPerl::Evaler;
25              
26             my $lisp = Language::LispPerl::Evaler->new();
27              
28             # Load core functions and macros
29             $lisp->load("core.clp");
30              
31             my $res = $lisp->eval(q|
32             (defmacro defn [name args & body]
33             `(def ~name
34             (fn ~args ~@body)))
35              
36             (defn foo [arg]
37             (println arg))
38              
39             (foo "hello world!") ;comment here
40             |);
41              
42             # $res is the last lisp object evaluated.
43              
44             =head1 DESCRIPTION
45              
46             Language::LispPerl is a pure Perl lisp interpreter.
47             It is a fork of L<CljPerl> that focuses on making embedding
48             lisp code in your Perl written software straightforward.
49              
50             =head1 INCOMPATIBILITIES
51              
52             =over
53              
54             =item From version 0.004
55              
56             This uses L<Moose> instead of L<Moo>. This should not have any impact on your code,
57             except if you have written your own role for 'Language::LispPerl::BuiltIns'. It will need to be a L<Moose::Role>
58             instead of a L<Moo::Role>.
59              
60             =back
61              
62             =head2 BINDING Perl functions to Lisp
63              
64             =head3 Lisp <-> Perl
65              
66             Here is how to bind to your own Perl functions from lisp.
67              
68             This assumes that your perl functions live in My::App::LispFunctions
69              
70             =head4 PURE Perlfunctions in My::App::LispFunctions:
71              
72             package My::App::LispFunctions;
73              
74             sub do_stuff {
75             my ($x , $y ) = @_;
76             ..
77             return;
78             }
79              
80             sub say_stuff {
81             my ($x , $y ) = @_;
82             ..
83             return $string_or_number;
84             }
85              
86             sub is_stuff {
87             ..
88             # Note that here we return a raw lisp object.
89             return Language::LispPerl->true();
90             }
91              
92             =head4 Binding to these functions in myapp.clp (living in share/lisp for instance):
93              
94             ;; These lisp binding functions will live
95             ;; in the namespace 'myapp'
96              
97             ;; Note that you need core.clp to be loaded in the Evaler.
98              
99             (ns myapp
100             (. require My::App::LispFunctions)
101              
102             (defn do-stuff [x y]
103             (.My::App::LispFunctions do_stuff ^{:return "nil"} x y ))
104              
105             (defn say-stuff [x y]
106             (.My::App::LispFunctions say_stuff ^{:return "scalar"} x y ))
107              
108             (defn is-stuff [x y]
109             (.My::App::LispFunctions is_stuff ^{:return "raw"} x y)))
110              
111             =head4 Usage in lisp space:
112              
113             ( require "myapp.clp" ) ;; Or in Perl $lisp->load("myapp.clp");
114             ( myapp#do-stuff .. .. ) ;; Note the myapp# namespace marker.
115              
116              
117             =head3 Importing and using any Perl package (without prior binding)
118              
119             =head4 An example which creates a timer with AnyEvent.
120              
121             (. require AnyEvent)
122              
123             (def cv (->AnyEvent condvar))
124              
125             (def count 0)
126              
127             (def t (->AnyEvent timer
128             {:after 1
129             :interval 1
130             :cb (fn [ & args]
131             (println count)
132             (set! count (+ count 1))
133             (if (>= count 10)
134             (set! t nil)))}))
135              
136             (.AnyEvent::CondVar::Base recv cv)
137              
138             =head3 Implemeting your own native Lisp functions
139              
140             .TBC.
141              
142             =head3 This lisp implementation
143              
144             =head4 Atoms
145              
146             * Reader forms
147              
148             * Symbols :
149              
150             foo, foo#bar
151              
152             * Literals
153              
154             * Strings :
155              
156             "foo", "\"foo\tbar\n\""
157              
158             * Numbers :
159              
160             1, -2, 2.5
161              
162             * Booleans :
163              
164             true, false . Or from Perl: Language::LispPerl->true() and Language::LispPerl->false()
165              
166             * Nil :
167              
168             nil . Or from Perl: Language::LispPerl->nil();
169              
170             * Keywords :
171              
172             :foo
173              
174             * Lists :
175              
176             (foo bar)
177              
178             * Vectors :
179              
180             [foo bar]
181              
182             * Maps :
183              
184             {:key1 value1 :key2 value2 "key3" value3}
185              
186              
187             =head4 Macro charaters
188              
189             * Quote ('). :
190              
191             '(foo bar)
192              
193             * Comment (;) :
194              
195             ; comment
196              
197             * Dispatch (#) :
198              
199             * Accessor (:) :
200              
201             #:0 ; index accessor
202             #:"key" ; key accessor
203             #::key ; key accessor
204              
205             * Sender (!) :
206              
207             #!"foo"
208              
209             * XML ([) :
210              
211             #[body ^{:attr "value"}]
212              
213             * Metadata (^) :
214              
215             ^{:key value}
216              
217             * Syntax-quote (`) :
218              
219             `(foo bar)
220              
221             * Unquote (~) :
222              
223             `(foo ~bar)
224              
225             * Unquote-slicing (~@) :
226              
227             `(foo ~@bar)
228              
229             =head4 Builtin lisp Functions
230              
231             * list :
232              
233             (list 'a 'b 'c) ;=> '(a b c)
234              
235             * car :
236              
237             (car '(a b c)) ;=> 'a
238              
239             * cdr :
240              
241             (cdr '(a b c)) ;=> '(b c)
242              
243             * cons :
244              
245             (cons 'a '(b c)) ;=> '(a b c)
246              
247             * key accessor :
248              
249             (#::a {:a 'a :b 'a}) ;=> 'a
250              
251             * keys :
252              
253             (keys {:a 'a :b 'b}) ;=> (:a :b)
254              
255             * index accessor :
256              
257             (#:1 ['a 'b 'c]) ;=> 'b
258              
259             * sender :
260              
261             (#:"foo" ['a 'b 'c]) ;=> (foo ['a 'b 'c])
262              
263             * xml :
264              
265             #[html ^{:class "markdown"} #[body "helleworld"]]
266              
267             * length :
268              
269             (length '(a b c)) ;=> 3
270             (length ['a 'b 'c]) ;=> 3
271             (length "abc") ;=> 3
272              
273             * append :
274              
275             (append '(a b) '(c d)) ;=> '(a b c d)
276             (append ['a 'b] ['c 'd]) ;=> ['a 'b 'c 'd]
277             (append "ab" "cd") ;=> "abcd"
278              
279             * type :
280              
281             (type "abc") ;=> "string"
282             (type :abc) ;=> "keyword"
283             (type {}) ;=> "map"
284              
285             * meta :
286              
287             (meta foo ^{:m 'b})
288             (meta foo) ;=> {:m 'b}
289              
290             * fn :
291              
292             (fn [arg & args]
293             (println 'a))
294              
295             * apply :
296              
297             (apply list '(a b c)) ;=> '(a b c)
298              
299             * eval :
300              
301             (eval "(+ 1 2)")
302              
303             * require :
304              
305             (require "core")
306              
307             * def :
308              
309             (def foo "bar")
310             (def ^{:k v} foo "bar")
311              
312             * set! :
313              
314             (set! foo "bar")
315              
316             * let :
317              
318             (let [a 1
319             b a]
320             (println b))
321              
322             * defmacro :
323              
324             (defmacro foo [arg & args]
325             `(println ~arg)
326             `(list ~@args))
327              
328             * if :
329              
330             (if (> 1 0)
331             (println true)
332             (println false))
333              
334             (if true
335             (println true))
336              
337             * while :
338              
339             (while true
340             (println true))
341              
342             * begin :
343              
344             (begin
345             (println 'foo)
346             (println 'bar))
347              
348             * perl->clj :
349              
350             * ! not :
351              
352             (! true) ;=> false
353              
354             * + - * / % == != >= <= > < : only for number.
355              
356             * eq ne : only for string.
357              
358             * equal : for all objects.
359              
360             * . : (.[perl namespace] method [^meta] args ...)
361             A meta can be specifed to control what type of value should be passed into perl function.
362             type : "scalar" "array" "hash" "ref" "nil"
363             ^{:return type
364             :arguments [type ...]}
365              
366             (.Language::LispPerl print "foo")
367             (.Language::LispPerl print ^{:return "nil" :arguments ["scalar"]} "foo") ; return nil and pass first argument as a scalar
368              
369             * -> : (->[perl namespace] method args ...)
370             Like '.', but this will pass perl namespace as first argument to perl method.
371              
372             * println
373              
374             (println {:a 'a})
375              
376             * trace-vars : Trace the variables in current frame.
377              
378             (trace-vars)
379              
380             * quote : Returns the given list as is without evaluating it
381              
382             (quote (+ 1 2 )) -> (+ 1 2)
383              
384             =head4 Core Functions (defined in core.clp)
385              
386             * use-lib : append path into Perl and Language::LispPerl files' searching paths.
387              
388             (use-lib "path")
389              
390             * ns : Language::LispPerl namespace.
391              
392             (ns "foo"
393             (println "bar"))
394              
395             * defn :
396              
397             (defn foo [arg & args]
398             (println arg))
399              
400             * defmulti :
401              
402             * defmethod :
403              
404             * reduce :
405              
406             * map :
407              
408             * file#open : open a file with a callback.
409              
410             (file#open ">file"
411             (fn [fh]
412             (file#>> fn "foo")))
413              
414             * file#<< : read a line from a file handler.
415              
416             (file#<< fh)
417              
418             * file#>> : write a string into a file handler.
419              
420             (file#>> fh "foo")
421              
422             =head1 SEE ALSO
423              
424             L<CljPerl>
425              
426             =head1 AUTHOR
427              
428             Current author: Jerome Eteve ( JETEVE )
429              
430             Original author: Wei Hu, E<lt>huwei04@hotmail.comE<gt>
431              
432             =head1 COPYRIGHT
433              
434             Copyright 2016 Jerome Eteve. All rights Reserved.
435              
436             Copyright 2013 Wei Hu. All Rights Reserved.
437              
438             =head1 ACKNOWLEDGEMENTS
439              
440             This package as been released with the support of L<http://broadbean.com>
441              
442             =head1 LICENSE
443              
444             Licensed under the Apache License, Version 2.0 (the "License");
445             you may not use this file except in compliance with the License.
446             You may obtain a copy of the License at
447              
448             http://www.apache.org/licenses/LICENSE-2.0
449              
450             Unless required by applicable law or agreed to in writing, software
451             distributed under the License is distributed on an "AS IS" BASIS,
452             WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
453             See the License for the specific language governing permissions and
454             limitations under the License.
455              
456             =cut