README.markdown

   1 <!-- This is definitely the biggest hack, ever. Damnit, GitHub. -->
   2 <h1><a href="https://travis-ci.org/ELLIOTTCABLE/Paws.js"><img alt='Build status' src="https://travis-ci.org/ELLIOTTCABLE/Paws.js.png" align='right'></a><img src="http://elliottcable.s3.amazonaws.com/p/8x8.png" align='right'><a href="https://coveralls.io/r/ELLIOTTCABLE/Paws.js"><img alt='Coverage status' src="https://coveralls.io/repos/ELLIOTTCABLE/Paws.js/badge.png?branch=Master" align='right'></a><img src="http://elliottcable.s3.amazonaws.com/p/8x8.png" align='right'><a href="https://gemnasium.com/ELLIOTTCABLE/Paws.js"><img alt='Dependency status' src="https://gemnasium.com/ELLIOTTCABLE/Paws.js.png" align='right'></a><img src="http://elliottcable.s3.amazonaws.com/p/8x8.png" align='right'><a href="http://stillmaintained.com/ELLIOTTCABLE/Paws.js"><img alt='Maintenance status' src="http://stillmaintained.com/ELLIOTTCABLE/Paws.js.png" align='right'></a>
   3
   4 Paws.js </h1>
   5 **Hello, friend.** This is a JavaScript implementation of the Paws machine, intended both to be included
   6 into client-side code executed by browsers, and to be embedded into [Node.js][] projects.
   7
   8 **“What's a Paws,”** you ask? [Paws][] could be seen either as a *type* of programming language, or
   9 as a design for a VM *on which* languages of that type can be run. Paws is a project sitting
  10 somewhere between a pure VM for language development (think: the JVM), and a family of languages
  11 (think: the LISPs.)
  12
  13 Paws lends itself well to highly *asynchronous* programming, meaning it's designed for things
  14 involving the network requests (by design, web applications), and other tasks where concurrency is
  15 desirable. In addition, things built on top of Paws can *distribute* themselves across multiple
  16 environments and machines (this means your database, and your user's browsers, can all talk amongst
  17 one-another.) Finally, Paws is designed from the ground-up to be *concurrency*-aware, ensuring tasks
  18 can parallelize when they won't affect eachother negatively.
  19
  20 **“Cool! Can I use it?”** Probably not, I'm afraid, although it's adorable that you ask.
  21 Unfortunately, this project is basically just a VM, with some excruciatingly-primative primatives
  22 with which one can construct abstractions. (Writing code that will run on this machine is
  23 approximately analogous to writing raw assembler.) Before this project will be useful to you,
  24 somebody'll need to write some abstractions (basically, a language) on top of it!
  25
  26 To boot, the Paws system as a whole is still under heavy design and development; lots of things are
  27 still likely to change. Although there's a [specification for the current version,][spec] lots of
  28 relatively fundamental aspects of the machine's semantics are still subject to evolution. In fact,
  29 some of the neatest features of the design aren't nailed down into the specification yet (nor are
  30 they implemented in this codebase); so anybody trying to write those abstractions for you is
  31 probably going to have some of their work invalidated in the future. **tl;dr: the Paws design isn't
  32 stable, yet!**
  33
  34 **Okay, well, I like language design. Can I write stuff on top of this machine?** I'm so glad you
  35 asked! You're my favourite kind of person! Assuming you understand the caveat mentioned above (that
  36 this project is in flux), you can *absolutely* start experimenting with abstractions on top of the
  37 Paws machine.
  38
  39 If you want to learn more, you should definitely [grab yourself an IRC client][irc] (I suggest
  40 [IRCCloud][]), or just [click here][webchat], to join the chatroom where we discuss the Paws project
  41 as a whole: [`#ELLIOTTCABLE`][webchat] on Freenode. All newcomers are welcome, and contribution is
  42 hugely appreciated!
  43
  44    [Node.js]: <http://nodejs.org> "A server-side JavaScript platform"
  45    [Paws]: <http://paws.mu> "An asynch-heavy distributed platform for concurrent programming"
  46    [spec]: <http://ell.io/spec> "Specification for the 10th iteration of the Paws design"
  47    [irc]: <http://freenode.net/using_the_network.shtml> "freenode: using the network"
  48    [IRCCloud]: <http://irccloud.com> "IRCCloud, the IRC client of the future"
  49    [webchat]: <http://ell.io/IRC> "Freenode's webchat, for #ELLIOTTCABLE"
  50
  51 Using
  52 -----
  53 This implementation of a Paws machine can be used in two ways: interactively, at the command-line;
  54 or directly, via its embedding API. More information about command-line usage can be acquired by
  55 querying the executable at the command-line:
  56
  57     npm install                     # (Must be run before the executable can be used)
  58     ./Executables/paws.js --help
  59     ./Executables/paws.js interact  # Example, opens an interactive ‘REPL’ to play with
  60
  61 As for embedding the `Paws.js` API, you'll have to dive into the code and poke around a bit, for the
  62 moment. I'm also happy to give you a quick overview, if you join [our channel][webchat] and ask!
  63
  64 *(I swear, API documentation is coming soon! `:P` )*
  65
  66 Contributing
  67 ------------
  68 I consistently put a lot of effort into ensuring that this codebase is easy to spelunk. Hell, I
  69 reduced myself to using [CoffeeScript][], to make everything easier to read! `(=`
  70
  71 Any and all [issues / pull-requests][issues] are welcome. There's a rather comprehensive test-suite
  72 for the reactor itself; it's appreciated if any changes are contributed with passing test-cases, of
  73 course.
  74
  75 After `git clone`'ing the codebase, you should immediately `npm run-script hi`; this will help you
  76 set up your local copy for hacking.
  77
  78 More specific information ~~can be found in [CONTRIBUTING](./blob/Master/CONTRIBUTING.markdown)~~.
  79 (Well, eventually. `>,>`)
  80
  81    [CoffeeScript]: <http://coffeescript.org> "A little language that transpiles into JavaScript"
  82    [issues]: <https://github.com/ELLIOTTCABLE/Paws.js/issues> "Issue-tracker for Paws.js"
  83
  84 <br>
  85 ----
  86 <div align='center' id='npm-and-browser-support'>
  87    <a href="https://npmjs.org/package/paws.js">
  88       <img alt="npm package information" src="https://nodei.co/npm/paws.js.png?downloads=true&stars=true"></a>
  89    <br/><img alt="npm downloads" src="https://nodei.co/npm-dl/paws.js.png?months=9">
  90    <h4>Browser support:</h4>
  91    <a href="https://ci.testling.com/ELLIOTTCABLE/Paws.js">
  92       <img alt="Current browser-support status on HEAD (generated by Testling-CI)" src="https://ci.testling.com/ELLIOTTCABLE/Paws.js.png"> </a>
  93 </div>