diff --git a/.arcconfig b/.arcconfig new file mode 100644 --- /dev/null +++ b/.arcconfig @@ -0,0 +1,4 @@ +{ + "phabricator.uri": "https://dev.xkqr.org/", + "repository.callsign": "UTEC" +} diff --git a/LICENCE b/LICENCE new file mode 100644 --- /dev/null +++ b/LICENCE @@ -0,0 +1,13 @@ +Copyright (c) kqr 2018 + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH +REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND +FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, +INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR +OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +PERFORMANCE OF THIS SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 --- /dev/null +++ b/README.md @@ -0,0 +1,172 @@ +emacscalc +========= + +`emacscalc` (or `ec`) is a script that lets you run the Emacs built-in +calculator calc-mode "stand-alone", without needing to first open Emacs. + +Why would anyone do this? + +Because calc-mode ROCKS. + +Seriously. + +It's extremely powerful, yet incredibly keyboard efficient. Ironically enough, +it can be accurately described as "the Vim of calculators". + +If you use any other calculator, try spending a week with calc-mode. + + +### “But I don't use Emacs.” + +I'm not forcing you to use Emacs for your text editor. Or your file manager. Or +your contact management, or anything else, really, other than for your +calculator. + +Emacs is a software development platform, and calc-mode happens to have been +built on Emacs. If that is a problem with you, then it sucks to be you. It could +just as well have been Java – but it was Emacs, so install Emacs and run this +script and you'll get the best calculator you've ever had. + + +Installation +------------ + +To install, simply copy the `emacscalc.sh` script to somewhere in your `$PATH`. +Give it the old executable bit if you want to run it like a command. + +If you are going to use `emacscalc` from the command line, It may be a good idea +to rename the script to something short and sweet: I chose `ec`, mirroring the +names of the `bc` and `dc` calculators. + +However, I strongly recommend creating a keyboard shortcut in your desktop +environment to launch the "graphical" `emacscalc`. This has been really +convenient. In order to launch it in graphical mode, you need to pass the `-g` +flag to the script. (The script defaults are optimised for command line use, +because with graphical usage specifying additional flags tends not to be an +issue.) + + + +Screenshots +----------- + +At the moment, it looks rather dreadful (well, it looks like a default Emacs +would, I suppose), so no screenshots are provided. This may change (either or +both)! + + +Fundamentals +------------ + +In contrast to many other calculators, `ec` is based on postfix operation, or +reverse Polish notation, as it is also known. In other words, if you need to +calculate the integer value of + + 4 * (5 - 2) + 1 + --------------- + 3 + +You don't press + + ( 4 * ( 5 - 2 ) + 1 ) / 3 = + +You also don't press + + 5 - 2 = * 4 = + 1 = / 3 = + +instead, you press either + + 4 5 2 - * 1 + 3 / + +or, if you still want to do the parentheses first because that makes it easier +to keep track of things, + + 5 2 - 4 * 1 + 3 / + +If you are anything like me, you read this and think that `ec` is just some +weird experiment into old-school technologies, and not fit for actual use. + +Far from true. Postfix notation still has some hardcore followers because it +simply makes entering calculations easier and more efficient[citation needed]. +Once you're used to it – which doesn't take long – you'll want it everywhere +(and I can recommend the RealCalc app for Android). + +Whenever you enter a number in `ec`, it gets pushed onto the stack. When you +enter an operator or a function, it pops off the stack as many numbers as it +needs, and then pushes the result back onto the stack. + + +Getting Help +------------ + +If you need help in `ec`, pressing the key `h` twice will bring up a handy +summary of what to press to get most operators and functions. It's a good cheat +sheet until you've memorised them. + +To get started, it may be a good idea to go through the tutorial. You can open +that by pressing `h` followed by `t`. + +If you want to read the complete user guide, press `h` followed by `i`. It's a +big document though, so starting with the tutorial and cheat sheet is advisable. + + +Tips +---- + +Here, I plan on collecting various tips and tricks. Actually, mostly for my own +memory. But I am also happy to receive ideas! + +If a description talks about pressing `ctrl-k`, that means holding down the control key and +gently tapping the `k` key. If it talks about typing `f G`, that means first +tapping (including releasing) the `f` key, followed by holding the shift key and +tapping the `g` key (to produce an upper case `G`.) + +In other words, dashes indicate when you hold keys down together, and spaces +indicate that keys are to be released between presses. + + +### Beginner + + +### Intermediate + +#### Convert binary to decimal + +If you press `ctrl-2` before pasting a number into `ec`, it will be interpreted +as a binary number. Since `ec` by default displays all numbers in decimal, you +can read out the decimal conversion as soon as you have pasted it. + +Another way to enter a binary number is to lead it with `2#`. So if we have the +binary number 1010111 we can enter it as `2#1010111` and the stack will show 87. + + +#### Convert decimal to binary + +Unless you specify otherwise, any number you insert is interpreted as decimal. +So to convert decimal to binary, simply switch `ec` into binary mode by typing +`d 2`. If your number is on the stack already, it'll now show the binary +representation of it. If not, simply enter a decimal number and it'll show in binary! + + +#### Count with time! + +I am terrible at counting anything that's not base ten. That includes the time +of the day. Fortunately for me, `ec` can do it for me! In at least two ways, +depending on how large time spans we're talking about. + +1. If you want to count on the scale of hours, you can use the + "degree-arcminute-arcsecond" format. Since there are 60 arcseconds to an + arcminute, and 60 arcminutes to a degree, you can just pretend they are + referring to regular minutes and seconds, and that the degrees are hours. + + In this format, 8:45:32 PM would be entered as `20@ 47' 32"`. if we want to + know how long that was since half past noon that day, we simply enter that, followed + by `12@ 30'`, and press `-` to subtract the two! + +2. If you want to count on the scale of days, you'll need to use the date + counting functionalities in `ec`. It is somewhat flexible in the formats it + accepts, but I find the easiest to be something like `'<8:47:32 pm feb 25 + 2018>`. These days are also eligible for addition, subtraction and whatnot. + + +### Advanced \ No newline at end of file diff --git a/emacscalc.sh b/emacscalc.sh new file mode 100755 --- /dev/null +++ b/emacscalc.sh @@ -0,0 +1,71 @@ +#!/bin/sh + +# Version of script +version="0.1.2" + +help() { + echo "Usage: $(basename $0) [-h] [-v] [-g] [-x] [-U] + + Run the Emacs calculator. + + -h Show this help + -v Show version + -g Open in graphical window, not the terminal + -x Disable CUA mode (Emacs default, less novice-friendly) + -U Load users' Emacs configuration (slower startup)" + exit +} + +version() { + echo "emacscalc (Emacs Calculator) version $version" + echo "Copyright (c) kqr 2018" + echo + echo -n "Tapping into the power of " + emacs --version | head -n 2 + exit +} + + +# Default options +nw="-nw" +cua="+1" +user="-Q" + +while getopts "hgxv" name; do + case "$name" in + h) help ;; + g) nw="";; + x) cua="-1";; + v) version ;; + U) user="";; + *) help ;; + esac +done + + +emacs $nw $user --eval="(progn + (tool-bar-mode -1) + (scroll-bar-mode -1) + (menu-bar-mode -1) + + (setq + select-enable-primary t + help-window-select t) + + (cua-mode $cua) + (when cua-mode + (defun calc-mode? () + (eq major-mode (quote calc-mode))) + + (define-advice cua-paste (:before-while (arg)) + (and (calc-mode?) (calc-yank arg)))) + + (full-calc) + + (define-key calc-mode-map [?q] + (quote save-buffers-kill-terminal)) + + (define-advice calc-full-help (:after nil) + (switch-to-buffer-other-window \"*Help*\") + (message \"Press q to go back to calc\")))" +