VM program, files, commands, and functions

[gs99]

"Recall that a VM program is a collection of one or more .vm files, each containing one or more VM functions, each being a sequence of VM commands."
"The order of the functions within the .vm files does not matter."---Page 141.

I'm confused. Doesn't the VM program (that I write) read .vm files?
How can my program be a collection of these files?

I understood the .vm files contain VM commands as shown in 7.2.2 and 7.2.3.
E.g. SimpleAdd.vm:
push constant 7
push constant 8
add

Please provide some examples of functions in a .vm file, and explain why the order does not matter.

Edit: A similar statement is made on page 129: "A VM program is a collection of one or more files with a .vm extension, each consisting of one or more functions."  

[ybakos]

CONTENTS DELETED

The author has deleted this message.

[gs99]

When explaining something to another person, shouldn’t you use clear terms? Shouldn’t you want to recognize what the other person already knows?  

“One of the very useful aspects of Python is the concept of collection (or container) types. In general a collection is an object that contains other objects in a way that is easily referenced or indexed.”
http://en.wikipedia.org/wiki/Python_syntax#Collection_types

Notice that “container” is used to define collection. Some of these collection containers: lists, tuples, and strings.

With this well-known picture of "collections", my VM program does not contain .vm files. The .vm files are separate ‘animals in a separate barn’; they reside in completely different paths.  

Yes, I agree, a procedural/OO program is a collection of functions, starting with “main”. And there may be multiple program files, with their unique file extension (e.g.,.py).

But the book says a "VM program is a collection of one or more .vm files, each containing one or more VM functions, each being a sequence of VM commands."

ybakos wrote

Take a look at some of the .vm files in the project toolkit. Search for the word "function".

If I understand you correctly (.vm files in the project toolkit), here is the first one, simpleAdd.vm:
// This file is part of www.nand2tetris.org
// and the book "The Elements of Computing Systems"
// by Nisan and Schocken, MIT Press.
// File name: projects/07/StackArithmetic/SimpleAdd/SimpleAdd.vm
// Pushes and adds two constants.
push constant 7
push constant 8
add

Where is the word “function”?

Here is the second, StackTest.vm:
// This file is part of www.nand2tetris.org
// and the book "The Elements of Computing Systems"
// by Nisan and Schocken, MIT Press.
// File name: projects/07/StackArithmetic/StackTest/StackTest.vm
// Executes a sequence of arithmetic and logical operations
// on the stack.
push constant 17
push constant 17
eq
push constant 892
push constant 891
lt
push constant 32767
push constant 32766
gt
push constant 56
push constant 31
push constant 53
add
push constant 112
sub
neg
and
push constant 82
or

Where is the function?

If I can’t see the function, how can I understand the other statement on page 141
"The order of the functions within the .vm files does not matter."?

Where in the book does it explain these functions that are in the .vm files?
The word is used in Figure 7.6 The memory segments seen by every VM function.
And Figure 7.7 includes this: “VM files (f = VM function)”
But no examples are provided.
Again, when explaining new concepts, shouldn’t you provide examples?

Is the VM “function” different than a Python “function”?

How is a VM “command” related to a VM “function”? They cannot be the same; doesn't the order of VM commands matter? Would this sequence be valid for SimpleAdd.vm?:
push constant 7
add
push constant 8

The statement "Recall that a VM program is a collection of one or more .vm files, each containing one or more VM functions, each being a sequence of VM commands." is still a mystery. I cannot recall something that didn't happen.
 
 

[gs99]

@ybakos

Why did you delete your message?

We learn by this exchange of ideas.

[ybakos]

I'll try to answer your questions soon.

[gs99]

I appreciate your help. In the meantime, I came up with these comments that may help your answer.

Several examples are provided for Elementary Stack Operation push and pop starting on page 124.
Very good; understand that.

On page 130, the simple push and pop are complicated by the usage of memory segments, listed in Figure 7.6. But no examples are provided for this more complicated concept!

You may object, saying “An example is provided on page 132!”

