PreviousUpNext

15.3.300  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 acf =  anormcode_form;                                              # anormcode_form                is from   src/lib/compiler/back/top/anormcode/anormcode-form.pkg
    package cs  =  compiler_state;                                              # compiler_state                is from   src/lib/compiler/toplevel/interact/compiler-state.pkg
    package ds  =  deep_syntax;                                                 # deep_syntax                   is from   src/lib/compiler/front/typer-stuff/deep-syntax/deep-syntax.pkg
    package fil =  file__premicrothread;                                        # file__premicrothread          is from   src/lib/std/src/posix/file--premicrothread.pkg
    package it  =  import_tree;                                                 # import_tree                   is from   src/lib/compiler/execution/main/import-tree.pkg
    package lt  =  linking_mapstack;                                            # linking_mapstack              is from   src/lib/compiler/execution/linking-mapstack/linking-mapstack.pkg
    package pcs =  per_compile_stuff;                                           # per_compile_stuff             is from   src/lib/compiler/front/typer-stuff/main/per-compile-stuff.pkg
    package ph  =  picklehash;                                                  # picklehash                    is from   src/lib/compiler/front/basics/map/picklehash.pkg
    package pp  =  standard_prettyprinter;                                      # standard_prettyprinter        is from   src/lib/prettyprint/big/src/standard-prettyprinter.pkg
    package psx =  posixlib;                                                    # posixlib                      is from   src/lib/std/src/psx/posixlib.pkg
    package raw =  raw_syntax;                                                  # raw_syntax                    is from   src/lib/compiler/front/parser/raw-syntax/raw-syntax.pkg
    package sci =  sourcecode_info;                                             # sourcecode_info               is from   src/lib/compiler/front/basics/source/sourcecode-info.pkg
    package seg =  code_segment;                                                # code_segment                  is from   src/lib/compiler/execution/code-segments/code-segment.pkg
    package syx =  symbolmapstack;                                              # symbolmapstack                is from   src/lib/compiler/front/typer-stuff/symbolmapstack/symbolmapstack.pkg
    package tmp =  highcode_codetemp;                                           # highcode_codetemp             is from   src/lib/compiler/back/top/highcode/highcode-codetemp.pkg
herein

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

        make:           String -> Bool; /* DEPRECATED */
        load:           String -> Bool; /* DEPRECATED */                        # For now (at least) this is just a synonym for 'make', intended to read better at the top of scripts.
        use:            String -> Bool;                                         # Another synonym for 'make'. Perl has this right: Scripters care about making the library available;
                                                                                # they don't care about compiling vs loading etc. DEPRECATING 'make' and 'load' here.
        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;

        search_lib_load_path_for_file:  String -> Null_Or(String);

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

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

        parse_string_to_raw_declarations                                                                # PUBLIC.  This facility created for   src/lib/x-kit/widget/edit/eval-mode.pkg
          : 
          {                                                                                             # 
            sourcecode_info:            sci::Sourcecode_Info,                                           # Source code to compile, also error sink.
            pp:                         pp::Prettyprinter                                               # Where to prettyprint results.
          }                                                                                             #
          ->                                                                                            #
          List( raw::Declaration );                                                                     # 


        compile_raw_declaration_to_package_closure                                                      # PUBLIC.  This facility created for   src/lib/x-kit/widget/edit/eval-mode.pkg
          :
          {                                                                                             # 
            declaration:                        raw::Declaration,                                       #
            sourcecode_info:                    sci::Sourcecode_Info,                                   # Source code to compile, also error sink.
            pp:                                 pp::Prettyprinter,                                      # Where to prettyprint results.
            compiler_state_stack:               (cs::Compiler_State, List(cs::Compiler_State)),         # Compiler symbol tables to use for this compile.
            options:                            List( cs::Compile_And_Eval_String_Option )              # Future-proofing, lets us add more parameters in future without breaking backward compatibility at the client-call level.
          }                                                                                             #
          ->
          Null_Or (
              { package_closure:                        seg::Package_Closure,
                import_trees:                           List( it::Import_Tree ),
                export_picklehash:                      Null_Or( ph::Picklehash ),
                linking_mapstack:                       lt::Picklehash_To_Heapchunk_Mapstack,
                code_and_data_segments:                 seg::Code_And_Data_Segments,
                new_symbolmapstack:                     syx::Symbolmapstack,                            # A symbol table delta containing (only) stuff from raw_declaration.
                deep_syntax_declaration:                ds::Declaration,                                # Typechecked form of  raw_declaration.
                exported_highcode_variables:            List( tmp::Codetemp ),
                inline_expression:                      Null_Or( acf::Function ),
                top_level_pkg_etc_defs_jar:             cs::Compiler_Mapstack_Set_Jar,
                get_current_compiler_mapstack_set:      Void -> cs::Compiler_Mapstack_Set,
                compiler_verbosity:                     pcs::Compiler_Verbosity,
                compiler_state_stack:                   (cs::Compiler_State, List(cs::Compiler_State))
              }
          );

        link_and_run_package_closure                                                                    # This facility created for   src/lib/x-kit/widget/edit/eval-mode.pkg
          :
          { sourcecode_info:                    sci::Sourcecode_Info,                                   # Source code to compile, also error sink.
            pp:                                 pp::Prettyprinter                                       # Where to prettyprint results.
          }
          ->
          { package_closure:                    seg::Package_Closure,
            import_trees:                       List( it::Import_Tree ),
            export_picklehash:                  Null_Or( ph::Picklehash ),
            linking_mapstack:                   lt::Picklehash_To_Heapchunk_Mapstack,
            code_and_data_segments:             seg::Code_And_Data_Segments,
            new_symbolmapstack:                 syx::Symbolmapstack,                                    # A symbol table delta containing (only) stuff from raw_declaration.
            deep_syntax_declaration:            ds::Declaration,                                        # Typechecked form of  raw_declaration.
            exported_highcode_variables:        List( tmp::Codetemp ),
            inline_expression:                  Null_Or( acf::Function ),
            top_level_pkg_etc_defs_jar:         cs::Compiler_Mapstack_Set_Jar,
            get_current_compiler_mapstack_set:  Void -> cs::Compiler_Mapstack_Set,
            compiler_verbosity:                 pcs::Compiler_Verbosity,
            compiler_state_stack:               (cs::Compiler_State, List(cs::Compiler_State))          # Compiler symbol tables to use for this compile.
          }                                                                                             #
          ->                                                                                            #
          (cs::Compiler_State, List(cs::Compiler_State));                                               # Updated compiler symbol tables.  Caller may keep or discard.


        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;
#               (_[]):      (String, Int) -> Char;
#               (_[]):      (Rw_Vector(X), Int) -> X;
                (_[]:=):    (Rw_Vector(X), Int, X) -> Void;

                =~ :          (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 api Threadkit;
            };

        redump_heap
            :
            String -> Void;

    };
end;

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


Comments and suggestions to: bugs@mythryl.org

PreviousUpNext