cream-and-sugar

<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Cream & Sugar: Built-In Functions</title> <link rel="icon" type="image/x-icon" href="https://jgnewman.github.io/cream-and-sugar/assets/images/favicon.ico" /> <link href="https://fonts.googleapis.com/css?family=Bitter:400,700|Open+Sans:300,400,800" rel="stylesheet"> <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/normalize/5.0.0/normalize.min.css" /> <link rel="stylesheet" href="../../assets/css/app.css"> <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.8.0/styles/default.min.css"> <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.8.0/highlight.min.js"></script> </head> <body class="docs"> <div class="branding"></div> <div class="content"> <div class="left-border"> <h1>Built-In Functions</h1> <h2 class="subhead">The Creamiest, Surgariest Part</h2> </div> <p>C&S comes packaged with a few useful functions right off the bat. You don't need to import them or reference them on some kind of global C&S object. They are just available for you to use whenever you want.</p> <p>Following is a list of all built-in functions as well as descriptions of how to use them and what you can expect them to return.</p> <h4 id="apply-fun-argsarray-">apply fun [, argsArray]</h4> <pre><code>apply fn => 2 + 2 #=> 4 apply fn x => x + 2, [2] #=> 4 </code></pre><ul> <li><code>fun {Function}</code>: Any type of function.</li> <li><code>argsArray {Array}</code>: Optional. An array of arguments to be passed to the function.</li> </ul> <p>Invokes <code>fun</code> and returns the result. If <code>argsArray</code> is provided, passes those arguments to the function when invoked.</p> <h4 id="aritize-fun-arity">aritize fun, arity</h4> <pre><code>iterate list => iterate list, [] iterate [], accum => accum iterate [h|t], accum => iterate t, accum << h # Only allow users to call `iterate` # with 1 argument export aritize iterate, 1 </code></pre><ul> <li><code>fun {Function}</code>: Any type of function.</li> <li><code>arity {Number}</code>: The allowed arity to lock the function into.</li> </ul> <p>Returns a new function that can only be called with the number of arguments provided as <code>arity</code>. If the function is called with any other number of arguments, an error will be thrown.</p> <h4 id="arraytotuple-arr">arrayToTuple arr</h4> <pre><code>arrayToTuple [ 1, 2, 3 ] #=> {{ 1, 2, 3 }} </code></pre><ul> <li><code>arr {Array}</code>: Any array.</li> </ul> <p>Creates a new tuple from items in an array.</p> <h4 id="cache-fun">cache fun</h4> <pre><code>foo = cache fn x => x foo 4 #=> 4 foo 6 #=> 4 </code></pre><ul> <li><code>fun {Function}</code>: Any function.</li> </ul> <p>The <code>cache</code> function takes a function as its argument and returns a new function that will cache its result after being executed once. Having been cached, you can call this function as many times as you want and it will immediately return the cached value without having to execute the original function again.</p> <p>Cached functions may be "reset" by calling the <code>decache</code> bif.</p> <h4 id="create-klass-constructorargs-">create klass [, ...constructorArgs]</h4> <pre><code>create Date #=> Fri Sep 09 2016 17:00:43 GMT-0400 (EDT) create Error, "This is error text." #=> Error: This is error text(…) </code></pre><ul> <li><code>klass {Function}</code>: A class constructor.</li> <li><code>constructorArgs {Any}</code>: Any arguments to be passed to the class constructor.</li> </ul> <p>Creates a new instance of <code>klass</code> by passing <code>constructorArgs</code> to the constructor. Returns the new class instance.</p> <h4 id="dangerouslymutate-key-value-collection">dangerouslyMutate key, value, collection</h4> <pre><code>location.href #=> 'http://example.com' dangerouslyMutate 'href', '/foo', location location.href #=> 'http://example.com/foo' </code></pre><ul> <li><code>key {String|Number|Atom}</code>: An object key or array index.</li> <li><code>value {Any}</code>: Any type of data.</li> <li><code>collection {Any Object-like type}</code>: Any kind of JavaScript collection.</li> </ul> <p>Breaks the functionalism paradigm by mutating an existing object instead of creating a new one. This is necessary for certain JavaScript techniques such as updating <code>location.href</code>.</p> <h4 id="datatype-data">dataType data</h4> <pre><code>dataType 'hello' #=> 'string' dataType 3.4 #=> 'number' dataType NaN #=> 'nan' dataType null #=> 'null' dataType [1, 2, 3] #=> 'array' dataType /^foo$/ #=> 'regexp' dataType <div></div> #=> 'htmlelement' dataType (create Date) #=> 'date' dataType undefined #=> 'undefined' dataType OK #=> 'atom' dataType (spawn fn => 'hello') #=> 'process' dataType fn => 'hello' #=> 'function' dataType {foo: 'bar'} #=> 'object' dataType {{ x, y }} #=> 'tuple' </code></pre><ul> <li><code>data {Any}</code>: Any data type.</li> </ul> <p>Intelligently and reasonably assesses data types and returns a string identifying the type of <code>data</code>. Possible return values include:</p> <ul> <li>string</li> <li>number</li> <li>nan</li> <li>null</li> <li>array</li> <li>regexp</li> <li>htmlelement</li> <li>date</li> <li>undefined</li> <li>atom</li> <li>process</li> <li>function</li> <li>object</li> <li>tuple</li> </ul> <h4 id="debug-message">debug message</h4> <pre><code>debug 'Something was weird' #=> undefined </code></pre><ul> <li><code>message {String}</code>: A message to log to the console.</li> </ul> <p>A shortcut for JavaScript's <code>console.debug(message)</code>. Attempts to default to <code>console.log</code> if <code>console.debug</code> does not exist. If the <code>console</code> object does not exists, fails silently.</p> <h4 id="decache-fun">decache fun</h4> <pre><code>foo = cache fn x => x foo 4 #=> 4 foo 6 #=> 4 decache foo foo 6 #=> </code></pre><ul> <li><code>fun {Function}</code>: Any function.</li> </ul> <p>The <code>cache</code> function caches a function such that it stores its result having been executed one time. Calling <code>decache</code> on that same function will reset it such that it will cache itself again on the next execution.</p> <h4 id="die-message">die message</h4> <pre><code>die 'This app is not working' #=> undefined </code></pre><ul> <li><code>message {String}</code>: An error message.</li> </ul> <p>A shortcut for JavaScript's <code>throw new Error(message)</code>.</p> <h4 id="dom-selector">dom selector</h4> <pre><code>dom '#my-div' #=> HTMLElement dom 'div' #=> HTMLElement </code></pre><ul> <li><code>selector {String}</code>: Identifies the criteria for selecting a DOM element.</li> </ul> <p>Locates and returns a single DOM element identified by <code>selector</code>. If no element was found, returns <code>null</code>.</p> <h4 id="domarray-selector">domArray selector</h4> <pre><code>domArray '#my-div' #=> [HTMLElement] domArray 'div' #=> [HTMLElement, HTMLElement, HTMLElement] </code></pre><ul> <li><code>selector {String}</code>: Identifies the criteria for selecting DOM elements.</li> </ul> <p>Locates and returns a real array of DOM elements identified by <code>selector</code>. If no element was found, returns an empty array.</p> <h4 id="eql-a-b">eql a, b</h4> <pre><code>eql 4, 4 #=> true eql 4, "4" #=> false eql [1, 2, 3], [1, 2, 3] #=> true eql [1, 2, 3], [2, 3, 1] #=> false eql [1, 2, {a: 'b'}], [1, 2, {a: 'b'}] #=> true </code></pre><ul> <li><code>a {Any}</code>: Any type of data.</li> <li><code>b {Any}</code>: Any type of data.</li> </ul> <p>Determines whether <code>a</code> and <code>b</code> are deep equal by strict comparison and returns either <code>true</code> or <code>false</code>.</p> <p><br/> <br/></p> <h4 id="get-key-collection">get key, collection</h4> <pre><code>get 2, ['a', 'b', 'c', 'd'] #=> 'c' get 'foo', {foo: 'bar', baz: 'quux'} #=> 'bar' get FOO, {FOO: 'bar'} #=> 'bar' </code></pre><ul> <li><code>key {String|Number|Atom}</code>: An object key or array index.</li> <li><code>collection {Any Object-like type}</code>: Any kind of JavaScript collection.</li> </ul> <p>Retrieves an element identified by <code>key</code> from <code>collection</code> and returns the element.</p> <h4 id="head-list">head list</h4> <pre><code>head [1, 2, 3] #=> 1 head [1] #=> 1 head [] #=> undefined </code></pre><ul> <li><code>list {Array|Tuple|String}</code>: An list type.</li> </ul> <p>Returns the first item in a list or <code>undefined</code> if there are no items.</p> <h4 id="instanceof-data-constructor">instanceof data, constructor</h4> <pre><code>instanceof {}, Object #=> true instanceof 4, Object #=> false </code></pre><ul> <li><code>data {Any}</code>: Any type of data.</li> <li><code>constructor {Function}</code>: A class constructor function.</li> </ul> <p>Calls JavaScript's <code>instanceof</code> statement and returns the result, either <code>true</code> or <code>false</code>.</p> <h4 id="kill-process">kill process</h4> <pre><code>process = spawn fn => log "I'm alive!" kill process </code></pre><ul> <li><code>process {Process}</code>: A process created using the <code>spawn</code> function.</li> </ul> <p>Terminates the process. Returns <code>undefined</code>.</p> <h4 id="lang-key-value">lang key, value</h4> <pre><code>lang 'use.react', false #=> undefined </code></pre><ul> <li><code>key {String}</code>: Any string.</li> <li><code>value {Any}</code>: Any value.</li> </ul> <p>Sets thread-level configuration options for the language. For example, <code>lang 'use.react', false</code> will prevent trying to use React when compiling JSX-like syntax.</p> <p>Note that these are runtime configuration options. They are not hoisted and may be used anywhere within your code. Each thread in your application will also have access to its own set of configuration options so setting an option within a child process will not affect code running in the host thread.</p> <p>Returns <code>undefined</code>.</p> <h5 id="current-config-options">Current Config Options</h5> <p><code>use.react</code> - {Boolean} Defaults to true. Determines whether C&S will try to use React.js when compiling JSX-like syntax.</p> <p>This list is expected to be expanded.</p> <h4 id="last-list">last list</h4> <pre><code>last [1, 2, 3] #=> 3 last [1] #=> 1 last [] #=> undefined </code></pre><ul> <li><code>list {Array|Tuple|String}</code>: A list type.</li> </ul> <p>Returns the last item in a list or <code>undefined</code> if there are no items.</p> <h4 id="lead-list">lead list</h4> <pre><code>lead [1, 2, 3] #=> [1, 2] lead [1] #=> [] lead [] #=> [] </code></pre><ul> <li><code>list {Array|Tuple|String}</code>: A list type.</li> </ul> <p>Returns a new array of all but the last item in <code>list</code>, or an empty array if there are no items or only 1 item.</p> <h4 id="log-message">log message</h4> <pre><code>log 'This app is great!' #=> undefined </code></pre><ul> <li><code>message {String}</code>: A message to log to the console.</li> </ul> <p>A shortcut for JavaScript's <code>console.log(message)</code>. If the <code>console</code> object does not exists, fails silently.</p> <h4 id="random-array">random array</h4> <pre><code>random [1, 2, 3] #=> 2 random [1, 2, 3] #=> 1 </code></pre><ul> <li><code>array {Array}</code>: An array.</li> </ul> <p>Selects a random item from <code>array</code> and returns the item.</p> <h4 id="range-from-through">range from, through</h4> <pre><code>range 1, 10 #=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] </code></pre><ul> <li><code>from {Number}</code>: Any whole number.</li> <li><code>through {Number}</code>: Any whole number.</li> </ul> <p>Creates an array containing a range of numbers from <code>from</code> through <code>through</code>.</p> <h4 id="receive-fun">receive fun</h4> <pre><code>receive match {{ OK, msg }} => doSomethingWith msg {{ ERR, msg }} => throw (create Error, msg) </code></pre><ul> <li><code>fun {Function}</code>: Any type of function including a <code>fn</code>, a <code>def</code> block, or a <code>match</code> block.</li> </ul> <p>Registers a handler for dealing with messages that come in from a separate process. Returns <code>undefined</code>.</p> <h4 id="remove-key-collection">remove key, collection</h4> <pre><code>remove 'foo', {foo: 'bar', baz: 'quux'} #=> {baz: 'quux'} remove 1, ['a', 'b', 'c'] #=> ['a', 'c'] </code></pre><ul> <li><code>key {String|Number|Atom}</code>: An object key or array index.</li> <li><code>collection {Any Object-like type}</code>: Any kind of JavaScript collection.</li> </ul> <p>Creates a shallow clone of <code>collection</code> not including the item identified by <code>key</code>.</p> <h4 id="reply-message">reply message</h4> <pre><code>reply {{ OK, 'This is my message.' }} </code></pre><ul> <li><code>message {Any Serializable Data|Atom}</code>: A message to send to an owner process.</li> </ul> <p>Sends <code>message</code> from a child process to an owner process. Returns <code>undefined</code>.</p> <h4 id="send-process-message">send process, message</h4> <pre><code>process = spawn fn => receive fn msg => console.log 'I got', msg send process, 'hello' #=> Logs: "I got hello" </code></pre><ul> <li><code>process {Process}</code>: A process created using the <code>spawn</code> function.</li> <li><code>message {Any Serializable Data|Atom}</code>: A message to send to a owner process.</li> </ul> <p>Sends <code>message</code> to <code>process</code>. Returns <code>undefined</code>.</p> <h4 id="spawn-fun">spawn fun</h4> <pre><code>process = spawn fn => console.log "I'm alive!" </code></pre><ul> <li><code>fun {Function}</code>: Any type of function, but normally an anonymous <code>fn</code>.</li> </ul> <p>Creates a new operating system process out of <code>fun</code>.</p> <h4 id="tail-list">tail list</h4> <pre><code>tail [1, 2, 3] #=> [2, 3] tail [1] #=> [] tail [] #=> [] </code></pre><p><code>list {Array|Tuple|String}</code>: An list type.</p> <p>Returns a new array of all but the first item in <code>list</code>, or an empty array if there are no items or only 1 item.</p> <h4 id="throw-err">throw err</h4> <pre><code>throw (create Error, 'This is an error message') </code></pre><ul> <li><code>err {Error}</code>: Any instance of any kind of error object.</li> </ul> <p>Throws an error.</p> <h4 id="tupletoarray-tuple">tupleToArray tuple</h4> <pre><code>tupleToArray {{ 1, 2, 3 }} #=> [1, 2, 3] </code></pre><ul> <li><code>tuple {Tuple}</code>: Any tuple.</li> </ul> <p>Creates a new array from items in a tuple.</p> <h4 id="tupletoobject-tuple-fun">tupleToObject tuple, fun</h4> <pre><code>tupleToObject {{ fun1, fun2 }}, fn item => item.name #=> {'fun1': fun1, 'fun2': fun2} </code></pre><ul> <li><code>tuple {Tuple}</code>: Any tuple.</li> <li><code>fun {Function}</code>: Optional. An iterator function taking <code>item</code> and <code>index</code>.</li> </ul> <p>Creates an object from a tuple where <code>fun</code> is used to determine how to construct key names for each item in the tuple. If <code>fun</code> is not provided, indices will be used as object keys.</p> <h4 id="update-key-value-collection">update key, value, collection</h4> <pre><code>obj = {foo: 'bar', baz: 'quux'} update 'foo', 'Billy', obj #=> {foo: 'Billy', baz: 'quux'} </code></pre><ul> <li><code>key {String|Number|Atom}</code>: An object key or array index.</li> <li><code>value {Any}</code>: Any type of data.</li> <li><code>collection {Any Object-like type}</code>: Any kind of JavaScript collection.</li> </ul> <p>Creates a shallow clone of <code>collection</code> wherein the value for <code>key</code> has been updated to <code>value</code>.</p> <h4 id="warn-message">warn message</h4> <pre><code>warn 'Something was weird' #=> undefined </code></pre><ul> <li><code>message {String}</code>: A message to log to the console.</li> </ul> <p>A shortcut for JavaScript's <code>console.warn(message)</code>. Attempts to default to <code>console.log</code> if <code>console.warn</code> does not exist. If the <code>console</code> object does not exists, fails silently.</p> </div> <section id="docs-app"></section> <script> // Section for random JavaScript hacks just to get this out quickly. window.addEventListener('load', function () { // Fix indentation in code blocks the best we can since panini's // markdown compiler injects whitespace into pre tags. Array.prototype.slice.call(document.querySelectorAll('pre code')).forEach(function (code) { var lines = code.innerHTML.trim().split('\n'); var out = [lines[0]]; var sliceAmount; lines.slice(1).forEach(function (line, index) { if (index === 0) { var whitespace = line.match(/^\s+/); whitespace = whitespace ? whitespace[0] : ''; if (/([=-](\>)?|\{|match|\>|div|try|chain|default\s+[^\n])$/.test(lines[0])) { whitespace = whitespace.slice(2); } sliceAmount = whitespace; } out.push(line.replace(sliceAmount, '')); }); code.innerHTML = out.join('\n'); code.className = 'visible lang-coffeescript'; hljs.highlightBlock(code); }); // Attach id's to h4 tags so that we can link to specific bifs. Array.prototype.slice.call(document.querySelectorAll('h4')).forEach(function (h4) { var html = h4.innerHTML.split(/\s+/g); html[0] = '<span class="bif" id="' + html[0] + '">' + html[0] + '</span>'; h4.innerHTML = html.join(' '); h4.className = 'visible'; }); // Fix relative link issues with the github site living in a subdirectory Array.prototype.slice.call(document.querySelectorAll('.content a')).forEach(function (a) { if (/^\/cream-and-sugar\//.test(location.pathname)) { a.setAttribute('href', '/cream-and-sugar' + a.getAttribute('href')) } }); // Some script conflict is preventing us from linking to a certain // spot on the page so here we just wait until the next run loop // and if we have a hash in the location object, scroll to it. (function () { var hash = location.hash; if (hash) { var item = document.querySelector(hash); setTimeout(function () { item && window.scroll(0, item.offsetParent.offsetTop); },0); } }()); // Fixes a responsiveness issue where on large screens sometimes // the offgray sidebar isn't tall enough. Make sure its always // tall enough whenever the screen resizes. (function () { var branding = document.querySelector('.branding'); var content = document.querySelector('.content'); function resizerizer() { var brandingHeight = branding.offsetHeight; content.style.height = ''; if (content.offsetHeight < brandingHeight) { content.style.height = brandingHeight + 'px'; } } window.addEventListener('resize', resizerizer); resizerizer(); }()); }); </script> <script src="../../assets/js/app.js"></script> </body> </html>