“For example,
push argument 2
pop local 1
will store the value of the function’s third argument in the function’s second local variable.”

What function? And what does this example really explain to a person with no experience? How does it help me understand memory segments and why they’re good for us?

That’s the only explanation I could find.
The authors recommend research. Is there some other source material that I missed?

[cadet1620]

gs99 wrote

I'm confused. Doesn't the VM program (that I write) read .vm files?
How can my program be a collection of these files?

I understood the .vm files contain VM commands as shown in 7.2.2 and 7.2.3.
E.g. SimpleAdd.vm:
push constant 7
push constant 8
add

Please provide some examples of functions in a .vm file, and explain why the order does not matter.

First, "VM" is being overused and causing your confusion. The program that you are writing is a VM language translator, usually referred to as "VM translator" in the book. Your VM translator will translate VM language contained in .vm files to Hack assembly language. Multiple .vm files will be translated and combined into a single .asm file.

The early test .vm files do not have functions in them since they are intended for testing partial VM translator implementations that don't yet handle functions. You will add function handling to your VM translator in project 8. This is Main.vm from projects/08/FunctionCalls/FibonacciElement.

// This file is part of the materials accompanying the book
// "The Elements of Computing Systems" by Nisan and Schocken,
// MIT Press. Book site: www.idc.ac.il/tecs
// File name: projects/08/FunctionCalls/FibonacciElement/Main.vm

// Computes the n'th element of the Fibonacci series, recursively.
// n is given in argument[0].  Called by the Sys.init function
// (part of the Sys.vm file), which also pushes the argument[0]
// parameter before this code starts running.

function Main.fibonacci 0
push argument 0
push constant 2
lt                     // check if n < 2
if-goto IF_TRUE
goto IF_FALSE
label IF_TRUE          // if n<2, return n
push argument 0
return
label IF_FALSE         // if n>=2, return fib(n-2)+fib(n-1)
push argument 0
push constant 2
sub
call Main.fibonacci 1  // compute fib(n-2)
push argument 0
push constant 1
sub
call Main.fibonacci 1  // compute fib(n-1)
add                    // return fib(n-1) + fib(n-2)
return

The order of functions in a .vm file doesn't matter for the same reason that the order of functions in other programming languages doesn't matter.  Note that some languages, like C/C++ require predeclarations for forward referenced functions, but the VM language does not.

projects/08/FunctionCalls/StaticsTest/*.vm is an example of functions in different .vm files being called.

Note the the Sys.vm file in most (maybe all) the test programs is a special version specific to the individual tests, not the complete version from the tools/OS directory. You'll learn how to use the functions in the OS .vm files in project 9.

--Mark

[gs99]

cadet1620 wrote

"VM" is being overused and causing your confusion.

No, that is not confusing to me.

The early test .vm files do not have functions in them since they are intended for testing partial VM translator implementations that don't yet handle functions. You will add function handling to your VM translator in project 8.

Thank you, that easily solves the mystery.
What was confusing to me: Chapter 7 prematurely teaches the concept of VM functions.
They're not needed yet. It's like an actor coming on stage before the script calls for her.

For example, Figure 7.7 on page 132 paints a picture that VM files are comprised of functions.
Foo.vm is comprised of functions f1, f2, and f3.
Bar.vm is made of functions f1 and f2.

But the VM files in project 7 are not comprised of functions. In fact they don’t have ANY functions!

So the statement on page 141 "Recall that a VM program is a collection of one or more .vm files, each containing one or more VM functions, each being a sequence of VM commands." is not correct in project 7!

A more accurate statement for this project:
“Recall that a VM program (one or more files) reads one or more .vm files, each being a sequence of VM commands.”
 
When we learned about chips, it was an orderly progress from simple to more complex combinational, then sequential logic. The book provided explanations for what we needed in that chapter (e.g. We weren’t bothered with sequential logic when learning about Mux16).

Some readers may have already learned these things in college, that's OK. Other readers are learning step by step; we need to direct our focus on objects needed in project 7.