PreviousUpNext

15.3.298  src/lib/core/internal/makelib.api

## makelib.api
## author: Matthias Blume (blume@cs.princeton.edu)

# Compiled by:
#     src/lib/core/internal/makelib-apis.lib


# This is the api for a "full" package makelib.
# This package gets constructed in
#     src/app/makelib/main/standard-compiler.sml
#  and is made available at top-level by
# (auto-)loading the library "full-cm.lib".
# (After system startup only a "minimal" package cm is visible.)



###            "Philosophy of science is about as useful
###             to scientists as ornithology is to birds."
###
###                           -- Richard P. Feynman



stipulate
    package fil =  file__premicrothread;                                        # file__premicrothread          is from   src/lib/std/src/posix/file--premicrothread.pkg
    package psx =  posixlib;                                                    # posixlib                      is from   src/lib/std/src/psx/posixlib.pkg
herein

    # This api is implemented in:
    #
    #     src/app/makelib/main/makelib-g.pkg
    #
    api Makelib {
        #
        help:           Void   -> Void;

        make:           String -> Bool;
        load:           String -> Bool;                                         # For now (at least) this is just a synonym for 'make', intended to read better at the top of scripts.
        compile:        String -> Bool;
        freeze:         String -> Bool;

        freeze'
            :
            { recursively: Bool }
            -> String
            -> Bool;

        show_all:        Void -> Void;
        show_apis:       Void -> Void;

        show_pkgs:       Void -> Void;
        show_vals:       Void -> Void;

        show_types:      Void -> Void;
        show_generics:   Void -> Void;

        show_controls:   Void -> Void;
        show_control:    String -> Void;
        set_control:     String -> String -> Void;

        show_api:        String -> Void;
        show_pkg:        String -> Void;

        Controller(X)
            =
            {   get: Void -> X,
                set: X -> Void
            };


        package control:
            api {
                keep_going_after_compile_errors: Controller(  Bool );
                verbose:                         Controller(  Bool );
                warn_on_obsolete_syntax:         Controller(  Bool );
                debug:                           Controller(  Bool );
                conserve_memory:                 Controller(  Bool );
                generate_index:                  Controller(  Bool );
                #
                parse_caching:                   Controller(  Int  );
            };

        package freezefile_db:
            api {
                Freezefile;
                known:      Void -> List( Freezefile );
                describe:   Freezefile  -> String;
                os_string:  Freezefile  -> String;
                dismiss:    Freezefile  -> Void;
                unshare:    Freezefile  -> Void;
            };

        package makelib_state:
            api {
                clear_state:    Void   -> Void;
                dump:           String -> Void;

                dump_latex:   { directory:       String,
                                filename_prefix: String,
                                filename_suffix: String
                              }
                              ->
                              Void;
            };

        sources
            :
            Null_Or {
              architecture: String,
              os:           String
            }
            ->
            String
            ->
            Null_Or (
                List {
                  file:    String,
                  ilk:   String,
                  derived: Bool
                }
            );

        get_makelib_preprocessor_symbol_value                                   # If given preprocessor symbol is defined, returns its Int value, otherwise returns NULL.
            :
            String -> Controller( Null_Or(Int) );

        load_plugin
            :
            String -> Bool;

        build_executable_heap_image
           :
           freeze_policy::Freeze_Policy
           ->
           { setup:             Null_Or( String ),
             libfile_to_run:    String,
             wrapper_libfile:   String,
             heap_filename:     String
           }
           ->
           Null_Or( List( String ) );

        package graph
            :
            api {
                graph:  String
                ->
                Null_Or {
                  graph:     portable_graph::Graph,
                  imports:   List( freezefile_db::Freezefile ),
                  nativesrc: String -> String
                };
            };

        package scripting_globals
            :
            api {
                # The following identifiers get exported into
                # the global script namespace -- see
                #     src/lib/core/internal/make-mythryld-executable.pkg
                # -- so that Mythryl scripts can use them
                # without package qualifiers.
                # 
                # This package is the only place in Mythryl
                # where we favor run-on identifiers like
                # "getlogin" over our standard "get_login"
                # style identifiers.  Reasons:
                #
                #  o Most of these identifiers are hallowed
                #    by time-out-of-mind Unix tradition.
                #
                #  o These identifiers are primarily intended
                #    to keep short informal scripts short and
                #    informal.
                #
                #  o Keeping to the traditional forms in these
                #    common cases helps C/Perl programmers get
                #    up and running faster in Mythryl.
                #
                # In short: Every language needs a few irregular
                # verbs, and these are Mythryl's.
                #
                # For the actual values bound, see
                #     src/app/makelib/main/makelib-g.pkg

                # Note:  The (_[])   enables   'vec[index]'           notation;
                #        The (_[]:=) enables   'vec[index] := value'  notation;

                (_!):         multiword_int::Int -> multiword_int::Int;
                (_[]):      (Vector(X), Int) -> X;
                (_[]:=):    (Vector(X), Int, X) -> Vector(X);

                =~ :          (String, String) -> Bool;
                atod:          String -> Float;
                atoi:          String -> Int;
                backticks__op: String -> List(String);
                basename:      String -> String;
                bin_sh:        String -> String;
                bin_sh':       String -> winix__premicrothread::process::Status;
                chdir:         String -> Void;
                chomp:         String -> String; 
                die:           String -> Void;                                                          # Technically should be  Int -> X   since it doesn't return, but  String -> Void  generates fewer spurious compiler errors.
                die_x:         String -> X;                                                             # Technically correct since it doesn't return.
                dirname:       String -> String;
                environ:       Void   -> List( String );
                eval:          String -> Void;
                evali:         String -> Int;
                evalf:         String -> Float;
                evals:         String -> String;
                evalli:        String -> List(Int);
                evallf:        String -> List(Float);
                evalls:        String -> List(String);
                exit:          Int    -> Void;                                                          # Technically should be  Int -> X   since it doesn't return, but  Int -> Void  generates fewer spurious compiler errors.
                exit_x:        Int    -> X;                                                             # Technically correct since it doesn't return.
                explode:       String -> List( Char );
                factors:       Int    -> List( Int );
                fields:       (Char -> Bool) -> String -> List( String );
                filter:       (X -> Bool) -> List(X) -> List(X);
                fscanf:        fil::Input_Stream -> String ->  Null_Or( List( scanf::Printf_Arg ) );
                getcwd:        Void   -> String;
                getenv:        String -> Null_Or( String );
                getpid:        Void -> Int;
                getuid:        Void -> Int;
                geteuid:       Void -> Int;
                getppid:       Void -> Int;
                getgid:        Void -> Int;
                getegid:       Void -> Int;
                getgroups:     Void -> List( Int );
                getlogin:      Void -> String;
                getpgrp:       Void -> Int;
#               glob:          String -> List( String );        XXX BUGGO FIXME Should add this, patterned after the Python glob. There's relevant existing infrastructure in src/lib/tk/src/toolkit/regExp/globber.pkg
                mkdir:         String -> Void;
                setgid:        Int  -> Void;
                setpgid:      (Int, Int) -> Void;
                setsid:        Void -> Int;
                setuid:        Int  -> Void;
                implode:       List( Char ) -> String;
                in:               (_X, List( _X)) -> Bool;
                iseven:        Int -> Bool;
                isodd:         Int -> Bool;
                isprime:       Int -> Bool;
                join':         String -> String -> String -> List( String ) -> String;
                join:          String -> List( String ) -> String;
                lstat:         String -> psx::stat::Stat;
                now:           Void   -> Float;
                product:       List(Int) -> Int;
                rename:     { from:  String, to:  String } -> Void;
                rmdir:         String -> Void;
                round:         Float  -> Int;
                shuffle':      random::Random_Number_Generator -> List(X) -> List(X);
                shuffle:       List(X) -> List(X);
                sleep:         Float  -> Void;
                sort:          ((X, X) -> Bool) -> List(X) -> List(X);
                sorted:        ((X, X) -> Bool) -> List(X) -> Bool;  
                scanf:         String -> Null_Or( List( scanf::Printf_Arg ) );
                sscanf:        String -> String -> Null_Or( List( scanf::Printf_Arg ) );
                stat:          String -> psx::stat::Stat;
                strcat:        List( String ) -> String;
                strlen:        String -> Int;
                strsort:       List(String) -> List(String);
                struniqsort:   List(String) -> List(String);
                sum:           List(Int) -> Int;
                symlink:       { old:  String,   new: String } -> Void;             #  POSIX 1003.1a 
                time:          Void   -> one_word_int::Int;                     # NB: 'now' has much more precision.
                tolower:       String -> String;
                toupper:       String -> String;
                tokens:        (Char -> Bool) -> String -> List( String );
                trim:          String -> String;                        # Drop leading and trailing whitespace.
                uniquesort:    ((X, X) -> Order) -> List(X) -> List(X);
                unlink:        String -> Void;
                words:         String -> List( String );
                dotqquotes__op: String -> List( String );

                arg0:          Void -> String;
                argv:          Void -> List( String );

                isfile:        String -> Bool;
                isdir:         String -> Bool;
                ispipe:        String -> Bool;
                issymlink:     String -> Bool;
                issocket:      String -> Bool;
                ischardev:     String -> Bool;
                isblockdev:    String -> Bool;
                #
                mayread:       String -> Bool;
                maywrite:      String -> Bool;
                mayexecute:    String -> Bool;


                # These are used in
                #     src/lib/src/eval-unit-test.pkg
                # There must be a cleaner way! :)   XXX BUGGO FIXME
                # 
                eval_kludge_ref_int:         Ref( Int   );
                eval_kludge_ref_float:       Ref( Float );
                eval_kludge_ref_string:      Ref( String );
                #
                eval_kludge_ref_list_int:    Ref( List( Int    ) );
                eval_kludge_ref_list_float:  Ref( List( Float  ) );
                eval_kludge_ref_list_string: Ref( List( String ) );

                include Threadkit;
            };

        redump_heap
            :
            String -> Void;

    };
end;

## Copyright (c) 1999 by Lucent Bell Laboratories
## Subsequent changes by Jeff Prothero Copyright (c) 2010-2013,
## released per terms of SMLNJ-COPYRIGHT.


Comments and suggestions to: bugs@mythryl.org

PreviousUpNext