{ "schema": 1, "title": "Morloc Manual", "url": "https://morloc-project.github.io/docs/", "build": { "asciidoctor": "Asciidoctor 2.0.26", "node": "v24.21.0", "cheerio": "1.2.0", "turndown": "7.2.4", "pagefind": "1.5.2", "source": "138dde62058a4aff2da0af7c4ef23070b4d8e447" }, "pages": [ { "number": "1.", "title": "Intro", "id": "intro", "url": "https://morloc-project.github.io/docs/intro/", "md": "https://morloc-project.github.io/docs/intro/index.md", "chapter": "intro", "level": 1, "summary": "Morloc replaces the application with the function as the unit you build, publish, and compose.", "headings": [ { "id": "one-program", "title": "Morloc in one program", "number": "1.1." }, { "id": "what-morloc-is-not", "title": "What Morloc is not", "number": "1.2." } ] }, { "number": "2.", "title": "Why Morloc?", "id": "why", "url": "https://morloc-project.github.io/docs/why/", "md": "https://morloc-project.github.io/docs/why/index.md", "chapter": "why", "level": 1, "summary": "Every command line tool solves the same problems a second time.", "headings": [ { "id": "derived-interface", "title": "The interface is derived, not written", "number": "2.1." }, { "id": "values-cross-boundaries", "title": "Values cross boundaries, not file formats", "number": "2.2." }, { "id": "signature-vs-implementation", "title": "A signature and its implementations are separate things", "number": "2.3." }, { "id": "tests-follow-the-type", "title": "Tests and benchmarks follow the type, not the language", "number": "2.4." }, { "id": "toolboxes", "title": "Toolboxes add and subtract", "number": "2.5." }, { "id": "annotations", "title": "Caching, logging, and placement are annotations", "number": "2.6." }, { "id": "one-environment", "title": "One environment, solved once", "number": "2.7." }, { "id": "what-this-makes-possible", "title": "What this makes possible", "number": "2.8." }, { "id": "project-status", "title": "Where the project stands", "number": "2.9." }, { "id": "what-i-need", "title": "What I need", "number": "2.10." } ] }, { "number": "3.", "title": "Getting Started", "id": "getting-started", "url": "https://morloc-project.github.io/docs/getting-started/", "md": "https://morloc-project.github.io/docs/getting-started/index.md", "chapter": "getting-started", "level": 1, "summary": "", "headings": [] }, { "number": "3.1.", "title": "Installing Morloc", "id": "installing", "url": "https://morloc-project.github.io/docs/getting-started/installing.html", "md": "https://morloc-project.github.io/docs/getting-started/installing.md", "chapter": "getting-started", "level": 2, "summary": "Morloc is installed and managed by mim, the Morloc installation manager.", "headings": [ { "id": "installing-mim", "title": "Installing mim", "number": "3.1.1." }, { "id": "_what_mim_needs_from_your_host", "title": "What mim needs from your host", "number": "" }, { "id": "_choosing_a_backend", "title": "Choosing a backend", "number": "3.1.2." }, { "id": "_creating_an_environment", "title": "Creating an environment", "number": "3.1.3." }, { "id": "_working_inside_an_environment", "title": "Working inside an environment", "number": "3.1.4." } ] }, { "number": "3.2.", "title": "Your first program", "id": "first-program", "url": "https://morloc-project.github.io/docs/getting-started/first-program.html", "md": "https://morloc-project.github.io/docs/getting-started/first-program.md", "chapter": "getting-started", "level": 2, "summary": "The inevitable \"Hello World\" case is implemented in Morloc like so:", "headings": [] }, { "number": "3.3.", "title": "Sourcing a foreign function", "id": "sourcing", "url": "https://morloc-project.github.io/docs/getting-started/sourcing.html", "md": "https://morloc-project.github.io/docs/getting-started/sourcing.md", "chapter": "getting-started", "level": 2, "summary": "A Morloc module on its own has no implementations.", "headings": [] }, { "number": "3.4.", "title": "Writing code that is not tied to a language", "id": "abstract-modules", "url": "https://morloc-project.github.io/docs/getting-started/abstract-modules.html", "md": "https://morloc-project.github.io/docs/getting-started/abstract-modules.md", "chapter": "getting-started", "level": 2, "summary": "Sourcing C++ works, but it pins these conversions to C++.", "headings": [] }, { "number": "3.5.", "title": "Mixing languages in one program", "id": "mixing-languages", "url": "https://morloc-project.github.io/docs/getting-started/mixing-languages.html", "md": "https://morloc-project.github.io/docs/getting-started/mixing-languages.md", "chapter": "getting-started", "level": 2, "summary": "Morloc composes across languages freely, and that includes passing functions across the boundary.", "headings": [] }, { "number": "3.6.", "title": "Parallelism across languages", "id": "parallelism", "url": "https://morloc-project.github.io/docs/getting-started/parallelism.html", "md": "https://morloc-project.github.io/docs/getting-started/parallelism.md", "chapter": "getting-started", "level": 2, "summary": "Because implementations are interchangeable, so are execution strategies.", "headings": [] }, { "number": "3.7.", "title": "Where to go next", "id": "where-to-go-next", "url": "https://morloc-project.github.io/docs/getting-started/where-to-go-next.html", "md": "https://morloc-project.github.io/docs/getting-started/where-to-go-next.md", "chapter": "getting-started", "level": 2, "summary": "You now have the whole shape of Morloc: modules export terms, terms get general types, implementations come from foreign languages or from other Morloc...", "headings": [] }, { "number": "3.8.", "title": "Editor support", "id": "editor-support", "url": "https://morloc-project.github.io/docs/getting-started/editor-support.html", "md": "https://morloc-project.github.io/docs/getting-started/editor-support.md", "chapter": "getting-started", "level": 2, "summary": "Morloc is a young language and editor support reflects that.", "headings": [] }, { "number": "3.9.", "title": "Troubleshooting", "id": "troubleshooting", "url": "https://morloc-project.github.io/docs/getting-started/troubleshooting.html", "md": "https://morloc-project.github.io/docs/getting-started/troubleshooting.md", "chapter": "getting-started", "level": 2, "summary": "The problems new users actually hit, and what to do about each.", "headings": [] }, { "number": "4.", "title": "Syntax and Features", "id": "features", "url": "https://morloc-project.github.io/docs/features/", "md": "https://morloc-project.github.io/docs/features/index.md", "chapter": "features", "level": 1, "summary": "", "headings": [] }, { "number": "4.1.", "title": "Functions", "id": "functions", "url": "https://morloc-project.github.io/docs/features/functions.html", "md": "https://morloc-project.github.io/docs/features/functions.md", "chapter": "features", "level": 2, "summary": "Everything in Morloc is built out of functions, so this is where to start.", "headings": [ { "id": "_definition_and_application", "title": "Definition and application", "number": "4.1.1." }, { "id": "_composition_and_application_operators", "title": "Composition and application operators", "number": "4.1.2." }, { "id": "_partial_application", "title": "Partial application", "number": "4.1.3." }, { "id": "_operator_sections", "title": "Operator sections", "number": "4.1.4." }, { "id": "_lambdas", "title": "Lambdas", "number": "4.1.5." } ] }, { "number": "4.2.", "title": "Foreign functions", "id": "foreign-functions", "url": "https://morloc-project.github.io/docs/features/foreign-functions.html", "md": "https://morloc-project.github.io/docs/features/foreign-functions.md", "chapter": "features", "level": 2, "summary": "A Morloc module by itself declares types and compositions but contains no implementations.", "headings": [ { "id": "_the_source_statement", "title": "The source statement", "number": "4.2.1." }, { "id": "_block_form", "title": "Block form", "number": "" }, { "id": "_general_types", "title": "General types", "number": "4.2.2." }, { "id": "mapping-native-types", "title": "Native type mappings", "number": "4.2.3." }, { "id": "_sourcing_builtins_and_other_non_exports", "title": "Sourcing builtins and other non-exports", "number": "4.2.4." }, { "id": "_keyword_shaped_foreign_operators", "title": "Keyword-shaped foreign operators", "number": "4.2.5." } ] }, { "number": "4.3.", "title": "Booleans", "id": "booleans", "url": "https://morloc-project.github.io/docs/features/booleans.html", "md": "https://morloc-project.github.io/docs/features/booleans.md", "chapter": "features", "level": 2, "summary": "Booleans are written True and False and have the type Bool.", "headings": [ { "id": "_comparison_operators", "title": "Comparison operators", "number": "4.3.1." }, { "id": "_logical_operators", "title": "Logical operators", "number": "4.3.2." }, { "id": "_short_circuiting", "title": "Short-circuiting", "number": "" }, { "id": "_boolean_valued_list_functions", "title": "Boolean-valued list functions", "number": "4.3.3." }, { "id": "_guards", "title": "Guards", "number": "4.3.4." } ] }, { "number": "4.4.", "title": "Integer types", "id": "integers", "url": "https://morloc-project.github.io/docs/features/integers.html", "md": "https://morloc-project.github.io/docs/features/integers.md", "chapter": "features", "level": 2, "summary": "Morloc has one integer type for ordinary use and a family of fixed-width types for when the width matters.", "headings": [ { "id": "_writing_integer_literals", "title": "Writing integer literals", "number": "4.4.1." }, { "id": "_integer_types_at_a_glance", "title": "Integer types at a glance", "number": "4.4.2." }, { "id": "_the_default_int_type", "title": "The default Int type", "number": "4.4.3." }, { "id": "_big_integers_from_python", "title": "Big integers from Python", "number": "4.4.4." }, { "id": "_overflow_at_a_language_boundary", "title": "Overflow at a language boundary", "number": "4.4.5." }, { "id": "_compile_time_literal_bounds", "title": "Compile-time literal bounds", "number": "4.4.6." }, { "id": "_fixed_width_integer_types", "title": "Fixed-width integer types", "number": "4.4.7." }, { "id": "_converting_between_integer_types", "title": "Converting between integer types", "number": "4.4.8." }, { "id": "_negation_and_unary_minus", "title": "Negation and unary minus", "number": "4.4.9." }, { "id": "_negative_literals", "title": "Negative literals", "number": "" }, { "id": "_when_is_unary_and_when_it_is_binary", "title": "When - is unary and when it is binary", "number": "" }, { "id": "_position_restrictions", "title": "Position restrictions", "number": "" }, { "id": "_the_negatable_typeclass", "title": "The Negatable typeclass", "number": "" } ] }, { "number": "4.5.", "title": "Floating-point types", "id": "floats", "url": "https://morloc-project.github.io/docs/features/floats.html", "md": "https://morloc-project.github.io/docs/features/floats.md", "chapter": "features", "level": 2, "summary": "Morloc’s floating-point types are IEEE 754 binary formats.", "headings": [ { "id": "_literal_forms", "title": "Literal forms", "number": "4.5.1." }, { "id": "_ieee_754_and_non_finite_values", "title": "IEEE 754 and non-finite values", "number": "4.5.2." }, { "id": "_source_level_literals", "title": "Source-level literals", "number": "" }, { "id": "_arithmetic_on_non_finite_values", "title": "Arithmetic on non-finite values", "number": "" }, { "id": "_compile_time_literal_overflow", "title": "Compile-time literal overflow", "number": "4.5.3." }, { "id": "_wire_format_and_json_interop", "title": "Wire format and JSON interop", "number": "4.5.4." }, { "id": "_f32_precision_considerations", "title": "F32 precision considerations", "number": "4.5.5." }, { "id": "_converting_to_and_from_floating_point", "title": "Converting to and from floating point", "number": "4.5.6." }, { "id": "_negation_of_real_values", "title": "Negation of Real values", "number": "4.5.7." } ] }, { "number": "4.6.", "title": "Strings", "id": "strings", "url": "https://morloc-project.github.io/docs/features/strings.html", "md": "https://morloc-project.github.io/docs/features/strings.md", "chapter": "features", "level": 2, "summary": "A Morloc string is double-quoted and holds Unicode text:", "headings": [ { "id": "_interpolation", "title": "Interpolation", "number": "4.6.1." }, { "id": "_escapes", "title": "Escapes", "number": "4.6.2." }, { "id": "_triple_quoted_strings", "title": "Triple-quoted strings", "number": "4.6.3." }, { "id": "nul-bytes", "title": "NUL bytes in strings", "number": "4.6.4." } ] }, { "number": "4.7.", "title": "Tuples and Lists", "id": "tuples-and-lists", "url": "https://morloc-project.github.io/docs/features/tuples-and-lists.html", "md": "https://morloc-project.github.io/docs/features/tuples-and-lists.md", "chapter": "features", "level": 2, "summary": "Tuples and lists are the two containers you will reach for first.", "headings": [ { "id": "_tuples", "title": "Tuples", "number": "4.7.1." }, { "id": "_lists", "title": "Lists", "number": "4.7.2." } ] }, { "number": "4.8.", "title": "Records", "id": "records", "url": "https://morloc-project.github.io/docs/features/records.html", "md": "https://morloc-project.github.io/docs/features/records.md", "chapter": "features", "level": 2, "summary": "A record is a named, fixed set of named fields.", "headings": [ { "id": "_native_representations", "title": "Native representations", "number": "4.8.1." }, { "id": "_record_literals_match_by_field_name", "title": "Record literals match by field name", "number": "4.8.2." }, { "id": "_one_record_across_three_languages", "title": "One record across three languages", "number": "4.8.3." } ] }, { "number": "4.9.", "title": "Patterns", "id": "patterns", "url": "https://morloc-project.github.io/docs/features/patterns.html", "md": "https://morloc-project.github.io/docs/features/patterns.md", "chapter": "features", "level": 2, "summary": "Morloc’s pattern functions are first-class getters, setters, and bracket operators for reaching into and rearranging data structures.", "headings": [ { "id": "_getter_patterns", "title": "Getter patterns", "number": "4.9.1." }, { "id": "_setter_patterns", "title": "Setter patterns", "number": "4.9.2." }, { "id": "_bracket_patterns", "title": "Bracket patterns", "number": "4.9.3." }, { "id": "_composing_brackets_with_other_patterns", "title": "Composing brackets with other patterns", "number": "" }, { "id": "_patterns_next_to_python", "title": "Patterns next to Python", "number": "4.9.4." }, { "id": "_adding_bracket_support_to_your_own_types", "title": "Adding bracket support to your own types", "number": "4.9.5." } ] }, { "number": "4.10.", "title": "Pattern Matching", "id": "pattern-matching", "url": "https://morloc-project.github.io/docs/features/pattern-matching.html", "md": "https://morloc-project.github.io/docs/features/pattern-matching.md", "chapter": "features", "level": 2, "summary": "A pattern describes the shape of a value using the same notation you would use to build it.", "headings": [ { "id": "_irrefutable_patterns", "title": "Irrefutable patterns", "number": "4.10.1." }, { "id": "_wildcards", "title": "Wildcards", "number": "" }, { "id": "_as_patterns", "title": "As-patterns", "number": "" }, { "id": "_record_patterns_on_let_and_do_need_parentheses", "title": "Record patterns on let and do need parentheses", "number": "" }, { "id": "refutable-patterns", "title": "Refutable patterns", "number": "4.10.2." }, { "id": "match-expressions", "title": "match expressions", "number": "4.10.3." }, { "id": "_where_a_clause_list_ends", "title": "Where a clause list ends", "number": "" }, { "id": "_exhaustiveness", "title": "Exhaustiveness", "number": "4.10.4." }, { "id": "_guards_inside_a_clause", "title": "Guards inside a clause", "number": "4.10.5." }, { "id": "_not_yet_supported", "title": "Not yet supported", "number": "4.10.6." } ] }, { "number": "4.11.", "title": "where and let clauses", "id": "where-and-let", "url": "https://morloc-project.github.io/docs/features/where-and-let.html", "md": "https://morloc-project.github.io/docs/features/where-and-let.md", "chapter": "features", "level": 2, "summary": "Both introduce local bindings, and they differ in exactly one way that matters: where is order-invariant, let is sequential.", "headings": [ { "id": "_where", "title": "where", "number": "4.11.1." }, { "id": "_let", "title": "let", "number": "4.11.2." }, { "id": "_the_scope_rule_that_separates_them", "title": "The scope rule that separates them", "number": "4.11.3." } ] }, { "number": "4.12.", "title": "Conditionals", "id": "conditionals", "url": "https://morloc-project.github.io/docs/features/conditionals.html", "md": "https://morloc-project.github.io/docs/features/conditionals.md", "chapter": "features", "level": 2, "summary": "Guards are Morloc’s conditional branching.", "headings": [ { "id": "_guards_with_where", "title": "Guards with where", "number": "4.12.1." }, { "id": "_guards_in_other_positions", "title": "Guards in other positions", "number": "4.12.2." }, { "id": "_guards_inside_a_pattern_clause", "title": "Guards inside a pattern clause", "number": "4.12.3." } ] }, { "number": "4.13.", "title": "Recursion", "id": "recursion", "url": "https://morloc-project.github.io/docs/features/recursion.html", "md": "https://morloc-project.github.io/docs/features/recursion.md", "chapter": "features", "level": 2, "summary": "", "headings": [ { "id": "_recursive_functions", "title": "Recursive functions", "number": "4.13.1." }, { "id": "_recursive_types", "title": "Recursive types", "number": "4.13.2." }, { "id": "_linked_lists", "title": "Linked lists", "number": "" }, { "id": "_branching_binary_trees", "title": "Branching: binary trees", "number": "" }, { "id": "_list_guarded_recursion_rose_trees", "title": "List-guarded recursion: rose trees", "number": "" }, { "id": "_record_form", "title": "Record form", "number": "" }, { "id": "_parameterised_recursion", "title": "Parameterised recursion", "number": "" } ] }, { "number": "4.14.", "title": "Sum types", "id": "sum-types", "url": "https://morloc-project.github.io/docs/features/sum-types.html", "md": "https://morloc-project.github.io/docs/features/sum-types.md", "chapter": "features", "level": 2, "summary": "A record holds all of its fields at once.", "headings": [ { "id": "_a_constructor_set_is_closed_and_the_compiler_counts", "title": "A constructor set is closed, and the compiler counts", "number": "4.14.1." }, { "id": "_the_constructor_names_reach_the_interface", "title": "The constructor names reach the interface", "number": "4.14.2." }, { "id": "_constructors_that_take_arguments", "title": "Constructors that take arguments", "number": "4.14.3." }, { "id": "_matching_a_value_that_is_not_an_argument", "title": "Matching a value that is not an argument", "number": "4.14.4." }, { "id": "_recursive_types_2", "title": "Recursive types", "number": "4.14.5." }, { "id": "_constructor_names_are_global", "title": "Constructor names are global", "number": "4.14.6." }, { "id": "_native_representations_2", "title": "Native representations", "number": "4.14.7." }, { "id": "_comparing_values", "title": "Comparing values", "number": "4.14.8." } ] }, { "number": "4.15.", "title": "Effects and delayed evaluation", "id": "effects", "url": "https://morloc-project.github.io/docs/features/effects.html", "md": "https://morloc-project.github.io/docs/features/effects.md", "chapter": "features", "level": 2, "summary": "", "headings": [ { "id": "_why_effects_need_a_name", "title": "Why effects need a name", "number": "4.15.1." }, { "id": "_the_mental_model", "title": "The mental model", "number": "4.15.2." }, { "id": "failure-is-not-an-effect", "title": "Failure is not an effect", "number": "4.15.3." }, { "id": "_syntax", "title": "Syntax", "number": "4.15.4." }, { "id": "_declaring_an_effect", "title": "Declaring an effect", "number": "" }, { "id": "_annotating_signatures", "title": "Annotating signatures", "number": "" }, { "id": "_do_blocks", "title": "do-blocks", "number": "" }, { "id": "bare-statement-checks", "title": "A bare statement checks its result", "number": "" }, { "id": "_refutable_binds", "title": "Refutable binds", "number": "" }, { "id": "do-block-no-try", "title": "A do-block does not return a Try", "number": "" }, { "id": "_when_do_is_needed_and_when_it_isnt", "title": "When do is needed and when it isn’t", "number": "" }, { "id": "_the_eval_prefix", "title": "The ! eval prefix", "number": "" }, { "id": "_the_reading_a_suspension_is_a_value", "title": "The reading: a suspension is a value", "number": "4.15.5." }, { "id": "rules", "title": "The rules", "number": "4.15.6." }, { "id": "_effect_row_variables", "title": "Effect row variables", "number": "4.15.7." }, { "id": "escapable", "title": "Escapable and inescapable effects", "number": "4.15.8." } ] }, { "number": "4.16.", "title": "Optional types", "id": "optionals", "url": "https://morloc-project.github.io/docs/features/optionals.html", "md": "https://morloc-project.github.io/docs/features/optionals.md", "chapter": "features", "level": 2, "summary": "Every language needs a way to say \"no value here\".", "headings": [ { "id": "_syntax_2", "title": "Syntax", "number": "4.16.1." }, { "id": "_working_with_optional_values", "title": "Working with optional values", "number": "4.16.2." }, { "id": "_optional_record_fields", "title": "Optional record fields", "number": "4.16.3." }, { "id": "_optionals_across_languages", "title": "Optionals across languages", "number": "4.16.4." }, { "id": "_implicit_coercion", "title": "Implicit coercion", "number": "4.16.5." }, { "id": "_nested_optionals_are_idempotent", "title": "Nested optionals are idempotent", "number": "4.16.6." } ] }, { "number": "4.17.", "title": "Intrinsics", "id": "intrinsics", "url": "https://morloc-project.github.io/docs/features/intrinsics.html", "md": "https://morloc-project.github.io/docs/features/intrinsics.md", "chapter": "features", "level": 2, "summary": "Intrinsics are compiler-generated special functions.", "headings": [ { "id": "_reference_table", "title": "Reference table", "number": "4.17.1." }, { "id": "_hashing", "title": "Hashing", "number": "4.17.2." }, { "id": "_compile_time_constants", "title": "Compile-time constants", "number": "4.17.3." }, { "id": "_saving_and_loading_data", "title": "Saving and loading data", "number": "4.17.4." }, { "id": "_caching_with_savem_and_load", "title": "Caching with @savem and @load", "number": "4.17.5." }, { "id": "_accessing_installed_data_files", "title": "Accessing installed data files", "number": "4.17.6." }, { "id": "_type_introspection", "title": "Type introspection", "number": "4.17.7." }, { "id": "failure-and-recovery", "title": "Failure and recovery", "number": "4.17.8." }, { "id": "_throw_abandon_the_computation", "title": "@throw: abandon the computation", "number": "" }, { "id": "_try_turn_a_raise_back_into_a_value", "title": "@try: turn a raise back into a value", "number": "" }, { "id": "_chaining_attempts", "title": "Chaining attempts", "number": "" }, { "id": "_caveats", "title": "Caveats", "number": "" } ] }, { "number": "5.", "title": "Advanced Types", "id": "types", "url": "https://morloc-project.github.io/docs/types/", "md": "https://morloc-project.github.io/docs/types/index.md", "chapter": "types", "level": 1, "summary": "", "headings": [] }, { "number": "5.1.", "title": "One term may have many definitions", "id": "term-polymorphism", "url": "https://morloc-project.github.io/docs/types/term-polymorphism.html", "md": "https://morloc-project.github.io/docs/types/term-polymorphism.md", "chapter": "types", "level": 2, "summary": "A Morloc term may have more than one definition, and the compiler picks whichever one produces the best program.", "headings": [ { "id": "_how_the_choice_collapses_a_program", "title": "How the choice collapses a program", "number": "5.1.1." }, { "id": "_contradictory_definitions", "title": "Contradictory definitions", "number": "5.1.2." }, { "id": "_a_test_suite_that_runs_against_every_implementation", "title": "A test suite that runs against every implementation", "number": "5.1.3." } ] }, { "number": "5.2.", "title": "Overload terms with typeclasses", "id": "typeclasses", "url": "https://morloc-project.github.io/docs/types/typeclasses.html", "md": "https://morloc-project.github.io/docs/types/typeclasses.md", "chapter": "types", "level": 2, "summary": "A typeclass lets one name have a different implementation for each type it is applied to.", "headings": [ { "id": "_one_class_many_languages", "title": "One class, many languages", "number": "5.2.1." }, { "id": "_superclasses", "title": "Superclasses", "number": "5.2.2." }, { "id": "_importing_a_class_from_another_module", "title": "Importing a class from another module", "number": "5.2.3." } ] }, { "number": "5.3.", "title": "Infix operators", "id": "infix-operators", "url": "https://morloc-project.github.io/docs/types/infix-operators.html", "md": "https://morloc-project.github.io/docs/types/infix-operators.md", "chapter": "types", "level": 2, "summary": "An operator in Morloc is an ordinary function whose name happens to be punctuation.", "headings": [ { "id": "_declaring_associativity_and_precedence", "title": "Declaring associativity and precedence", "number": "5.3.1." }, { "id": "_operators_from_foreign_languages_and_typeclasses", "title": "Operators from foreign languages and typeclasses", "number": "5.3.2." }, { "id": "_importing_operators", "title": "Importing operators", "number": "5.3.3." }, { "id": "_names_that_cannot_start_with", "title": "Names that cannot start with --", "number": "5.3.4." } ] }, { "number": "5.4.", "title": "Naming a type: type and newtype", "id": "newtype", "url": "https://morloc-project.github.io/docs/types/newtype.html", "md": "https://morloc-project.github.io/docs/types/newtype.md", "chapter": "types", "level": 2, "summary": "Morloc gives you two keywords for putting a name on a type, and the choice between them decides whether the new name is the same type as the old one or a...", "headings": [ { "id": "_type_transparent_aliases", "title": "type: transparent aliases", "number": "5.4.1." }, { "id": "_alias_chains_resolve_on_their_own", "title": "Alias chains resolve on their own", "number": "5.4.2." }, { "id": "_docstring_inheritance", "title": "Docstring inheritance", "number": "5.4.3." }, { "id": "_what_an_alias_cannot_do", "title": "What an alias cannot do", "number": "5.4.4." }, { "id": "_newtype_nominal_types", "title": "newtype: nominal types", "number": "5.4.5." }, { "id": "_when_a_newtype_needs_a_packable_instance", "title": "When a newtype needs a Packable instance", "number": "5.4.6." }, { "id": "_sharing_a_wire_format_across_newtypes", "title": "Sharing a wire format across newtypes", "number": "5.4.7." }, { "id": "_declarations_with_no_body", "title": "Declarations with no body", "number": "5.4.8." }, { "id": "_the_rules", "title": "The rules", "number": "5.4.9." } ] }, { "number": "5.5.", "title": "Serializing custom types with Packable", "id": "packable", "url": "https://morloc-project.github.io/docs/types/packable.html", "md": "https://morloc-project.github.io/docs/types/packable.md", "chapter": "types", "level": 2, "summary": "Morloc can move a value between languages when it knows how to write that value down.", "headings": [ { "id": "_a_worked_example_map", "title": "A worked example: Map", "number": "5.5.1." }, { "id": "_specialized_instances", "title": "Specialized instances", "number": "5.5.2." }, { "id": "_pack_in_your_own_code", "title": "pack in your own code", "number": "5.5.3." } ] }, { "number": "5.6.", "title": "The kind system", "id": "kinds", "url": "https://morloc-project.github.io/docs/types/kinds.html", "md": "https://morloc-project.github.io/docs/types/kinds.md", "chapter": "types", "level": 2, "summary": "A kind says what sort of thing a type variable stands for.", "headings": [ { "id": "_nat_numbers_in_the_type", "title": "Nat: numbers in the type", "number": "5.6.1." }, { "id": "_str_labels_in_the_type", "title": "Str: labels in the type", "number": "5.6.2." }, { "id": "_rec_schemas_in_the_type", "title": "Rec: schemas in the type", "number": "5.6.3." }, { "id": "_list_and_set_collections_of_labels", "title": "List and Set: collections of labels", "number": "5.6.4." }, { "id": "_gradual_arguments", "title": "Gradual arguments", "number": "5.6.5." }, { "id": "_reference_type_level_functions", "title": "Reference: type-level functions", "number": "5.6.6." }, { "id": "_reference_constraints", "title": "Reference: constraints", "number": "5.6.7." }, { "id": "_what_does_not_work_yet", "title": "What does not work yet", "number": "5.6.8." } ] }, { "number": "5.7.", "title": "Tensors", "id": "tensors", "url": "https://morloc-project.github.io/docs/types/tensors.html", "md": "https://morloc-project.github.io/docs/types/tensors.md", "chapter": "types", "level": 2, "summary": "The standard library’s tensor types carry their dimensions in the type, so the compiler can catch a shape mismatch — a 3x4 matrix where a 4x3 was wanted —...", "headings": [ { "id": "_shapes_that_have_to_agree", "title": "Shapes that have to agree", "number": "5.7.1." }, { "id": "_dimensions_computed_from_other_dimensions", "title": "Dimensions computed from other dimensions", "number": "5.7.2." }, { "id": "_dimensions_that_come_from_arguments", "title": "Dimensions that come from arguments", "number": "5.7.3." }, { "id": "_building_a_tensor_by_hand", "title": "Building a tensor by hand", "number": "5.7.4." }, { "id": "_omitting_dimensions", "title": "Omitting dimensions", "number": "5.7.5." }, { "id": "_what_is_checked_and_what_is_not", "title": "What is checked, and what is not", "number": "5.7.6." } ] }, { "number": "5.8.", "title": "Tables", "id": "tables", "url": "https://morloc-project.github.io/docs/types/tables.html", "md": "https://morloc-project.github.io/docs/types/tables.md", "chapter": "types", "level": 2, "summary": "A Table is columnar data whose row count and column schema are part of its type:", "headings": [ { "id": "_building_a_table", "title": "Building a table", "number": "5.8.1." }, { "id": "_introspection", "title": "Introspection", "number": "5.8.2." }, { "id": "_column_operations", "title": "Column operations", "number": "5.8.3." }, { "id": "_row_operations", "title": "Row operations", "number": "5.8.4." }, { "id": "_stacking_tables", "title": "Stacking tables", "number": "5.8.5." }, { "id": "_crossing_a_language_boundary", "title": "Crossing a language boundary", "number": "5.8.6." }, { "id": "_reading_and_writing_table_files", "title": "Reading and writing table files", "number": "5.8.7." }, { "id": "_limits", "title": "Limits", "number": "5.8.8." } ] }, { "number": "6.", "title": "Building CLIs", "id": "clis", "url": "https://morloc-project.github.io/docs/clis/", "md": "https://morloc-project.github.io/docs/clis/index.md", "chapter": "clis", "level": 1, "summary": "A Morloc module compiles to a command line tool.", "headings": [] }, { "number": "6.1.", "title": "The example program", "id": "example-program", "url": "https://morloc-project.github.io/docs/clis/example-program.html", "md": "https://morloc-project.github.io/docs/clis/example-program.md", "chapter": "clis", "level": 2, "summary": "The chapter uses one tool throughout: sift, which searches a directory tree for lines matching a pattern and reports what it finds.", "headings": [] }, { "number": "6.2.", "title": "The two argument zones", "id": "argument-zones", "url": "https://morloc-project.github.io/docs/clis/argument-zones.html", "md": "https://morloc-project.github.io/docs/clis/argument-zones.md", "chapter": "clis", "level": 2, "summary": "Every Morloc program’s argv is split into two zones.", "headings": [ { "id": "_programs_with_a_single_export", "title": "Programs with a single export", "number": "6.2.1." } ] }, { "number": "6.3.", "title": "Docstrings", "id": "docstrings", "url": "https://morloc-project.github.io/docs/clis/docstrings.html", "md": "https://morloc-project.github.io/docs/clis/docstrings.md", "chapter": "clis", "level": 2, "summary": "A docstring is a comment that the compiler keeps.", "headings": [ { "id": "_directives", "title": "Directives", "number": "6.3.1." } ] }, { "number": "6.4.", "title": "Arguments", "id": "arguments", "url": "https://morloc-project.github.io/docs/clis/arguments.html", "md": "https://morloc-project.github.io/docs/clis/arguments.md", "chapter": "clis", "level": 2, "summary": "By default every argument in a signature is a positional, in the order it appears.", "headings": [ { "id": "_when_an_argument_is_wrong", "title": "When an argument is wrong", "number": "6.4.1." }, { "id": "_options_flags_and_repeats", "title": "Options, flags, and repeats", "number": "6.4.2." }, { "id": "_naming", "title": "Naming", "number": "6.4.3." }, { "id": "_ending_option_parsing", "title": "Ending option parsing", "number": "6.4.4." } ] }, { "number": "6.5.", "title": "Record arguments", "id": "record-arguments", "url": "https://morloc-project.github.io/docs/clis/record-arguments.html", "md": "https://morloc-project.github.io/docs/clis/record-arguments.md", "chapter": "clis", "level": 2, "summary": "A record argument is a natural fit for a group of related settings, but a caller does not want to write a JSON object to set one field.", "headings": [ { "id": "_three_ways_to_fill_it", "title": "Three ways to fill it", "number": "6.5.1." }, { "id": "_what_is_rejected", "title": "What is rejected", "number": "6.5.2." } ] }, { "number": "6.6.", "title": "Sum type arguments", "id": "sum-type-arguments", "url": "https://morloc-project.github.io/docs/clis/sum-type-arguments.html", "md": "https://morloc-project.github.io/docs/clis/sum-type-arguments.md", "chapter": "clis", "level": 2, "summary": "A record says \"all of these\"; a data type says \"one of these\".", "headings": [] }, { "number": "6.7.", "title": "Input shape", "id": "input-shape", "url": "https://morloc-project.github.io/docs/clis/input-shape.html", "md": "https://morloc-project.github.io/docs/clis/input-shape.md", "chapter": "clis", "level": 2, "summary": "The defaults from Arguments cover most arguments: a scalar is read from argv, a compound value is inline JSON or a file.", "headings": [ { "id": "_a_worked_example", "title": "A worked example", "number": "6.7.1." }, { "id": "_shape_follows_the_wire_form", "title": "Shape follows the wire form", "number": "6.7.2." } ] }, { "number": "6.8.", "title": "Reading a stream from standard input", "id": "reading-stdin", "url": "https://morloc-project.github.io/docs/clis/reading-stdin.html", "md": "https://morloc-project.github.io/docs/clis/reading-stdin.md", "chapter": "clis", "level": 2, "summary": "A tool that reads standard input when you do not give it a file is the shape that makes pipelines work.", "headings": [ { "id": "_what_standard_input_may_carry", "title": "What standard input may carry", "number": "6.8.1." }, { "id": "_rules_for_stdin", "title": "Rules for @stdin", "number": "6.8.2." } ] }, { "number": "6.9.", "title": "Output formats", "id": "output-formats", "url": "https://morloc-project.github.io/docs/clis/output-formats.html", "md": "https://morloc-project.github.io/docs/clis/output-formats.md", "chapter": "clis", "level": 2, "summary": "A command’s return value is serialized and written to standard output.", "headings": [ { "id": "_nothing_to_report", "title": "Nothing to report", "number": "6.9.1." }, { "id": "_failure", "title": "Failure", "number": "6.9.2." } ] }, { "number": "6.10.", "title": "Output actions", "id": "output-actions", "url": "https://morloc-project.github.io/docs/clis/output-actions.html", "md": "https://morloc-project.github.io/docs/clis/output-actions.md", "chapter": "clis", "level": 2, "summary": "One typed function usually wants more than one presentation.", "headings": [ { "id": "_with_keeps_a_value_render_produces_bytes", "title": "@with keeps a value; @render produces bytes", "number": "6.10.1." }, { "id": "_giving_a_formatter_arguments", "title": "Giving a formatter arguments", "number": "6.10.2." }, { "id": "_choosing_a_default", "title": "Choosing a default", "number": "6.10.3." }, { "id": "_media_types", "title": "Media types", "number": "6.10.4." }, { "id": "action-rules", "title": "Rules and rejections", "number": "6.10.5." } ] }, { "number": "6.11.", "title": "Streaming output with @collect", "id": "streaming-output", "url": "https://morloc-project.github.io/docs/clis/streaming-output.html", "md": "https://morloc-project.github.io/docs/clis/streaming-output.md", "chapter": "clis", "level": 2, "summary": "Everything so far has treated a command’s output as one value: compute it, serialize it, write it.", "headings": [ { "id": "_actions_on_a_stream", "title": "Actions on a stream", "number": "6.11.1." }, { "id": "_offset_where_a_batch_sits_in_the_stream", "title": "@offset: where a batch sits in the stream", "number": "6.11.2." }, { "id": "_ifile_the_gathered_stream_as_a_file", "title": "IFile: the gathered stream as a file", "number": "6.11.3." }, { "id": "_streaming_rules", "title": "Streaming rules", "number": "6.11.4." }, { "id": "_what_the_help_says_a_stream_produces", "title": "What the help says a stream produces", "number": "6.11.5." } ] }, { "number": "6.12.", "title": "Composing tools", "id": "composing-tools", "url": "https://morloc-project.github.io/docs/clis/composing-tools.html", "md": "https://morloc-project.github.io/docs/clis/composing-tools.md", "chapter": "clis", "level": 2, "summary": "A module that compiles to a CLI is still a module.", "headings": [ { "id": "_grouping_commands", "title": "Grouping commands", "number": "6.12.1." }, { "id": "_installing", "title": "Installing", "number": "6.12.2." } ] }, { "number": "6.13.", "title": "The interface as data", "id": "interface-as-data", "url": "https://morloc-project.github.io/docs/clis/interface-as-data.html", "md": "https://morloc-project.github.io/docs/clis/interface-as-data.md", "chapter": "clis", "level": 2, "summary": "-h is written for a person.", "headings": [ { "id": "_other_views_of_the_same_commands", "title": "Other views of the same commands", "number": "6.13.1." } ] }, { "number": "6.14.", "title": "Directive reference", "id": "directive-reference", "url": "https://morloc-project.github.io/docs/clis/directive-reference.html", "md": "https://morloc-project.github.io/docs/clis/directive-reference.md", "chapter": "clis", "level": 2, "summary": "Every docstring directive that affects the generated interface, grouped by where it may be written.", "headings": [] }, { "number": "7.", "title": "Building APIs", "id": "apis", "url": "https://morloc-project.github.io/docs/apis/", "md": "https://morloc-project.github.io/docs/apis/index.md", "chapter": "apis", "level": 1, "summary": "", "headings": [] }, { "number": "7.1.", "title": "Search and install", "id": "search-and-install", "url": "https://morloc-project.github.io/docs/apis/search-and-install.html", "md": "https://morloc-project.github.io/docs/apis/search-and-install.md", "chapter": "apis", "level": 2, "summary": "The docstrings are used for discoverability as well.", "headings": [] }, { "number": "7.2.", "title": "Exposing native resources", "id": "exposing-native-resources", "url": "https://morloc-project.github.io/docs/apis/exposing-native-resources.html", "md": "https://morloc-project.github.io/docs/apis/exposing-native-resources.md", "chapter": "apis", "level": 2, "summary": "The dependencies field links against shared libraries.", "headings": [] }, { "number": "7.3.", "title": "Controlling data transfer", "id": "data-transfer", "url": "https://morloc-project.github.io/docs/apis/data-transfer.html", "md": "https://morloc-project.github.io/docs/apis/data-transfer.md", "chapter": "apis", "level": 2, "summary": "When a Morloc value crosses a pool boundary, the runtime picks one of three routes for data transfer:", "headings": [ { "id": "_combinations", "title": "Combinations", "number": "7.3.1." }, { "id": "_examples", "title": "Examples", "number": "7.3.2." } ] }, { "number": "7.4.", "title": "Building API interfaces", "id": "api-interfaces", "url": "https://morloc-project.github.io/docs/apis/api-interfaces.html", "md": "https://morloc-project.github.io/docs/apis/api-interfaces.md", "chapter": "apis", "level": 2, "summary": "In addition to being CLI tools, compiled Morloc programs can run as long-lived daemons, accepting function calls over HTTP, TCP, or Unix sockets.", "headings": [ { "id": "_http_protocol", "title": "HTTP protocol", "number": "7.4.1." }, { "id": "_tcp_protocol", "title": "TCP protocol", "number": "7.4.2." }, { "id": "_unix_socket_protocol", "title": "Unix socket protocol", "number": "7.4.3." }, { "id": "_running_all_protocols_at_once", "title": "Running all protocols at once", "number": "7.4.4." }, { "id": "_ephemeral_ports", "title": "Ephemeral ports", "number": "" }, { "id": "_from_single_daemons_to_a_router", "title": "From single daemons to a router", "number": "7.4.5." }, { "id": "_router_mode", "title": "Router mode", "number": "7.4.6." }, { "id": "_setup", "title": "Setup", "number": "" }, { "id": "_starting_the_router", "title": "Starting the router", "number": "" }, { "id": "_discovery", "title": "Discovery", "number": "" }, { "id": "_calling_functions", "title": "Calling functions", "number": "" }, { "id": "_error_handling", "title": "Error handling", "number": "" }, { "id": "_independent_daemons_vs_router_managed_daemons", "title": "Independent daemons vs router-managed daemons", "number": "" }, { "id": "_shutdown", "title": "Shutdown", "number": "7.4.7." }, { "id": "_summary", "title": "Summary", "number": "7.4.8." } ] }, { "number": "7.5.", "title": "Model Context Protocol (MCP)", "id": "mcp", "url": "https://morloc-project.github.io/docs/apis/mcp.html", "md": "https://morloc-project.github.io/docs/apis/mcp.md", "chapter": "apis", "level": 2, "summary": "The same compiled program that runs as a CLI tool or a daemon can also serve as an MCP server, exposing its exported functions as tools that an AI agent...", "headings": [ { "id": "_the_handshake", "title": "The handshake", "number": "7.5.1." }, { "id": "_inspecting_the_tool_surface", "title": "Inspecting the tool surface", "number": "7.5.2." }, { "id": "_how_arguments_map_to_properties", "title": "How arguments map to properties", "number": "7.5.3." }, { "id": "_calling_a_tool", "title": "Calling a tool", "number": "7.5.4." }, { "id": "_what_is_not_exposed", "title": "What is not exposed", "number": "7.5.5." }, { "id": "_errors", "title": "Errors", "number": "7.5.6." }, { "id": "_connecting_an_mcp_client", "title": "Connecting an MCP client", "number": "7.5.7." }, { "id": "_inside_versus_outside_the_container", "title": "Inside versus outside the container", "number": "7.5.8." }, { "id": "_summary_2", "title": "Summary", "number": "7.5.9." } ] }, { "number": "8.", "title": "Managing Runs", "id": "runs", "url": "https://morloc-project.github.io/docs/runs/", "md": "https://morloc-project.github.io/docs/runs/index.md", "chapter": "runs", "level": 1, "summary": "A morloc program is an executable that can dispatch work across multiple language pools and, optionally, remote compute nodes.", "headings": [] }, { "number": "8.1.", "title": "Logging", "id": "logging", "url": "https://morloc-project.github.io/docs/runs/logging.html", "md": "https://morloc-project.github.io/docs/runs/logging.md", "chapter": "runs", "level": 2, "summary": "Morloc programs can emit per-call log lines around any labeled term in source.", "headings": [ { "id": "_enabling_logging", "title": "Enabling logging", "number": "8.1.1." }, { "id": "_template_placeholders", "title": "Template placeholders", "number": "8.1.2." }, { "id": "_color_codes", "title": "Color codes", "number": "8.1.3." }, { "id": "_terminal_detection_and_no_color", "title": "Terminal detection and NO_COLOR", "number": "8.1.4." }, { "id": "_worked_example", "title": "Worked example", "number": "8.1.5." } ] }, { "number": "8.2.", "title": "Benchmarking", "id": "benchmarking", "url": "https://morloc-project.github.io/docs/runs/benchmarking.html", "md": "https://morloc-project.github.io/docs/runs/benchmarking.md", "chapter": "runs", "level": 2, "summary": "log: true reports every call as it happens.", "headings": [ { "id": "_the_summary_row", "title": "The summary row", "number": "8.2.1." }, { "id": "_comparing_implementations", "title": "Comparing implementations", "number": "8.2.2." } ] }, { "number": "8.3.", "title": "Run directory", "id": "run-directory", "url": "https://morloc-project.github.io/docs/runs/run-directory.html", "md": "https://morloc-project.github.io/docs/runs/run-directory.md", "chapter": "runs", "level": 2, "summary": "Every persistent-logging invocation of a morloc-built executable is one run.", "headings": [ { "id": "rundir-activation", "title": "Activation knobs", "number": "8.3.1." }, { "id": "_summary_json", "title": "summary.json", "number": "8.3.2." }, { "id": "rundir-location", "title": "Where the directory lives", "number": "8.3.3." }, { "id": "_cleanup", "title": "Cleanup", "number": "8.3.4." }, { "id": "_prologue_and_epilogue", "title": "Prologue and epilogue", "number": "8.3.5." }, { "id": "_nested_invocations", "title": "Nested invocations", "number": "8.3.6." } ] }, { "number": "8.4.", "title": "Caching", "id": "caching", "url": "https://morloc-project.github.io/docs/runs/caching.html", "md": "https://morloc-project.github.io/docs/runs/caching.md", "chapter": "runs", "level": 2, "summary": "Mark any labeled call site cache: true in the program YAML and its result is memoized to disk.", "headings": [ { "id": "_declaring_a_cached_call", "title": "Declaring a cached call", "number": "8.4.1." }, { "id": "_what_goes_in_the_hash", "title": "What goes in the hash", "number": "8.4.2." }, { "id": "cache-layout", "title": "Storage layout", "number": "8.4.3." }, { "id": "_reading_and_writing", "title": "Reading and writing", "number": "8.4.4." } ] }, { "number": "8.5.", "title": "Compression", "id": "compression", "url": "https://morloc-project.github.io/docs/runs/compression.html", "md": "https://morloc-project.github.io/docs/runs/compression.md", "chapter": "runs", "level": 2, "summary": "Morloc data packets carry a compression byte in their header, so any packet written to disk can transparently round-trip through a compressor.", "headings": [ { "id": "_compression_in_write", "title": "Compression in @write", "number": "8.5.1." }, { "id": "_compression_in_morloc_nexus_run", "title": "Compression in morloc-nexus run", "number": "8.5.2." }, { "id": "_compression_level_table", "title": "Compression-level table", "number": "8.5.3." }, { "id": "_algorithm_agnostic_surface", "title": "Algorithm-agnostic surface", "number": "8.5.4." }, { "id": "_caching_is_unaffected", "title": "Caching is unaffected", "number": "8.5.5." } ] }, { "number": "8.6.", "title": "Debugging", "id": "debugging", "url": "https://morloc-project.github.io/docs/runs/debugging.html", "md": "https://morloc-project.github.io/docs/runs/debugging.md", "chapter": "runs", "level": 2, "summary": "When a foreign function throws — a Python ZeroDivisionError, a C++ std::invalid_argument, an R stop(…​) — the default behavior of a morloc-built program is...", "headings": [ { "id": "_enabling_at_compile_time", "title": "Enabling at compile time", "number": "8.6.1." }, { "id": "_a_failing_run", "title": "A failing run", "number": "8.6.2." }, { "id": "debug-knobs", "title": "Runtime knobs", "number": "8.6.3." }, { "id": "dump-location", "title": "Where dumps land", "number": "8.6.4." }, { "id": "_content_addressed_dedup", "title": "Content-addressed dedup", "number": "8.6.5." }, { "id": "_frame_status_markers", "title": "Frame status markers", "number": "8.6.6." }, { "id": "_recovering_an_input_via_load", "title": "Recovering an input via @load", "number": "8.6.7." }, { "id": "_interaction_with_the_cache", "title": "Interaction with the cache", "number": "8.6.8." } ] }, { "number": "8.7.", "title": "Random access and streaming", "id": "random-access-and-streaming", "url": "https://morloc-project.github.io/docs/runs/random-access-and-streaming.html", "md": "https://morloc-project.github.io/docs/runs/random-access-and-streaming.md", "chapter": "runs", "level": 2, "summary": "Three abstract types describe a value that lives in a file rather than in memory:", "headings": [ { "id": "_random_access_with_ifile", "title": "Random access with IFile", "number": "8.7.1." }, { "id": "_sequential_writing_with_ostream", "title": "Sequential writing with OStream", "number": "8.7.2." }, { "id": "_sequential_reading_with_istream", "title": "Sequential reading with IStream", "number": "8.7.3." }, { "id": "_typed_standard_streams", "title": "Typed standard streams", "number": "8.7.4." }, { "id": "stream-env-vars", "title": "Environment variables", "number": "8.7.5." } ] }, { "number": "9.", "title": "Utilities", "id": "utilities", "url": "https://morloc-project.github.io/docs/utilities/", "md": "https://morloc-project.github.io/docs/utilities/index.md", "chapter": "utilities", "level": 1, "summary": "The nexus ships two utility subcommands that operate on data files without needing a compiled morloc program: file (identifies a file) and view (loads and...", "headings": [] }, { "number": "9.1.", "title": "morloc-nexus file", "id": "nexus-file", "url": "https://morloc-project.github.io/docs/utilities/nexus-file.html", "md": "https://morloc-project.github.io/docs/utilities/nexus-file.md", "chapter": "utilities", "level": 2, "summary": "morloc-nexus file plays the role of the UNIX file utility for Morloc-compatible data files.", "headings": [ { "id": "stream-packets", "title": "Stream packets", "number": "9.1.1." }, { "id": "_options", "title": "Options", "number": "9.1.2." }, { "id": "_verbose_example", "title": "Verbose example", "number": "9.1.3." } ] }, { "number": "9.2.", "title": "morloc-nexus view", "id": "nexus-view", "url": "https://morloc-project.github.io/docs/utilities/nexus-view.html", "md": "https://morloc-project.github.io/docs/utilities/nexus-view.md", "chapter": "utilities", "level": 2, "summary": "Reads a data file (morloc data-packet, morloc stream-packet, .json, .mpk, .arrow, .parquet, or .csv) and re-emits it in a chosen output format.", "headings": [ { "id": "_reading_from_stdin", "title": "Reading from stdin", "number": "9.2.1." }, { "id": "_schema_resolution", "title": "Schema resolution", "number": "9.2.2." }, { "id": "_pattern_extract_a_subset", "title": "--pattern: extract a subset", "number": "9.2.3." }, { "id": "_packet_shape_output_s_d_p", "title": "Packet-shape output: -s / -d / -p", "number": "9.2.4." }, { "id": "_f_jsonl_line_delimited_json", "title": "-f jsonl: line-delimited JSON", "number": "9.2.5." }, { "id": "view-size-guardrails", "title": "Size guardrails and --force", "number": "9.2.6." }, { "id": "footer-less-streams", "title": "Footer-less streams", "number": "9.2.7." }, { "id": "_options_2", "title": "Options", "number": "9.2.8." } ] }, { "number": "9.3.", "title": "mim (Morloc Installation Manager)", "id": "mim", "url": "https://morloc-project.github.io/docs/utilities/mim.html", "md": "https://morloc-project.github.io/docs/utilities/mim.md", "chapter": "utilities", "level": 2, "summary": "", "headings": [ { "id": "_system_scope_environments", "title": "System-scope environments", "number": "9.3.1." }, { "id": "_rebuilding_and_reconfiguring_environments", "title": "Rebuilding and reconfiguring environments", "number": "9.3.2." }, { "id": "mim-packages", "title": "Packages", "number": "9.3.3." }, { "id": "mim-language-toolchains", "title": "Language toolchains", "number": "9.3.4." }, { "id": "_development_environments", "title": "Development environments", "number": "9.3.5." }, { "id": "_inspecting_an_environment", "title": "Inspecting an environment", "number": "9.3.6." }, { "id": "_checking_environment_health", "title": "Checking environment health", "number": "9.3.7." }, { "id": "_the_environment_home_and_dotfiles", "title": "The environment home and dotfiles", "number": "9.3.8." }, { "id": "mim-serve", "title": "Serving installed programs", "number": "9.3.9." }, { "id": "_install", "title": "install", "number": "" }, { "id": "_view", "title": "view", "number": "" }, { "id": "mim-start", "title": "start", "number": "" }, { "id": "_status_stop_logs", "title": "status, stop, logs", "number": "" }, { "id": "_eval", "title": "eval", "number": "" }, { "id": "mim-freeze", "title": "freeze", "number": "" } ] }, { "number": "9.4.", "title": "morloc eval", "id": "morloc-eval", "url": "https://morloc-project.github.io/docs/utilities/morloc-eval.html", "md": "https://morloc-project.github.io/docs/utilities/morloc-eval.md", "chapter": "utilities", "level": 2, "summary": "Morloc has three subcommands that turn source into a result, and they serve distinct roles:", "headings": [ { "id": "_imports_in_eval_strings", "title": "Imports in eval strings", "number": "9.4.1." }, { "id": "_the_eval_sandbox", "title": "The eval sandbox", "number": "9.4.2." }, { "id": "_single_line_layout_braces_and_semicolons", "title": "Single-line layout: braces and semicolons", "number": "9.4.3." }, { "id": "_saving_an_eval_expression_as_a_command", "title": "Saving an eval expression as a command", "number": "9.4.4." } ] }, { "number": "10.", "title": "Modules and Libraries", "id": "modules", "url": "https://morloc-project.github.io/docs/modules/", "md": "https://morloc-project.github.io/docs/modules/index.md", "chapter": "modules", "level": 1, "summary": "", "headings": [] }, { "number": "10.1.", "title": "Importing modules", "id": "importing-modules", "url": "https://morloc-project.github.io/docs/modules/importing-modules.html", "md": "https://morloc-project.github.io/docs/modules/importing-modules.md", "chapter": "modules", "level": 2, "summary": "Every Morloc file is a module.", "headings": [] }, { "number": "10.2.", "title": "Installing modules", "id": "installing-modules", "url": "https://morloc-project.github.io/docs/modules/installing-modules.html", "md": "https://morloc-project.github.io/docs/modules/installing-modules.md", "chapter": "modules", "level": 2, "summary": "The default Morloc modules are hosted on GitHub under the morloclib organization.", "headings": [ { "id": "configuring-cpp-build", "title": "Configuring the C++ build", "number": "10.2.1." } ] }, { "number": "10.3.", "title": "The universal library", "id": "universal-library", "url": "https://morloc-project.github.io/docs/modules/universal-library.html", "md": "https://morloc-project.github.io/docs/modules/universal-library.md", "chapter": "modules", "level": 2, "summary": "A module may export types, typeclasses, and function signatures but no implementations.", "headings": [] }, { "number": "11.", "title": "Language Support", "id": "languages", "url": "https://morloc-project.github.io/docs/languages/", "md": "https://morloc-project.github.io/docs/languages/index.md", "chapter": "languages", "level": 1, "summary": "", "headings": [] }, { "number": "11.1.", "title": "Build parameters", "id": "build-parameters", "url": "https://morloc-project.github.io/docs/languages/build-parameters.html", "md": "https://morloc-project.github.io/docs/languages/build-parameters.md", "chapter": "languages", "level": 2, "summary": "Morloc compiles each part of a program with its own language toolchain.", "headings": [ { "id": "_per_machine_defaults_with_morloc_config", "title": "Per-machine defaults with morloc config", "number": "11.1.1." }, { "id": "_per_session_defaults_with_morloc_lang_params", "title": "Per-session defaults with MORLOC_LANG_PARAMS", "number": "11.1.2." }, { "id": "_precedence", "title": "Precedence", "number": "11.1.3." }, { "id": "_recognized_keys", "title": "Recognized keys", "number": "11.1.4." }, { "id": "_build_parameters_vs_package_yaml", "title": "Build parameters vs. package.yaml", "number": "11.1.5." } ] }, { "number": "11.2.", "title": "C++", "id": "cpp", "url": "https://morloc-project.github.io/docs/languages/cpp.html", "md": "https://morloc-project.github.io/docs/languages/cpp.md", "chapter": "languages", "level": 2, "summary": "C++ has no language-level package manager, so a C++ pool’s dependencies are external system libraries: the environment provisions the library (its headers...", "headings": [ { "id": "_library_dependencies_cpp_deps", "title": "Library dependencies (cpp-deps)", "number": "11.2.1." }, { "id": "_link_flags_dependencies", "title": "Link flags (dependencies)", "number": "11.2.2." } ] }, { "number": "11.3.", "title": "Python", "id": "python", "url": "https://morloc-project.github.io/docs/languages/python.html", "md": "https://morloc-project.github.io/docs/languages/python.md", "chapter": "languages", "level": 2, "summary": "", "headings": [ { "id": "py-deps", "title": "Dependencies (py-deps)", "number": "11.3.1." }, { "id": "_conda_channels", "title": "conda channels", "number": "" }, { "id": "local-deps", "title": "Local packages (local-deps)", "number": "11.3.2." } ] }, { "number": "11.4.", "title": "R", "id": "r", "url": "https://morloc-project.github.io/docs/languages/r.html", "md": "https://morloc-project.github.io/docs/languages/r.md", "chapter": "languages", "level": 2, "summary": "", "headings": [ { "id": "r-deps", "title": "Dependencies (r-deps)", "number": "11.4.1." } ] }, { "number": "11.5.", "title": "Rust", "id": "rust", "url": "https://morloc-project.github.io/docs/languages/rust.html", "md": "https://morloc-project.github.io/docs/languages/rust.md", "chapter": "languages", "level": 2, "summary": "", "headings": [ { "id": "_cargo_pools", "title": "Cargo pools", "number": "11.5.1." }, { "id": "rust-deps", "title": "Dependencies (rust-deps)", "number": "11.5.2." }, { "id": "_local_crates_local_deps", "title": "Local crates (local-deps)", "number": "11.5.3." }, { "id": "_one_resolution_per_environment", "title": "One resolution per environment", "number": "11.5.4." } ] }, { "number": "11.6.", "title": "Futhark", "id": "futhark", "url": "https://morloc-project.github.io/docs/languages/futhark.html", "md": "https://morloc-project.github.io/docs/languages/futhark.md", "chapter": "languages", "level": 2, "summary": "", "headings": [ { "id": "_futhark_backends_and_gpu_devices", "title": "Futhark backends and GPU devices", "number": "11.6.1." } ] }, { "number": "12.", "title": "Installation, Versions, and Deployment", "id": "install", "url": "https://morloc-project.github.io/docs/install/", "md": "https://morloc-project.github.io/docs/install/index.md", "chapter": "install", "level": 1, "summary": "mim is distributed as a static binary for x86 Linux, Linux ARM, and Apple Silicon macOS.", "headings": [] }, { "number": "12.1.", "title": "Choosing a container engine", "id": "container-engine", "url": "https://morloc-project.github.io/docs/install/container-engine.html", "md": "https://morloc-project.github.io/docs/install/container-engine.md", "chapter": "install", "level": 2, "summary": "There is no separate setup step.", "headings": [] }, { "number": "12.2.", "title": "Creating an environment", "id": "creating-an-environment", "url": "https://morloc-project.github.io/docs/install/creating-an-environment.html", "md": "https://morloc-project.github.io/docs/install/creating-an-environment.md", "chapter": "install", "level": 2, "summary": "An environment is a self-contained Morloc installation: a base container image (or, on the native backend, none), a pinned Morloc compiler and runtime, a...", "headings": [] }, { "number": "12.3.", "title": "Running commands", "id": "running-commands", "url": "https://morloc-project.github.io/docs/install/running-commands.html", "md": "https://morloc-project.github.io/docs/install/running-commands.md", "chapter": "install", "level": 2, "summary": "run executes a command inside an environment (the default when no --env is given); shell drops you into an interactive shell:", "headings": [] }, { "number": "12.4.", "title": "Managing environments", "id": "managing-environments", "url": "https://morloc-project.github.io/docs/install/managing-environments.html", "md": "https://morloc-project.github.io/docs/install/managing-environments.md", "chapter": "install", "level": 2, "summary": "You can keep multiple named environments and act on any of them with --env:", "headings": [] }, { "number": "12.5.", "title": "Customizing environments", "id": "customizing-environments", "url": "https://morloc-project.github.io/docs/install/customizing-environments.html", "md": "https://morloc-project.github.io/docs/install/customizing-environments.md", "chapter": "install", "level": 2, "summary": "An environment’s contents are declared, not scripted: there is no user Dockerfile.", "headings": [] }, { "number": "12.6.", "title": "Extra container flags", "id": "extra-container-flags", "url": "https://morloc-project.github.io/docs/install/extra-container-flags.html", "md": "https://morloc-project.github.io/docs/install/extra-container-flags.md", "chapter": "install", "level": 2, "summary": "Anything a container engine needs beyond what mim passes on its own — a GPU device, a proxy, a bind mount, a hostname — goes in an engine flag file: a YAML...", "headings": [] }, { "number": "12.7.", "title": "Deployment: serve and freeze", "id": "serve-and-freeze", "url": "https://morloc-project.github.io/docs/install/serve-and-freeze.html", "md": "https://morloc-project.github.io/docs/install/serve-and-freeze.md", "chapter": "install", "level": 2, "summary": "Once a program is installed in an environment (mim install, or morloc make --install inside it) there are two ways to put it in front of other machines and...", "headings": [ { "id": "_local_serving_with_start", "title": "Local serving with start", "number": "12.7.1." }, { "id": "_portable_images_with_freeze", "title": "Portable images with freeze", "number": "12.7.2." } ] }, { "number": "12.8.", "title": "Beyond fixed APIs: composable function services", "id": "composable-function-services", "url": "https://morloc-project.github.io/docs/install/composable-function-services.html", "md": "https://morloc-project.github.io/docs/install/composable-function-services.md", "chapter": "install", "level": 2, "summary": "A conventional API exposes a fixed set of endpoints.", "headings": [] }, { "number": "12.9.", "title": "Execution contexts", "id": "execution-contexts", "url": "https://morloc-project.github.io/docs/install/execution-contexts.html", "md": "https://morloc-project.github.io/docs/install/execution-contexts.md", "chapter": "install", "level": 2, "summary": "A term in morloc can be annotated with a label that associates the term with a computational context.", "headings": [ { "id": "_the_remote_context_dispatching_as_a_separate_job", "title": "The remote: context: dispatching as a separate job", "number": "12.9.1." }, { "id": "_enabling_dispatch_codegen", "title": "Enabling dispatch codegen", "number": "12.9.2." }, { "id": "dispatch-bridge", "title": "Running with the dispatch bridge", "number": "12.9.3." }, { "id": "_what_lands_on_the_shared_filesystem", "title": "What lands on the shared filesystem", "number": "12.9.4." }, { "id": "_preconditions_and_the_doctor_check", "title": "Preconditions and the doctor check", "number": "12.9.5." } ] }, { "number": "12.10.", "title": "System-wide environments with Podman", "id": "system-wide-podman", "url": "https://morloc-project.github.io/docs/install/system-wide-podman.html", "md": "https://morloc-project.github.io/docs/install/system-wide-podman.md", "chapter": "install", "level": 2, "summary": "Podman stores images per-user.", "headings": [] }, { "number": "13.", "title": "Build Architecture", "id": "internals", "url": "https://morloc-project.github.io/docs/internals/", "md": "https://morloc-project.github.io/docs/internals/index.md", "chapter": "internals", "level": 1, "summary": "", "headings": [] }, { "number": "13.1.", "title": "Architecture Overview", "id": "architecture-overview", "url": "https://morloc-project.github.io/docs/internals/architecture-overview.html", "md": "https://morloc-project.github.io/docs/internals/architecture-overview.md", "chapter": "internals", "level": 2, "summary": "A compiled Morloc program has two kinds of components: one nexus and one or more pools.", "headings": [] }, { "number": "13.2.", "title": "Cross-language function calls", "id": "cross-language-calls", "url": "https://morloc-project.github.io/docs/internals/cross-language-calls.html", "md": "https://morloc-project.github.io/docs/internals/cross-language-calls.md", "chapter": "internals", "level": 2, "summary": "When a Morloc program composes functions from different languages, the compiler must bridge the language boundary.", "headings": [ { "id": "_how_it_works", "title": "How it works", "number": "13.2.1." }, { "id": "_what_the_generated_code_looks_like", "title": "What the generated code looks like", "number": "13.2.2." }, { "id": "_performance_implications", "title": "Performance implications", "number": "13.2.3." } ] }, { "number": "13.3.", "title": "Protocols", "id": "protocols", "url": "https://morloc-project.github.io/docs/internals/protocols.html", "md": "https://morloc-project.github.io/docs/internals/protocols.md", "chapter": "internals", "level": 2, "summary": "This section describes the binary formats used for communication between the nexus and pools: the manifest, the packet protocol, the shared memory layout,...", "headings": [ { "id": "_the_manifest", "title": "The manifest", "number": "13.3.1." }, { "id": "_packet_protocol", "title": "Packet protocol", "number": "13.3.2." }, { "id": "_packet_types", "title": "Packet types", "number": "" }, { "id": "_metadata_blocks", "title": "Metadata blocks", "number": "" }, { "id": "_shared_memory", "title": "Shared memory", "number": "13.3.3." }, { "id": "_volumes", "title": "Volumes", "number": "" }, { "id": "_pointer_types", "title": "Pointer types", "number": "" }, { "id": "_volume_header_shm_t", "title": "Volume header (shm_t)", "number": "" }, { "id": "_block_header_block_header_t_packed", "title": "Block header (block_header_t, packed)", "number": "" }, { "id": "schema-strings", "title": "Schema strings", "number": "13.3.4." }, { "id": "_voidstar_binary_format", "title": "Voidstar binary format", "number": "13.3.5." } ] }, { "number": "13.4.", "title": "Runtime and Dev Builds", "id": "runtime-and-dev-builds", "url": "https://morloc-project.github.io/docs/internals/runtime-and-dev-builds.html", "md": "https://morloc-project.github.io/docs/internals/runtime-and-dev-builds.md", "chapter": "internals", "level": 2, "summary": "The Morloc runtime — the shared library (libmorloc.so) and the nexus binary (morloc-nexus) — is written in Rust.", "headings": [ { "id": "build-modes", "title": "Build modes", "number": "13.4.1." }, { "id": "_what_the_runtime_provides", "title": "What the runtime provides", "number": "13.4.2." }, { "id": "_build_dependencies", "title": "Build dependencies", "number": "13.4.3." }, { "id": "_container_images", "title": "Container images", "number": "13.4.4." } ] }, { "number": "14.", "title": "Future Directions", "id": "future", "url": "https://morloc-project.github.io/docs/future/", "md": "https://morloc-project.github.io/docs/future/index.md", "chapter": "future", "level": 1, "summary": "", "headings": [ { "id": "planes-of-libraries", "title": "Planes of libraries", "number": "14.1." } ] }, { "number": "15.", "title": "Q&A", "id": "qa", "url": "https://morloc-project.github.io/docs/qa/", "md": "https://morloc-project.github.io/docs/qa/index.md", "chapter": "qa", "level": 1, "summary": "", "headings": [] }, { "number": "15.1.", "title": "I only use one language, is Morloc still useful?", "id": "one-language", "url": "https://morloc-project.github.io/docs/qa/one-language.html", "md": "https://morloc-project.github.io/docs/qa/one-language.md", "chapter": "qa", "level": 2, "summary": "Yes, Morloc remains useful even if you only use one programming language.", "headings": [] }, { "number": "15.2.", "title": "Is this just a bioinformatics workflow language?", "id": "bioinformatics-only", "url": "https://morloc-project.github.io/docs/qa/bioinformatics-only.html", "md": "https://morloc-project.github.io/docs/qa/bioinformatics-only.md", "chapter": "qa", "level": 2, "summary": "No.", "headings": [] }, { "number": "15.3.", "title": "Does Morloc allow function-specific containerized environments?", "id": "per-function-environments", "url": "https://morloc-project.github.io/docs/qa/per-function-environments.html", "md": "https://morloc-project.github.io/docs/qa/per-function-environments.md", "chapter": "qa", "level": 2, "summary": "No, unlike workflow managers such as Snakemake and Nextflow, Morloc does not offer function-specific environments.", "headings": [] }, { "number": "15.4.", "title": "What about object-oriented programming?", "id": "object-oriented", "url": "https://morloc-project.github.io/docs/qa/object-oriented.html", "md": "https://morloc-project.github.io/docs/qa/object-oriented.md", "chapter": "qa", "level": 2, "summary": "An \"object\" is a somewhat loaded term in the programming world.", "headings": [] }, { "number": "15.5.", "title": "Is Morloc still relevant when AI can program and translate?", "id": "ai-relevance", "url": "https://morloc-project.github.io/docs/qa/ai-relevance.html", "md": "https://morloc-project.github.io/docs/qa/ai-relevance.md", "chapter": "qa", "level": 2, "summary": "Maybe.", "headings": [] }, { "number": "15.6.", "title": "I’m not a human, do I still need Morloc?", "id": "not-a-human", "url": "https://morloc-project.github.io/docs/qa/not-a-human.html", "md": "https://morloc-project.github.io/docs/qa/not-a-human.md", "chapter": "qa", "level": 2, "summary": "Yes, you are still a programmer and writing endless glue code to stitch things together takes time and is brittle.", "headings": [] }, { "number": "15.7.", "title": "Why is it named after Morlocks, weren’t they, like, bad?", "id": "morlocks", "url": "https://morloc-project.github.io/docs/qa/morlocks.html", "md": "https://morloc-project.github.io/docs/qa/morlocks.md", "chapter": "qa", "level": 2, "summary": "While the Morlocks of Wellian fame are best known for their culinary preferences, I think Wells misrepresented them.", "headings": [] }, { "number": "15.8.", "title": "Wait! I have more questions!", "id": "more-questions", "url": "https://morloc-project.github.io/docs/qa/more-questions.html", "md": "https://morloc-project.github.io/docs/qa/more-questions.md", "chapter": "qa", "level": 2, "summary": "Great!", "headings": [] }, { "number": "16.", "title": "Environmental Variable List", "id": "env", "url": "https://morloc-project.github.io/docs/env/", "md": "https://morloc-project.github.io/docs/env/index.md", "chapter": "env", "level": 1, "summary": "Every environment variable that morloc reads or sets lives in the MORLOC_ namespace.", "headings": [ { "id": "env-installation", "title": "Installation and runtime setup", "number": "16.1." }, { "id": "env-module-installation", "title": "Module installation (setup-script environment)", "number": "16.2." }, { "id": "env-run-directory", "title": "Run directory, logging, and reporting", "number": "16.3." }, { "id": "env-debugging", "title": "Debugging", "number": "16.4." }, { "id": "env-caching", "title": "Caching", "number": "16.5." }, { "id": "env-data-transfer", "title": "Data transfer (packets and shared memory)", "number": "16.6." }, { "id": "env-streaming", "title": "Streaming and compression", "number": "16.7." }, { "id": "env-nexus-wiring", "title": "Nexus and inter-process wiring", "number": "16.8." }, { "id": "env-inspection-tools", "title": "Nexus inspection tools (view / file)", "number": "16.9." }, { "id": "env-string-safety", "title": "String safety", "number": "16.10." } ] }, { "number": "17.", "title": "Contact", "id": "contact", "url": "https://morloc-project.github.io/docs/contact/", "md": "https://morloc-project.github.io/docs/contact/index.md", "chapter": "contact", "level": 1, "summary": "This is a young project and any brave early users are highly valued.", "headings": [] } ] }