Return to help CVS log

Up to [Research Unix] / researchv10no / cmd / sml / doc

Annotation of researchv10no/cmd/sml/doc/help, revision 1.1

1.1     ! root        1: Help:  A few hints for beginning users of SML of NJ
        !             2: 
        !             3: 1. running Standard ML
        !             4: 
        !             5:    Type "sml".  This puts you into the interactive system.  The top level
        !             6:    prompt is "- ", and the secondary prompt (printed when input is
        !             7:    incomplete) is "= ".  If you get the secondary prompt when you don't
        !             8:    expect it, typing ";<return>" will often complete your input, or type
        !             9:    your interrupt character (e.g. ^C) to cancel your input and return you
        !            10:    to top level.
        !            11: 
        !            12:    If "sml" doesn't work, ask where sml has been installed on your machine
        !            13:    and use the appropriate path name or redefine your PATH environment variable.
        !            14: 
        !            15: 2. interactive input
        !            16: 
        !            17:    Input to the top level interpreter (i.e. declarations and expressions)
        !            18:    must be terminated by a semicolon (and carriage return) before the
        !            19:    system will evaluate it.  The system then prints out a response
        !            20:    indicating the effect of the evaluation.  Expressions are treated as
        !            21:    implicit declarations of a standard variable "it".  For example,
        !            22: 
        !            23:        - 3; <return>       <- user input after prompt
        !            24:        val it  = 3 : int    <- system response
        !            25: 
        !            26:    This means that the value of the last top level expression evaluated
        !            27:    can be referred to using the variable "it".
        !            28: 
        !            29: 2. changing the prompts
        !            30: 
        !            31:    The primary and secondary prompt strings are the contents of the
        !            32:    references
        !            33: 
        !            34:      System.Control.primaryPrompt
        !            35:      System.Control.secondaryPrompt
        !            36: 
        !            37:    These can be redefined by assignment, e.g.:
        !            38: 
        !            39:      - System.Control.secondaryPrompt := "(**)";
        !            40: 
        !            41: 3. interrupting parsing or computation
        !            42: 
        !            43:    Typing your interrupt character should interrupt the compiler and
        !            44:    return you to top level, unless some function is catching the
        !            45:    Interrupt exception (a dangerous thing to do).
        !            46: 
        !            47: 4. exiting the interactive system
        !            48: 
        !            49:    Typing ^D (EOF) at top level will cause an exit to the shell (or the
        !            50:    parent process from which sml was run).
        !            51: 
        !            52: 5. loading ML source text from a file
        !            53: 
        !            54:    The operator use: string->unit interprets its argument as a Unix file
        !            55:    name relative to sml's current directory and loads the text from that
        !            56:    file as though it had been typed in.  "use" should normally be
        !            57:    executed at top level, but the loaded files can also contain calls of
        !            58:    use to recursively load other files.  It is a bad idea to call use
        !            59:    within an expression or declaration, because the effects are not
        !            60:    well-defined.
        !            61: 
        !            62: 6. saving an image of the system
        !            63: 
        !            64:    Use the function exportML: string->bool to dump an image of the
        !            65:    current sml system including the environment that you have built.  The
        !            66:    argument is the path name of the image file that is created.  The
        !            67:    result false is returned in the original system, while in the saved
        !            68:    image the value returned is true.  The call of exportML can be
        !            69:    embedded in an expression which will continue evaluation (e.g. to
        !            70:    print a message) in both the original system and in the image when it
        !            71:    is run, and its effect can depend on the result of the exportML call.
        !            72:    For example:
        !            73: 
        !            74:      if exportML("saved")
        !            75:      then print "this is the saved image\n"
        !            76:      else print "this is the original process\n"
        !            77: 
        !            78:    The saved image file is an executable binary, and can be run by typing
        !            79:    the file name as a command to the shell.  (Access to command-line
        !            80:    arguments and Unix environment variables when running the saved image
        !            81:    may be accomplished by System.argv and System.environ.)
        !            82: 
        !            83: 7. executing System commands and changing directories
        !            84: 
        !            85:    The function system : string->unit spawns a process to execute its argument
        !            86:    string as a shell command.  Thus to find out what the current directory is
        !            87:    within sml you can evaluate the expression
        !            88: 
        !            89:      system "pwd";
        !            90: 
        !            91:    which will cause the current directory to be printed out (there is no
        !            92:    way at the moment to return the current directory as a string).  To
        !            93:    change the current working directory of sml use the function
        !            94:    cd :string -> unit, whose argument should be a path name denoting a
        !            95:    directory.
        !            96: 
        !            97: 8. error messages
        !            98: 
        !            99:    The error messages produced by the compiler are not always as helpful
        !           100:    as they should be, and there are often too many of them.
        !           101: 
        !           102:    The compiler attempts to recover from syntactic and type errors so
        !           103:    that it can detect as many errors as possible during a compilation.
        !           104:    Unfortunately, it is not very graceful in recovery, and the process
        !           105:    can cause numerous spurious secondary error messages.
        !           106: 
        !           107:    When compiling files, the error messages include a line number.  For
        !           108:    simple syntactic errors this line number is often accurate or off by
        !           109:    just one line.  For other classes of errors, including type errors,
        !           110:    the line number may not be very useful, since it will often just
        !           111:    indicate the end of the declaration containing the error, and this
        !           112:    declaration can be quite large.
        !           113: 
        !           114:    There are a number of different forms of type error message, and it
        !           115:    may require some practice before you become adept at interpreting
        !           116:    them.  The most common form indicates a mismatch between the type of a
        !           117:    function (or operator) and its argument (or operand).  A
        !           118:    representation of the offending expression is usually included, but
        !           119:    this is an image of the internal abstract syntax for the expression
        !           120:    and may differ significantly from the original source code.  For
        !           121:    instance, an "if...then...else..." expression is represented
        !           122:    internally as a case expression over a boolean value: 
        !           123:    "case ... of true => ... | false => ...".
        !           124: 
        !           125: 9. useful system flags
        !           126: 
        !           127:    There are a number of useful system flags and variables, which are
        !           128:    found in the structure System.Control and its substructures.  The
        !           129:    primary and secondary prompt variable have already been mentioned;
        !           130:    here are some more:
        !           131: 
        !           132:    Printing:  System.Control.Print. ...
        !           133:    
        !           134:       printDepth : int ref 
        !           135:         controls depth to which complex values and syntax trees are printed
        !           136:        (default 5)
        !           137: 
        !           138:       stringDepth : int ref
        !           139:         controls how much of a long string will be printed (default 70)
        !           140: 
        !           141:       signatures : bool ref
        !           142:         when true, signatures, and the signatures of structures, will be
        !           143:         printed when these are defined at top level (default true)
        !           144: 
        !           145:    Garbage collection messages: 
        !           146: 
        !           147:       System.Control.Runtime.gcmessages: int ref
        !           148:         when 0, no messages are printed
        !           149:        when 1, only major collections are reported  (the default)
        !           150:        when 2, major collections and heap resizings are reported
        !           151:        when 3, minor and major collections and heap resizings are reported
        !           152: 
        !           153:    Memory use:
        !           154: 
        !           155:       System.Control.Runtime.ratio : int ref
        !           156:         determines the desired ratio between size of live data and total heap
        !           157:        size.  Default is 5, and 3 is the smallest acceptable value.  A higher
        !           158:        ratio causes more aggressive use of memory (up to the softmax bound).
        !           159: 
        !           160:       System.Control.Runtime.softmax : int ref
        !           161:         suggested ceiling on heap size, in bytes.  Heap size will not grow
        !           162:        beyond this value except to maintain the "minimum" ratio of 3.  Actually,
        !           163:        when hard limits are reached (e.g. as determined by limit datasize), the
        !           164:        system can continue to run as long as the actual ratio is greater than 2.
        !           165:        A good value for softmax is one that reflects the amount of physical
        !           166:        (not virtual) memory that is expected to be available for the sml process,
        !           167:        for instance, 5000000 (5MB) might be appropriate on an 8MB Sun 3.
        !           168: 
        !           169: 10. Timing
        !           170: 
        !           171:    The structure System.Timer, which has the signature 
        !           172: 
        !           173:       signature TIMER =
        !           174:        sig  
        !           175:          datatype time = TIME of {sec : int, usec : int}
        !           176:          type timer
        !           177:          val start_timer : unit -> timer
        !           178:          val check_timer : timer -> time
        !           179:          val makestring : time -> string
        !           180:          val add_time : time * time -> time
        !           181:        end
        !           182: 
        !           183:    provides basic facilities for timing your code.  Here is how a typical
        !           184:    timing function could be implemented:
        !           185: 
        !           186:      fun timeit (f: unit->'a) =
        !           187:         let open System.Timer
        !           188:             val start = start_timer()
        !           189:             val result = f()
        !           190:          in print(makestring(check_timer(start)));
        !           191:             print "\n";
        !           192:             result
        !           193:         end;
        !           194: 
        !           195: 11. Profiling
        !           196: 
        !           197:    See the file doc/profiling for instructions on using the built-in
        !           198:    profiling facilities.
        !           199: 
        !           200: 12. Basic ML environment
        !           201: 
        !           202:    Look at the files src/boot/perv.sig and src/boot/system.sig
        !           203:    for signatures that specify what is available in the basic environment.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.