SourcePath: .
SourceExt: _doc.yaml

Categories:
  - ID: commands
    Title: Command Reference
    Description: |-
      This section is a glossary of Murex builtin commands.
      
      Because Murex is loosely modelled on the functional paradigm, it means
      all language constructs are exposed via functions and those are typically
      builtins because they can share the Murex runtime virtual machine.
      However any executable command can also be called from within Murex;
      be that either via the `exec` builtin or natively like you would from any
      Linux, UNIX, or even Windows command prompt.

      ## Other Reference Material

      ### Language Guides

      1. [Language Tour](tour.md), which is an introduction into
         the Murex language.

      2. [Rosetta Stone](user-guide/rosetta-stone.md), which is a reference
         table comparing Bash syntax to Murex's.

      ### Murex's Source Code

      The source for each of these builtins can be found on [Github](https://github.com/lmorg/murex/tree/master/builtins/core).

      ### Shell Commands For Querying Builtins

      From the shell itself: run `builtins` to list the builtin command.

      If you require a manual on any of those commands, you can run `murex-docs`
      to return the same markdown-formatted document as those listed below. eg

      ```
      murex-docs trypipe
      ```
  
    Templates:
    - OutputPath: docs/commands
      CategoryFile: ../GUIDE.builtin-functions.md
      OutputExt: .md
      CategoryTemplate: gen/commands-md-cat.tmpl
      DocumentTemplate: gen/commands-md-doc.tmpl

    - OutputPath: builtins/docs
      CategoryFile: 000_summaries_commands_docgen.go
      OutputExt: _commands_docgen.go
      CategoryTemplate: gen/commands-go-cat.tmpl
      DocumentTemplate: gen/commands-go-doc.tmpl

    - OutputPath: builtins
      CategoryFile: docgen_test.go
      OutputExt: _commands_docgen.go
      CategoryTemplate: gen/commands-go_test-cat.tmpl
      DocumentTemplate:

  - ID: mkarray
    Title: mkarray
    Description:
    Templates:
    - OutputPath: docs/mkarray
      CategoryFile: ../../gen/includes/autogenerated.mkarray.inc.md
      OutputExt: .md
      CategoryTemplate: gen/mkarray-md-cat.tmpl
      DocumentTemplate: gen/mkarray-md-doc.tmpl

  - ID: optional
    Title: Optional Command Reference
    Description: |-
      This section is a glossary of Murex optional builtins.
      
      These builtins likely wont be compiled with Murex unless you specifically
      request them to be. This might be because they duplicate functionality
      already available on POSIX systems or introduce more complex dependencies.
      It might also be because that specific builtin is in an alpha stage and thus
      not ready to ship with Murex.

      ## Other Reference Material

      ### Language Guides

      1. [Core Builtins](./GUIDE.builtin-functions.md), for docs
         on the core builtins.

      2. [Language Tour](tour.md), which is an introduction into
         the Murex language.

      3. [Rosetta Stone](user-guide/rosetta-stone.md), which is a reference
         table comparing Bash syntax to Murex's.

      ### Murex's Source Code

      The source for each of these builtins can be found on [Github](https://github.com/lmorg/murex/tree/master/builtins/optional).

      ### Shell Commands For Querying Builtins

      From the shell itself: run `builtins` to list the builtin command.

      If you require a manual on any of those commands, you can run `murex-docs`
      to return the same markdown-formatted document as those listed below. eg

      ```
      murex-docs trypipe
      ```
    Templates:
    - OutputPath: docs/optional
      CategoryFile: ../GUIDE.optional-commands.md
      OutputExt: .md
      CategoryTemplate: gen/murex-md-cat.tmpl
      DocumentTemplate: gen/commands-md-doc.tmpl

    - OutputPath: builtins/docs
      CategoryFile: 
      OutputExt: _commands_docgen.go
      CategoryTemplate: 
      DocumentTemplate: gen/commands-go-doc.tmpl

  - ID: parser
    Title: Parser Reference
    Description: |-
      This section is a glossary of Murex tokens and parser behavior.
  
      ## Other Reference Material

      ### Language Guides

      1. [Language Tour](tour.md), which is an introduction into
         the Murex language.

      2. [Rosetta Stone](user-guide/rosetta-stone.md), which is a reference
         table comparing Bash syntax to Murex's.

      3. [Builtins](./GUIDE.builtin-functions.md), for docs on the core builtins.

      ### Murex's Source Code

      The parser is located Murex's source under the `lang/` path of the project
      files.
  
    Templates:
    - OutputPath: docs/parser
      CategoryFile: ../GUIDE.parser.md
      OutputExt: .md
      CategoryTemplate: gen/murex-md-cat.tmpl
      DocumentTemplate: gen/parser-md-doc.tmpl

  # events:
  - ID: events
    Title: events
    Description:
    Templates:
    - OutputPath: docs/events
      CategoryFile: ../../gen/includes/autogenerated.events.inc.md
      OutputExt: .md
      CategoryTemplate: gen/events-md-cat.tmpl
      DocumentTemplate: gen/events-md-doc.tmpl

  # types:
  - ID: types
    Title: Data-Type Reference
    Description: |-
      This section is a glossary of data-types which Murex is natively aware.

      Most of the time you will not need to worry about typing in Murex as the
      shell is designed around productivity as opposed to strictness despite
      generally following a strictly typed design.

      Read the [Language Tour](tour.md) for more detail on this topic.

      ## Definitions
      
      For clarity, it is worth explaining a couple of terms:
      
      1. "Data-types" in Murex are a description of the format of data. This
      means that while any stdio stream in UNIX will by "bytes", Murex might
      label that data as being a JSON string or CSV file (for example) which
      means any builtins that parse that stdio stream, for example to return
      the first 8 items, would need to parse those types differently. Thus a
      "data-type" in Murex is actually more than just a description of a data
      structure; it is a series of APIs to marshall and unmarshall data from
      complex file formats. This enables you to use the same command line tools
      to query any type of output.

      2. "Primitive" data-types refer to types that are the required by Murex
      to function. These will be `int`, `float` / `number`, `bool`, `string`,
      `generic`, and `null`.

      ## Feature Sets
      
      Since not all data formats are equal (for example the TOML file format
      doesn't support naked arrays where as JSON does), you may find some
      features missing in some data-types which are present in others. If in
      doubt then refer to the manual here or check the API manual for more
      details about specific hooks.

    Templates:
    - OutputPath: docs/types
      CategoryFile: ../GUIDE.type-system.md
      OutputExt: .md
      CategoryTemplate: gen/murex-md-cat.tmpl
      DocumentTemplate: gen/types-md-doc.tmpl

    #- OutputPath: builtins/docs
    #  CategoryFile: 000_summaries_commands_docgen.go
    #  OutputExt: _commands_docgen.go
    #  CategoryTemplate: gen/commands-go-cat.tmpl
    #  DocumentTemplate: gen/commands-go-doc.tmpl

    #- OutputPath: builtins
    #  CategoryFile: docgen_test.go
    #  OutputExt: _commands_docgen.go
    #  CategoryTemplate: gen/commands-go_test-cat.tmpl
    #  DocumentTemplate: 

  # pipes:

  # apis:
  - ID: apis
    Title: API Reference
    Description: |-
      This section is a glossary of APIs.
      
      These APIs are provided for reference for any developers wishing to write
      their own builtins. However some APIs are still worth being aware of even
      when just writing Murex scripts because they provide a background into
      the internal logic of Murex's runtime.

    Templates:
    - OutputPath: docs/apis
      CategoryFile: ../GUIDE.apis.md
      OutputExt: .md
      CategoryTemplate: gen/murex-md-cat.tmpl
      DocumentTemplate: gen/apis-md-doc.tmpl

  # user guide:
  - ID: user-guide
    Title: User Guide
    Description: |-
      This section contains miscellaneous documents on using and configuring the
      shell and Murex's numerous features.
    Templates:
    - OutputPath: docs/user-guide
      CategoryFile: ../user-guide.md
      OutputExt: .md
      CategoryTemplate: gen/userguide-md-cat.tmpl.md
      DocumentTemplate: gen/userguide-md-doc.tmpl

  # blog
  - ID: blog
    Title: Blog
    Description: |-
      Collection of Murex related documents and personal thoughts.
    Templates:
    - OutputPath: docs/blog
      CategoryFile: ../BLOG.md
      OutputExt: .md
      CategoryTemplate: gen/blog-md-cat.tmpl
      DocumentTemplate: gen/blog-md-doc.tmpl

  # changelog
  - ID: changelog
    Title: Change Log
    Description: |-
      Track new features, any breaking changes, and the release history here.
    Templates:
    - OutputPath: docs/changelog
      CategoryFile: ../CHANGELOG.md
      OutputExt: .md
      CategoryTemplate: gen/changelog-md-cat.tmpl
      DocumentTemplate: gen/changelog-md-doc.tmpl
