{"id":13759702,"url":"https://github.com/soveran/clac","last_synced_at":"2025-12-29T23:43:55.732Z","repository":{"id":40763501,"uuid":"88172722","full_name":"soveran/clac","owner":"soveran","description":"Command-line, stack-based calculator with postfix notation","archived":false,"fork":false,"pushed_at":"2021-09-06T15:03:53.000Z","size":105,"stargazers_count":350,"open_issues_count":7,"forks_count":30,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-03-15T09:21:24.459Z","etag":null,"topics":["calculator","command-line","postfix","stack-based"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/soveran.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-04-13T14:18:26.000Z","updated_at":"2024-03-14T11:58:29.000Z","dependencies_parsed_at":"2022-07-29T12:49:19.872Z","dependency_job_id":null,"html_url":"https://github.com/soveran/clac","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soveran%2Fclac","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soveran%2Fclac/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soveran%2Fclac/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soveran%2Fclac/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soveran","download_url":"https://codeload.github.com/soveran/clac/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224941140,"owners_count":17395828,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["calculator","command-line","postfix","stack-based"],"created_at":"2024-08-03T13:00:58.010Z","updated_at":"2025-12-29T23:43:55.679Z","avatar_url":"https://github.com/soveran.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# Clac\n\nA command line, stack-based calculator with postfix notation that\ndisplays the stack contents at all times. As you type, the stack\nchanges are reflected immediately.\n\n![clac in action](http://files.soveran.com/misc/clac.gif)\n\nIn a stack-based postfix calculator, entering a number pushes it\non a stack, and arithmetic operations pop their arguments from the\nstack and push the result. As all the operations take a fix number\nof arguments, there's no room for ambiguity: parenthesis and operator\nprecedence are not needed. Postfix notation is also known as reverse\nPolish notation, or RPN.\n\nWhy?\n----\n\nI like Forth and other stack based, concatenative languages, and\nI've used the `dc` calculator a lot. Once I got used to `dc`, other\ncalculators seemed to be less powerful. While it has been extremely\nuseful for me, I've always found the UI a bit lacking. That's why\nI decided to try this idea of an always-visible stack with realtime\nupdates.\n\nInstallation\n------------\n\nDownload the [latest release][releases] or check the available\n[packages][packages]. You can also compile the source code in the\nmaster branch.\n\n[releases]: https://github.com/soveran/clac/releases\n[packages]: https://github.com/soveran/clac/wiki/Distribution-Packages\n\nInstall clac into `/usr/local/bin` with the following command:\n\n    $ make install\n\nYou can use `make PREFIX=/some/other/directory install` if you wish\nto use a different destination. If you want to remove clac from\nyour system, use `make uninstall`.\n\nCommands\n--------\n\nWhen a command requires an argument, it pops a value from the stack.\nIf the stack is empty, a zero is provided instead. In the descriptions\nbelow, the top of the stack (and thus the first value popped) is\nrepresented by the letter `a`, while the second value popped is\nrepresented by the letter `b`. For example, if the stack is composed\nof the number `1`, `2` and `3` (with `3` at the top of the stack),\nwhen we describe the sum then `a` will be `3` and `b` will be `2`.\nIt is important to note that subtraction and division invert the\norder of the arguments before performing the operation: with `1`,\n`2` and `3` in the stack, when you type `-` it will pop the values\n`3` and `2` and push the result of `2 - 3`. This is in the tradition\nof other postfix calculators and programming languages.\n\nHere's a description of the available commands:\n\n### Arithmetic operations\n\n`+`\nPop two values `a` and `b` and push the result of `a + b`.\n\n`-`\nPop two values `a` and `b` and push the result of `b - a`.\n\n`*`\nPop two values `a` and `b` and push the result of `a * b`.\n\n`/`\nPop two values `a` and `b` and push the result of `b / a`.\n\n### Modulo operation\n\n`%`\nPop two values `a` and `b` and push the remainder of the Euclidean\ndivision of `b` by `a`.\n\n### Exponentiation\n\n`^`\nPop two values `a` and `b` and push the result of `b ^ a`.\n\n### Logarithm\n\n`ln`\nPop the value `a` and push its natural logarithm.\n\n`log`\nPop the value `a` and push its logarithm to base 10.\n\n### Factorial\n\n`!`\nPop the value `a` and push its factorial.\n\n### Trigonometry\n\n`sin`\nPop the value `a` and push its sine.\n\n`cos`\nPop the value `a` and push its cosine.\n\n`tan`\nPop the value `a` and push its tangent.\n\n`asin`\nPop the value `a` and push its arc sine.\n\n`acos`\nPop the value `a` and push its arc cosine.\n\n`atan`\nPop the value `a` and push its arc tangent.\n\n`atan2`\nPop two values `a` and `b` and push the arc tangent of `b / a`,\nusing the signs of `a` and `b` to determine the quadrant.\n\n### Error function\n\n`erf`\nPop the value `a` and push its error function.\n\n### Summation\n\n`sum`\nPop all the values in the stack and push their sum.\n\n`add`\nPop the value `a` and remove that many items from the stack. Push\ntheir sum.\n\n### Product\n\n`prod`\nPop all the values in the stack and push their product.\n\n`mul`\nPop the value `a` and remove that many items from the stack. Push\ntheir product.\n\n### Rounding\n\n`ceil`\nPop the value `a` and push the smallest integer value greater than or\nequal to `a`.\n\n`floor`\nPop the value `a` and push the largest integer value less than or\nequal to `a`.\n\n`round`\nPop the value `a` and push the integer value closest to `a`.\n\n### Absolute value\n\n`abs`\nPop the value `a` and push the non-negative value of `a`.\n\n### Binary operations\n\n`and`\nPop two values `a` and `b` and push the binary AND of `a` and `b`.\n\n`or`\nPop two values `a` and `b` and push the binary OR of `a` and `b`.\n\n`xor`\nPop two values `a` and `b` and push the binary XOR of `a` and `b`.\n\n### Stack manipulation\n\n`swap`\nPop two values `a` and `b` and push the values `a`, `b`.\n\n`dup`\nPop the value `a` and push the values `a`, `a`.\n\n`roll`\nPop two values `a` and `b` and rotate `b` elements in the stack `a`\ntimes.\n\n`drop`\nRemove the top of the stack.\n\n`clear`\nRemove all the elements in the stack.\n\n`count`\nPush the number of items in the stack.\n\n`_`\nPush on the stack the result of the last operation.\n\n### Stashing\n\n`stash`\nPop the value `a` and move that many items to the stash.\n\n`fetch`\nPop the value `a` and move that many items from the stash.\n\n`.`\nStash the top of the stack.\n\n`,`\nFetch one stashed item.\n\n`:`\nStash all the items in the stack.\n\n`;`\nFetch all stashed items.\n\nHistory\n-------\n\nUse `\u003cC-p\u003e`/`\u003cC-n\u003e` or the `\u003cUp\u003e`/`\u003cDown\u003e` arrow keys to navigate\nthe history.\n\nUser defined operations\n-----------------------\n\nIt is possible to define operations (or _words_, as they are usually\ncalled in stack based programming languages) by editing the `words`\nconfiguration file. It is not created by default, but clac will use\nsome environment variables in order to search for word definitions.\n\n`$CLAC_WORDS`\nIf set, it should point to a file containing word definitions.\n\n`$XDG_CONFIG_HOME`\nIf set, clac will search for `$XDG_CONFIG_HOME/clac/words`.\n\n`$HOME`\nIf set, clac will search for `$HOME/.config/clac/words`.\n\n### How to define words\n\nWords are defined as aliases, with one alias on each line.\nEmpty lines are ignored. Here are some examples:\n\n```shell\npi 3.14159265358979323846\n# this is a comment\ntau \"pi 2 *\"\nsqrt \"0.5 ^\"\n```\n\nNote that an alias has two parts: a word to be defined and its\nmeaning. That's why the `tau` and `sqrt` definitions are enclosed\nin double quotes. If the double quotes are removed, clac will\ncomplain that it can't parse the command. For example, if we remove\nthe double quotes from `sqrt` and start clac, we will get this error\nmessage:\n\n```\nIncorrect definition: sqrt 0.5 ^\n(~/.config/clac/words:3)\n```\n\nUser defined words can be used as if they were built-in commands:\n\n```shell\n$ clac \"42 dup * pi *\"\n5541.76944093239\n```\n\n### Comments\n\nAny lines that begin with `#` are considered comments and\nare ignored. There are no inline comments, and any `#`\ncharacters that are not the first character of a line are\ninterpreted literally. To define `#` as a word, wrap it in\ndouble quotes in the definition:\n\n```shell\n# This is a comment.\n\"#\" count\n```\n\nThe first line is ignored, and the second line assigns `#`\nto the operation `count`.\n\n### How to list defined words\n\nIf you type `words` and hit enter, clac will list the defined words.\n\n### How to reload defined words\n\nIf you type `reload` and hit enter, clac will reload the words file.\n\nNon-interactive mode\n--------------------\n\nWhile the most interesting aspect of clac is the ability to visualize\nthe stack as it is updated with each key press, at some point you\nmay want use clac just to get a quick result or call it from a\nscript. For that reason, clac can be used in non-interactive mode\nby invoking it with an argument.\n\n### Examples\n\nHere are some examples of non-interactive invocations:\n\n```shell\n$ clac \"3 4 +\"\n7\n\n$ clac \"2 3 4 +\"\n7\n2\n```\n\nWhen clac finishes evaluating the expression \"2 3 4 +\", there are\ntwo elements in the stack: the number 7 at the top of the stack and\nthe number 2 at the bottom of the stack. The elements are printed\nin order, one per line, starting from the top of the stack.\n\nThis other example uses the stashing features. Let's say we want\nto push two numbers and get the result of their multiplication plus\nthe square of the second number.\n\n```shell\n$ clac \"4 3 dup dup * . * , +\"\n21\n```\n\nAnother example that uses the stash would be to get the average of\nall the elements in the stack:\n\n```shell\n$ clac \"1 2 3 4 count . sum , /\"\n2.5\n```\n\nIn fact, if you find yourself calculating averages very often, you\ncan define the word `avg` as `\"count . sum , /\"`.\n\nContributing\n------------\n\nIf you find a bug, please create an issue detailing the ways to\nreproduce it. If you have a suggestion, create an issue detailing\nthe use case.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoveran%2Fclac","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoveran%2Fclac","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoveran%2Fclac/lists"}