1 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-transitional.dtd">
2 <html xmlns=
"http://www.w3.org/1999/xhtml" lang=
"en" xml:lang=
"en">
3 <head><meta http-equiv=
"Content-Type" content=
"text/html; charset=utf-8" />
4 <style type=
"text/css">@
import 'doc.css';</style>
6 <pre style=
"background:#AE6;width:25em;float:right;padding-right:2em">
24 <h1
class=
"kana">ポーション</h1>
25 <h1>A Short Pamphlet</h1>
26 <h4>by why the lucky stiff</h4>
28 <p>So why exactly are you learning
this nascent
do-nothing probably-broken language? For fun, right? I’m giving you till the end of sentence to come up with a good reason.</p>
29 <p>This pamphlet probably isn’t
for beginners to computer programming. Just
for those curious about what
Potion is like.</p>
30 <h2>An Understanding</h2>
31 <p>
Potion’s mantra is: <em>Everything is an
object. But objects aren’t everything.</em></p>
32 <p>Etched beneath that in faint pencil: <em>Oh, and everything is a
function.</em></p>
33 <h2>Special Things?</h2>
34 <p>So is there anything unusual about
Potion? Anything of particular interest?</p>
36 <li>
Potion compiles programs down to machine code.</li>
37 <li>It includes a small generational near-exact garbage collector,<br />
38 spending on avg 4ms on medium sized heaps.</li>
39 <li>It is two languages: one
for code, one
for data.</li>
40 <li>It’s written in under 10,000 lines of C.</li>
42 <p>
Potion is inspired by fellow languages Io, Ruby, OCaml, Lua, <span
class=
"caps">REBOL</span> and C. In that order. (Also influenced by the works of Ian Piumarta, Nicolas Cannasse and Basile Starynkevitch.)</p>
44 <p>Let’s start with some code.</p>
51 <p>I know
this isn’t terribly useful, but it’s an infinite printing of the string <code>
'quaff'</code>.</p>
52 <p>A colon starts a <strong>code block</strong>. And the period ends it. The <code>loop</code> command then runs the code block endlessly. You will see the colon and period combination reused throughout
Potion.</p>
53 <p>The <code>print</code> message is sent to the string <code>
'quaff'</code>. Strings are an object, like everything. They receive messages. Messages are separated from objects by a space. (In most languages, you use a dot to separate messages. But, like English, the period signifies the end of something rather than a separation.)</p>
57 (
'cheese',
'bread',
'mayo') at (1) print
60 <p>This one prints the message &
#8216;bread’. The stuff in parentheses is a <strong>list</strong>. We have a list of foodstuffs. And it’s being sent a message named <code>at</code>. Every list has an <code>at</code> message that looks up an item by its position in the list.</p>
61 <p>Notice that after the <code>at</code> message is another list. The <code>1</code> is an argument to <code>at</code>. It’s the position we want to look up. It looks like a list (and it <em>is</em> a list,) but we call it an argument because it comes after a message.</p>
65 (language='
Potion', pointless=true) at (key='language') print
68 <p>Okay, this one looks similar to the list, but it&
#8217;s not. Here we have a <strong>table</strong>. The table pairs up things. The string <code>'language'</code> is paired up with the string <code>'Potion'</code>.</p>
69 <p>Notice the arguments are also a table. Lists and tables are sort of interchangeable. You can use a table or a list as arguments.</p>
70 <h2>The Functional Side</h2>
71 <p>Functions are throughout Potion. Whether it be anonymous lambdas, blocks or type functions.</p>
75 minus = (x, y): x - y.
79 <p>This one illustrates a bit better how tables
get used as argument lists. We have the <code>minus</code> variable which contains a <strong>
function</strong>. The
function subtracts <code>y</code> from <code>x</code>. In
this case, it’ll return <code>-4</code>.</p>
80 <p>(This is similar to keyword arguments in Lua and Python, yes. However, it’s important to see that lists and tables and arguments in Potion all share the same syntax. Less to remember.)</p>
81 <h3>A List as a Function</h3>
84 foods = (
'cheese',
'bread',
'mayo')
88 <p>Here’s a
case where a list is being called as a
function. Yes, everything is a
function! We could also have called: <code>foods (index=2)</code>.</p>
89 <p>Strings, tables, numbers are also functions. The following returns the 3rd character of the
string.</p>
95 <p>Even functions are functions! I invented
this concept. Just like Steve Jobs will one day.</p>
99 (dog=
'canine', cat=
'feline', fox=
'vulpine') each (key, val):
100 (key,
' is a ', val) join print.
103 <p>Functions can also be attached to methods, for use as anonymous blocks (as in Ruby.)</p>
104 <p>These blocks are merely the last argument. This also works: <code>each ((key, val): key print.)</code>.</p>
105 <h2>The Object-Oriented Side</h2>
108 Person = class: /
name, /age, /sex.
110 (
'My name is ', /
name,
'.') join print.
113 <p>The above describes a <strong>class</strong> in Potion. Objects are very memory-efficient. Each Person object will store three properties: the
name, age and sex. (These are not kept in a hashtable. They are kept in memory, immediately following the object’s header.)</p>
114 <p>Properties use a slash before their
name. This comes from the computer filesystem, where slashes are used before the names of folders in which to store files.</p>
115 <p>However,
if you are desperate to use an
object as a hashtable, you can store anything you like in an
object’s method table. Not just methods can go there. Anything can be wrapped in a closure.</p>
116 <h3>Making Objects</h3>
123 <p>Yep, classes are functions, too! They create objects.</p>
124 <p>In this case, the
name of <code>p</code> hasn&
#8217;t been set, so the code will print <code>nil</code>.</p>
125 <p>But how does subclassing work?</p>
129 Policeman = Person
class (rank): /rank = rank.
130 Policeman print = ():
131 (
'My name is ', /
name,
' and I''m a ', /rank,
'.') join print.
133 Policeman (
'Constable') print
136 <p>The <code>
class</code> message just gets sent to the parent
class. And that’s it.</p>
137 <p>A Policeman now has four properties: <code>/
name</code>, <code>/age</code>, <code>/sex</code> and <code>/rank</code>.</p>
138 <p>Notice the first line of the code. The end of the statement is a block. That block is the
object’s constructor. So, in the last line, we’re passing in the
string ‘Constable’ as the <code>rank</code> argument.</p>
142 app = [window (width=200, height=400)
143 [para
'Welcome.', button
'OK']]
147 <p>Lastly, here we have a <strong>lick</strong>. This is the
data language brought up earlier in the section about Special Things. This code will print <code>
'window'</code> since that’s the
name of the first item in the lick.</p>
148 <p>Two languages in one? What
for? I mean you can
do anything you want from code, right?</p>
149 <p>There can be problems with expressing
data in code. Say the above example was written in Potion code. Some thing like
this:</p>
152 app = window(width=200, height=400):
157 <p>In order to get this to work, you need methods for <code>window</code>, <code>para</code> and <code>button</code>. This could clutter the namespace. Also, under what context are those messages available? Are they methods of the created window? Or do they go through some kind of proxy object? We don’t know what’s going on behind
this code. (Which isn’t bad at all,
if it works.)</p>
158 <p>By having a separate little
data language, you can build tree structures of arbitrary elements (akin to <span class="caps">HTML</span>) which act as a kind of common structure between Potion libraries. (You can also think of it as code which has been parsed, but not executed.)</p>
159 <h3>The Flexibility Of…</h3>
160 <p>Licks generally follow the look of Potion. Strings can be quoted. Tables are curved on the edges.</p>
163 [
name (attr1=
'string', attr2=10)
'TEXT HERE']
166 <p>Every lick can have a
name, a table of attributes, and a list of children. The list of children can, instead, be a Potion
data type, such as a number or
string or something. (No,
this isn’t a
new idea. It’s very much like E4X<sup
class=
"footnote" id=
"fnr2"><a href=
"#fn2">2</a></sup>, but without <span
class=
"caps">XML</span>.)</p>
167 <p>However, licks also allow unquoted strings, to give you some added flexibility.</p>
171 digit <- n:[0-9] { n number }
172 value <- d:digit+ |
'(' e:expr
')' { d or e }
173 expr <- l:value op:[*/] r:value
175 if (op ==
'*'): l * r.
else: l / r.
181 <p>Here we have four entries in a lick, getting passed to the <code>Grammar</code> method. The entries are: <code>digit</code>, <code>value</code>, <code>expr</code> and <code>
main</code>. (So,
for example, the <code>digit</code> entry will be paired with the string <code>
"<- n:[0-9] { n number }"</code>.</p>
182 <p>The lick syntax keeps track of nested groups of parentheses, square brackets and curly braces. The unquoted mode merely needs to start with a letter, number or non-token character.</p>
183 <p>Be careful of commas in unquoted strings. This won’t work:</p>
189 <p>You’ll end up with two entries in the lick: a <code>dollars</code> entry and a <code>000</code> entry.</p>
190 <p>Commas are okay inside of nested groups, though. So,
this would be okay:</p>
196 <h2>Pause For Effect</h2>
197 <p>Okay, let’s stop. So you’ve basically seen everything in the language already. Sorry about that. It kind of blows that there’s no surprises
left. :( But, hey, I said it’s little, right?</p>
198 <p>Are you starting to see some patterns in
this code?</p>
200 <li>Methods, blocks and functions all use the colon-dot syntax.</li>
201 <li>Tables and lists are reused as
function and block arguments. And as attributes in licks.</li>
202 <li>Generally, lowercase is used. Except in the
case of
class names. (But it’s nothing special, you can use lowercase
for classes
if you want.)</li>
204 <h2>Potion Syntax</h2>
205 <p>Now that you have a feel
for what Potion can
do, let’s talk about every one of Potion’s tokens in detail.</p>
207 <p>Potion source code is always in <span
class=
"caps">UTF</span>-8. Likewise, all Potion strings are <span
class=
"caps">UTF</span>-8. Potion is too small to include other encodings in its core <span
class=
"caps">API</span>.</p>
209 <p>Potion code lines are separate by a newline. (Or a CR-LF works as well.)</p>
216 <p>Throughout
Potion, a comma is equivalent to a newline.</p>
222 <p>This also means that tables can be written
using newlines as separators:</p>
230 <p>Spaces are used to separate messages and objects and operators, but they usually are only used
for clarity’s sake.</p>
231 <p>To borrow an earlier example, it turns out the following is legit.</p>
234 (
'cheese',
'bread',
'mayo')at(1)print
237 <p>There is some flexibility, in order to avoid senseless syntax errors.</p>
239 <p>Lines preceded by the octothorpe are ignored by Potion.</p>
242 # this foul business...
243 String length = (): 10.
247 <p>Lines can be grouped together into blocks. Think of it as a collection of code you’ve group together to run later. Blocks start with a colon and end with a dot.</p>
254 <h2>Built-in Types</h2>
255 <p>Potion has a rather small set of built-in types and libraries. This is to keep the language core small
for folks who want to embed Potion and to constraint its memory footprint.</p>
256 <h3>True, False, Nil.</h3>
257 <p>Potion has three keywords
for these built-in types.</p>
258 <p><code>nil</code> indicates that a variable is empty: it has no value and no type. (This isn’t exactly
true, though. Its
class is <code>NilKind</code>.)</p>
259 <p><code>
true</code> and <code>
false</code> are
boolean values belonging to the <code>Boolean</code>
class.</p>
260 <p>Anything which is not <code>nil</code> or <code>
false</code> is considered a positive value. (Which means that the number zero and empty strings are considered <code>
true</code> in
if statements.)</p>
262 <p>Basic numbers take up no memory and are passed as plain (32-bit or<br />
263 64-bit, depending on your processor) integers, but we loose one bit of<br />
264 precision
for a tag bit. Arithmetic methods accept the type Number,<br />
265 which is Integer or Double and converts them as it fits.</p>
274 <p>Double numbers use a boxed
double-precision floating point number.</p>
283 <p>Seemless arbitrary-precision math is planned
for the 1.0 release.</p>
285 <p>Strings begin with a single quote, followed by a series of <span
class=
"caps">UTF</span>-8 characters, then a
final single quote. There is only one escape code: <code>
''</code>
for an embedded single quote.</p>
291 'C:\Program Files\Potion'
294 <p>Double-quoted strings allow a number of escape codes.</p>
296 <li><code>
"\n"</code>
for a newline.</li>
297 <li><code>
"\r"</code>
for a carriage
return.</li>
298 <li><code>
"\t"</code>
for a tab.</li>
299 <li><code>
"\uXXXX"</code>
for a Unicode character.</li>
302 <p>In my opinion, a language can be called “functional”
if every statement and expression returns a value. Even <code>
if</code> statements or
class definitions. This is just how Potion is designed. Every statement is a function, since it takes arguments and returns results. There is no <code>void</code>.</p>
303 <h3>if, elsif, else</h3>
304 <p>The <code>if</code> keyword tests its arguments for truth. Its block is then executed if they pass.</p>
307 if (age > 100):
'ancient'.
310 <p>Like any
function, <code>if</code> returns a result. If the condition fails, you get <code>nil</code>. Otherwise, you
get the result of the code executed inside the block.</p>
311 <p>Beyond <code>if</code>, you can chain <code>elsif</code> and <code>else</code> to
catch other conditions.</p>
315 if (title ==
'Jonathan Strange & Mr. Norrell'):
317 elsif (title ==
'The Star Diaries'):
319 elsif (title ==
'The Slynx'):
322 '... probably Philip K. Dick'.
325 <p>These three keywords can all be executed like functions, even though they are compiled into basic instructions.</p>
327 <p>The <code>loop</code> keyword executes its block endlessly.</p>
334 <p>The <code>while</code> keyword will execute its block endlessly, as long as its arguments stay true.</p>
338 while (count > 0):
344 <p>Potion has no <code>for</code> keyword. One alternative is the <code>to</code> keyword.</p>
355 <p>The <code>to</code> keyword will loop from the first number, up to the last.</p>
356 <p>Another option is the <code>times</code> method, which starts at zero.</p>
359 5 times: 'Odelay' print.
362 <p>Notice how the block doesn&
#8217;t need parentheses if we don’t want the block arguments coming in.</p>
364 <p>Returns a value from the
function. You only need to use the <code>
return</code> keyword explicitly
if you’re looking to quit in the middle of the
function.</p>
365 <h2>Names and Objects</h2>
366 <p>The most expressive parts of a program are the naming and creation of unique objects.</p>
368 <p>Generally, any <span
class=
"caps">UTF</span>-8 set of characters which isn’t seen as a built-in type or
operator can be used as a variable. Variables are assigned with a plain equals sign.</p>
373 HTTP =
'Hypertext Transfer Protocol'
377 <p>You must set a variable before
using it (even
if just to <code>nil</code>.) Otherwise, Potion sees a message, sent to <code>
self</code>.</p>
379 <p>Messages follow the same rules as variables. A message name can be any <span
class=
"caps">UTF</span>-8 character which isn’t a built-in type or
operator.</p>
383 [dollars (amount=
self)].
387 <p>In
this example, the <code>$</code> message converts the number into a kind of currency lick.</p>
389 <p>Objects can be asked
if they respond to a message, by prefixing the message with a question mark.</p>
393 "Huh? Numbers are sexed? That's amazing." print.
396 <p>You can also optionally execute the message by send it arguments. And you can space out the quiz mark,
if you want.</p>
402 <p>Since numbers don’t have a <code>gender</code> method,
this’ll give <code>nil</code> rather than an error.</p>
403 <p>A better example of
this would be
if you are in a web application and you wanted to see
if the query
string contained a <code>session</code> entry.</p>
406 HomePage
get = (url):
407 session = url query ? at (
'session').
410 <p>That way if <code>query</code> is empty, you won’t
get an error, you’ll just
get nil. Assuming that <code>query</code> is a table, though — you’ll
get back the value filed under the <code>
'session'</code> key.</p>
412 <p>A path is any set of non-whitespace <span
class=
"caps">UTF</span>-8 characters preceded by a slash. A path is also called an “instance variable” in programming jargon.</p>
415 BTree =
class: /
left, /right.
421 <p>Paths cannot be randomly added to the
object after the
object is created. Each
object has a strict set of paths. Every path which is used in the constructor is added to the
object upon creation.</p>
422 <h3>Path Queries</h3>
423 <p>As with methods, you can query an
object to see if it has a given path.</p>
426 BTree = class: /
left, /right.
430 'left path found!' print.
433 <h2>And That&
#8217;s It?</h2>
434 <p>Yes, that’s the important stuff
for now. But a number of
new features are coming to Potion soon<sup
class=
"footnote" id=
"fnr3"><a href=
"#fn3">3</a></sup>.</p>
436 <li>Assignment extended to match and bind,
for expressing conditions on
object layout.</li>
437 <li><span
class=
"caps">FFI</span> (<code>
extern</code>), debuggers (-d), external compilers (-c) (<em>to c and native executable
for the start</em>).</li>
438 <li>Types and symbol tables. Types to be faster, and symtabs to be slower and more like a <span class="caps">LISP</span> and perl/ruby.</li>
439 <li>Compiler macros and compiler optimizations, like tailcall, constant folding, strength reduction.</li>
440 <li>Bignums, marshalling.</li>
441 <li>More libraries
for os, ui, db, …</li>
442 <li>And also: Native threading. This is a biggie. It requires lock-free bags and some
new native<br />
443 atomic insns and parallelizing loops. The work-stealing sister language sol<sup class="footnote" id="fnr4"><a href="#fn4">4</a></sup> looks good,<br />
444 it can yield to other threads. But
if or
if not to steal work, and
if or not share data.</li>
445 <li>Channels and blocking recv
for typed task communications al la Go. On top of <code>aio</code>.</li>
446 <li>Eventually lists, implemented via licks, but with a LISPy feeling.</li>
448 <p>This are already in, but documented elsewhere<sup class="footnote" id="fnr5"><a href="#fn5">5</a></sup>:</p>
450 <li>Mixins, a syntax
for blending methods into classes.</li>
451 <li><span
class=
"caps">MOP</span>, changing metaclasses, the behavior of classes.</li>
452 <li>Coroutines, a technique
for inprocess threading.</li>
453 <li>Continuations,
for saving and resuming the stack, <code>here</code> and <code>yield</code>.</li>
454 <li>Exceptions
for graceful error handling.</li>
455 <li>Asynchronous non-blocking IO in the <code>aio</code> module.</li>
456 <li>Buffered stream FILE* IO in the <code>buffile</code> module.</li>
457 <li><code>readline</code> module providing a little repl
if called without script</li>
458 <li>Optional, named and
default signature arguments.</li>
460 <p>Thankyou
for reading along. I hope
this was only a brief interruption to an otherwise lush and exotic life. I’m sorry to disappoint with so little. Perhaps one day I can make things right?</p>
462 <p
class=
"footnote" id=
"fn1"><a href=
"#fnr1"><sup>1</sup></a> Potion the <a href="http://github.com/perl11/potion">programming language</a>. Not the drink of fables.</p>
463 <p
class=
"footnote" id=
"fn2"><a href=
"#fnr2"><sup>2</sup></a> <a href=
"http://en.wikipedia.org/wiki/ECMAScript_for_XML">ECMAScript for <span class="caps">XML</span></a>. (See also: <a href=
"http://en.wikipedia.org/wiki/S-Expression">s-expression</a>.)</p>
464 <p
class=
"footnote" id=
"fn3"><a href=
"#fnr3"><sup>3</sup></a> <a href=
"https://github.com/perl11/potion/wiki/_pages">Potion wiki</a>.</p>
465 <p
class=
"footnote" id=
"fn4"><a href=
"#fnr4"><sup>4</sup></a> <a href=
"http://github.com/rsms/sol">sol</a>.</p>
466 <p
class=
"footnote" id=
"fn5"><a href=
"#fnr5"><sup>5</sup></a> <a href=
"http://perl11.org/potion/html/">Potion Documentation</a>.</p>
467 <h2>Potion’s and p2 license</h2>
468 <p>p2 is free software, released under an <span
class=
"caps">MIT</span> and <span
class=
"caps">ARTISTIC</span> 2 license —<br />
469 the very brief paragraphs below. There is satisfaction simply in<br />
470 having created this. Please use
this how you may, even in commercial<br />
471 or academic software. I’ve had a good time and am want
for nothing.</p>
473 <p>potion is copyright © 2009 why the lucky stiff, <span
class=
"caps">MIT</span> licensed.</p>
474 <p>p2 and maintainance code by perl11 http:
475 © 2013 perl11 org, licensed under the <span
class=
"caps">ARTISTIC</span> 2.</p>
476 <p>HOWEVER. The follow <span
class=
"caps">MIT</span> licensed codes have also been employed:</p>
477 <p>Be it known, parts of the
object model taken from <a href=
"http://www.piumarta.com/software/id-objmodel/">obj.c</a>.<br />
478 © 2007 Ian Piumarta</p>
479 <p>And, also, the design of the VM bytecode is from <a href=
"http://luaforge.net/docman/view.php/83/98/ANoFrillsIntroToLua51VMInstructions.pdf">Lua</a>.<br />
480 © 1994-2006 Lua.org, <span
class=
"caps">PUC</span>-Rio</p>
481 <p>The Mersenne Twister (<a href=
"http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/MT2002/emt19937ar.html">MT19937</a>)<br />
482 © 1997-2002, Makoto Matsumoto and Takuji Nishimura</p>
483 <p>Lastly, <a href=
"http://attractivechaos.awardspace.com/khash.h.html">khash.h</a>.<br />
484 © 2008, by Attractive Chaos</p>
485 <p>Permission is hereby granted, free of charge, to any person obtaining<br />
486 a copy of
this software and associated documentation files (the<br />
487 “Software”), to deal in the Software without restriction, including<br />
488 without limitation the rights to use, copy, modify, merge, publish,<br />
489 distribute, sublicense, and/or sell copies of the Software, and to<br />
490 permit persons to whom the Software is furnished to
do so, subject to<br />
491 the following conditions:</p>
492 <p>The above copyright notice and
this permission notice shall be<br />
493 included in all copies or substantial portions of the Software.</p>
494 <p><span
class=
"caps">THE</span> <span class="caps">SOFTWARE</span> IS <span class="caps">PROVIDED</span> “AS IS”, <span
class=
"caps">WITHOUT</span> <span class="caps">WARRANTY</span> OF <span class="caps">ANY</span> <span class="caps">KIND</span>,<br />
495 <span
class=
"caps">EXPRESS</span> OR <span class="caps">IMPLIED</span>, <span
class=
"caps">INCLUDING</span> <span class="caps">BUT</span> <span class="caps">NOT</span> <span class="caps">LIMITED</span> TO <span class="caps">THE</span> <span class="caps">WARRANTIES</span> OF<br />
496 <span
class=
"caps">MERCHANTABILITY</span>, <span
class=
"caps">FITNESS</span> <span class="caps">FOR</span> A <span class="caps">PARTICULAR</span> <span class="caps">PURPOSE</span> <span class="caps">AND</span><br />
497 <span
class=
"caps">NONINFRINGEMENT</span>. IN NO <span class="caps">EVENT</span> <span class="caps">SHALL</span> <span class="caps">THE</span> <span class="caps">AUTHORS</span> BE <span class="caps">LIABLE</span> <span class="caps">FOR</span> <span class="caps">ANY</span><br />
498 <span
class=
"caps">CLAIM</span>, <span
class=
"caps">DAMAGES</span> OR <span class="caps">OTHER</span> <span class="caps">LIABILITY</span>, <span
class=
"caps">WHETHER</span> IN AN <span class="caps">ACTION</span> OF <span class="caps">CONTRACT</span>,<br />
499 <span
class=
"caps">TORT</span> OR <span class="caps">OTHERWISE</span>, <span
class=
"caps">ARISING</span> <span class="caps">FROM</span>, <span
class=
"caps">OUT</span> OF OR IN <span class="caps">CONNECTION</span> <span class="caps">WITH</span> <span class="caps">THE</span><br />
500 <span
class=
"caps">SOFTWARE</span> OR <span class="caps">THE</span> <span class="caps">USE</span> OR <span class="caps">OTHER</span> <span class="caps">DEALINGS</span> IN <span class="caps">THE</span> <span class="caps">SOFTWARE</span>.</p>
int main(int argc, char *argv[])
struct Potion_State Potion
the global interpreter state P. currently singleton (not threads yet)
