summaryrefslogtreecommitdiffhomepage
path: root/m.html.markdown
diff options
context:
space:
mode:
Diffstat (limited to 'm.html.markdown')
-rw-r--r--m.html.markdown370
1 files changed, 370 insertions, 0 deletions
diff --git a/m.html.markdown b/m.html.markdown
new file mode 100644
index 00000000..d0879ab6
--- /dev/null
+++ b/m.html.markdown
@@ -0,0 +1,370 @@
+---
+language: M (MUMPS)
+contributors:
+ - ["Fred Turkington", "http://z3ugma.github.io"]
+filename: LEARNM.m
+---
+
+M, or MUMPS (Massachusetts General Hospital Utility Multi-Programming System) is
+a procedural language with a built-in NoSQL database. Or, it’s a database with
+an integrated language optimized for accessing and manipulating that database.
+A key feature of M is that accessing local variables in memory and persistent
+storage use the same basic syntax, so there's no separate query
+language to remember. This makes it fast to program with, especially for
+beginners. M's syntax was designed to be concise in an era where
+computer memory was expensive and limited. This concise style means that a lot
+more fits on one screen without scrolling.
+
+The M database is a hierarchical key-value store designed for high-throughput
+transaction processing. The database is organized into tree structures called
+"globals", which are sparse data structures with parallels to modern formats
+like JSON.
+
+Originally designed in 1966 for the healthcare applications, M continues to be
+used widely by healthcare systems and financial institutions for high-throughput
+real-time applications.
+
+### Example
+
+Here's an example M program to calculate the Fibonacci series:
+
+```
+fib ; compute the first few Fibonacci terms
+ new i,a,b,sum
+ set (a,b)=1 ; Initial conditions
+ for i=1:1 do quit:sum>1000
+ . set sum=a+b
+ . write !,sum
+ . set a=b,b=sum
+```
+
+### Comments
+
+```
+; Comments start with a semicolon (;)
+```
+### Data Types
+
+M has two data types:
+
+```
+; Numbers - no commas, leading and trailing 0 removed.
+; Scientific notation with 'E'.
+; Floats with IEEE 754 double-precision values (15 digits of precision)
+; Examples: 20, 1e3 (stored as 1000), 0500.20 (stored as 500.2)
+; Strings - Characters enclosed in double quotes.
+; "" is the null string. Use "" within a string for "
+; Examples: "hello", "Scrooge said, ""Bah, Humbug!"""
+```
+### Commands
+
+Commands are case insensitive, and have a shortened abbreviation, often the first letter. Commands have zero or more arguments,depending on the command. M is whitespace-aware. Spaces are treated as a delimiter between commands and arguments. Each command is separated from its arguments by 1 space. Commands with zero arguments are followed by 2 spaces.
+
+#### W(rite)
+
+Print data to the current device.
+
+```
+WRITE !,"hello world"
+```
+
+! is syntax for a new line. Multiple statements can be provided as additional arguments:
+
+```
+w !,"foo bar"," ","baz"
+```
+
+#### R(ead)
+
+Retrieve input from the user
+
+```
+READ var
+r !,"Wherefore art thou Romeo? ",why
+```
+Multiple arguments can be passed to a read command. Constants are outputted. Variables are retrieved from the user. The terminal waits for the user to enter the first variable before displaying the second prompt.
+
+```
+r !,"Better one, or two? ",lorem," Better two, or three? ",ipsum
+```
+
+#### S(et)
+
+Assign a value to a variable
+
+```
+SET name="Benjamin Franklin"
+s centi=0.01,micro=10E-6
+w !,centi,!,micro
+
+;.01
+;.00001
+```
+#### K(ill)
+
+Remove a variable from memory or remove a database entry from disk.
+
+```
+KILL centi
+k micro
+```
+### Globals and Arrays
+
+In addition to local variables, M has persistent variables stored to disk called _globals_. Global names must start with a __caret__ (__^__). Globals are the built-in database of M.
+
+Any variable can be an array with the assignment of a _subscript_. Arrays are sparse and do not have a predefined size. Arrays should be visualized like trees, where subscripts are branches and assigned values are leaves. Not all nodes in an array need to have a value.
+
+```
+s ^cars=20
+s ^cars("Tesla",1,"Name")="Model 3"
+s ^cars("Tesla",2,"Name")="Model X"
+s ^cars("Tesla",2,"Doors")=5
+
+w !,^cars
+; 20
+w !,^cars("Tesla")
+; null value - there's no value assigned to this node but it has children
+w !,^cars("Tesla",1,"Name")
+; Model X
+```
+
+Arrays are automatically sorted in order. Take advantage of the built-in sorting by setting your value of interest as the last child subscript of an array rather than its value.
+
+```
+; A log of temperatures by date and time
+s ^TEMPS("11/12","0600",32)=""
+s ^TEMPS("11/12","1030",48)=""
+s ^TEMPS("11/12","1400",49)=""
+s ^TEMPS("11/12","1700",43)=""
+```
+### Operators
+```jinja
+; Assignment: =
+; Unary: + Convert a string value into a numeric value.
+; Arthmetic:
+; + addition
+­; - subtraction
+; * multiplication
+; / floating-point division
+; \ integer division
+; # modulo
+; ** exponentiation
+; Logical:
+; & and
+; ! or
+; ' not
+; Comparison:
+; = equal
+; '= not equal
+; > greater than
+; < less than
+; '> not greater / less than or equal to
+; '< not less / greater than or equal to
+; String operators:
+; _ concatenate
+; [ contains ­ a contains b
+; ]] sorts after ­ a comes after b
+; '[ does not contain
+; ']] does not sort after
+```
+
+#### Order of operations
+
+Operations in M are _strictly_ evaluated left to right. No operator has precedence over any other.
+You should use parentheses to group expressions.
+
+```
+w 5+3*20
+;160
+;You probably wanted 65
+w 5+(3*20)
+```
+
+### Flow Control, Blocks, & Code Structure
+
+A single M file is called a _routine_. Within a given routine, you can break your code up into smaller chunks with _tags_. The tag starts in column 1 and the commands pertaining to that tag are indented.
+
+A tag can accept parameters and return a value, this is a function. A function is called with '$$':
+
+```
+; Execute the 'tag' function, which has two parameters, and write the result.
+w !,$$tag^routine(a,b)
+```
+
+M has an execution stack. When all levels of the stack have returned, the program ends. Levels are added to the stack with _do_ commands and removed with _quit_ commands.
+
+#### D(o)
+
+With an argument: execute a block of code & add a level to the stack.
+
+```
+d ^routine ;run a routine from the begining.
+; ;routines are identified by a caret.
+d tag ;run a tag in the current routine
+d tag^routine ;run a tag in different routine
+```
+
+Argumentless do: used to create blocks of code. The block is indented with a period for each level of the block:
+
+```
+set a=1
+if a=1 do
+. write !,a
+. read b
+. if b > 10 d
+. . w !, b
+w "hello"
+```
+
+#### Q(uit)
+Stop executing this block and return to the previous stack level.
+Quit can return a value.
+
+#### N(ew)
+Clear a given variable's value _for just this stack level_. Useful for preventing side effects.
+
+Putting all this together, we can create a full example of an M routine:
+
+```
+; RECTANGLE - a routine to deal with rectangle math
+ q ; quit if a specific tag is not called
+
+main
+ n length,width ; New length and width so any previous value doesn't persist
+ w !,"Welcome to RECTANGLE. Enter the dimensions of your rectangle."
+ r !,"Length? ",length,!,"Width? ",width
+ d area(length,width) ;Do a tag
+ s per=$$perimeter(length,width) ;Get the value of a function
+ w !,"Perimeter: ",per
+ q
+
+area(length,width) ; This is a tag that accepts parameters.
+ ; It's not a function since it quits with no value.
+ w !, "Area: ",length*width
+ q ; Quit: return to the previous level of the stack.
+
+perimeter(length,width)
+ q 2*(length+width) ; Quits with a value; thus a function
+```
+
+### Conditionals, Looping and $Order()
+
+F(or) loops can follow a few different patterns:
+
+```jinja
+;Finite loop with counter
+;f var=start:increment:stop
+
+f i=0:5:25 w i," " ;0 5 10 15 20 25
+
+; Infinite loop with counter
+; The counter will keep incrementing forever. Use a conditional with Quit to get out of the loop.
+;f var=start:increment
+
+f j=1:1 w j," " i j>1E3 q ; Print 1-1000 separated by a space
+
+;Argumentless for - infinite loop. Use a conditional with Quit.
+; Also read as "forever" - f or for followed by two spaces.
+s var=""
+f s var=var_"%" w !,var i var="%%%%%%%%%%" q
+; %
+; %%
+; %%%
+; %%%%
+; %%%%%
+; %%%%%%
+; %%%%%%%
+; %%%%%%%%
+; %%%%%%%%%
+; %%%%%%%%%%
+
+```
+
+#### I(f), E(lse), Postconditionals
+
+M has an if/else construct for conditional evaluation, but any command can be conditionally executed without an extra if statement using a _postconditional_. This is a condition that occurs immediately after the command, separated with a colon (:).
+
+```jinja
+; Conditional using traditional if/else
+r "Enter a number: ",num
+i num>100 w !,"huge"
+e i num>10 w !,"big"
+e w !,"small"
+
+; Postconditionals are especially useful in a for loop.
+; This is the dominant for loop construct:
+; a 'for' statement
+; that tests for a 'quit' condition with a postconditional
+; then 'do'es an indented block for each iteration
+
+s var=""
+f s var=var_"%" q:var="%%%%%%%%%%" d ;Read as "Quit if var equals "%%%%%%%%%%"
+. w !,var
+
+;Bonus points - the $L(ength) built-in function makes this even terser
+
+s var=""
+f s var=var_"%" q:$L(var)>10 d ;
+. w !,var
+
+```
+#### Array Looping - $Order
+As we saw in the previous example, M has built-in functions called with a single $, compared to user-defined functions called with $$. These functions have shortened abbreviations, like commands.
+One of the most useful is __$Order()__ / $O(). When given an array subscript, $O returns the next subscript in that array. When it reaches the last subscript, it returns "".
+
+```jinja
+;Let's call back to our ^TEMPS global from earlier:
+; A log of temperatures by date and time
+s ^TEMPS("11/12","0600",32)=""
+s ^TEMPS("11/12","0600",48)=""
+s ^TEMPS("11/12","1400",49)=""
+s ^TEMPS("11/12","1700",43)=""
+; Some more
+s ^TEMPS("11/16","0300",27)=""
+s ^TEMPS("11/16","1130",32)=""
+s ^TEMPS("11/16","1300",47)=""
+
+;Here's a loop to print out all the dates we have temperatures for:
+n date,time ; Initialize these variables with ""
+
+; This line reads: forever; set date as the next date in ^TEMPS.
+; If date was set to "", it means we're at the end, so quit.
+; Do the block below
+f s date=$ORDER(^TEMPS(date)) q:date="" d
+. w !,date
+
+; Add in times too:
+f s date=$ORDER(^TEMPS(date)) q:date="" d
+. w !,"Date: ",date
+. f s time=$O(^TEMPS(date,time)) q:time="" d
+. . w !,"Time: ",time
+
+; Build an index that sorts first by temperature -
+; what dates and times had a given temperature?
+n date,time,temp
+f s date=$ORDER(^TEMPS(date)) q:date="" d
+. f s time=$O(^TEMPS(date,time)) q:time="" d
+. . f s temp=$O(^TEMPS(date,time,temp)) q:temp="" d
+. . . s ^TEMPINDEX(temp,date,time)=""
+
+;This will produce a global like
+^TEMPINDEX(27,"11/16","0300")
+^TEMPINDEX(32,"11/12","0600")
+^TEMPINDEX(32,"11/16","1130")
+```
+
+## Further Reading
+
+There's lots more to learn about M. A great short tutorial comes from the University of Northern Iowa and Professor Kevin O'Kane's [Introduction to the MUMPS Language][1] presentation.
+
+To install an M interpreter / database on your computer, try a [YottaDB Docker image][2].
+
+YottaDB and its precursor, GT.M, have thorough documentation on all the language features including database transactions, locking, and replication:
+
+* [YottaDB Programmer's Guide][3]
+* [GT.M Programmer's Guide][4]
+
+[1]: https://www.cs.uni.edu/~okane/source/MUMPS-MDH/MumpsTutorial.pdf
+[2]: https://yottadb.com/product/get-started/
+[3]: https://docs.yottadb.com/ProgrammersGuide/langfeat.html
+[4]: http://tinco.pair.com/bhaskar/gtm/doc/books/pg/UNIX_manual/index.html