pmsLibrary: A library of useful APL functions and operators, specified as prototypes, best implemented within the language. NOTE: Slowly moving to a standard style (Classes in CamelCase, methods in lower_case).

• For source files, see pmsLibrary/src, all .dyalog files.
• For help information, see pmsLibrary/docs, mostly .help text files, but see formatHelp.pdf.
• For user command ]require, see README in directory pmsLibrary/userCmds.

This is a work in progress, as I move a handful of such functions out of workspaces into github.

Table of Contents

• require Ensure that APL objects required within a specific function or package are in the active workspace visible via ⎕PATH, loading as needed from other workspaces or directories.
  • See also pmsLibrary/userCmds/README.md, to learn how to make it easy to have require available throughout a Dyalog session.
• ∆MY Support static objects tied to a function/op, created once and maintained over calls.
• Dict Create ordered dictionaries with an array of creation, sorting, and searching services.
• TinyDict Create low-overhead, ordered dictionaries with simple access to keys and values.
• gen Create Python-like generators that allow for functions to iteratively "yield" values without returning.
• future Create simple future objects, whose values may be scalars within APL arrays, built on isolate-related I-beams.
• ∆format, ∆f Support Python-like f-strings extended for APL multi-dimentional objects, allowing for variable interpolation into quoted strings.
• ∆FIX OBSOLETE. See ∆PRE. A preprocessor for .dyalog files, which may contain a namespace-class object, functions, and operators, along with preprocessor statements ::IF, ::IFDEF, ::DEF, macro-like name substitution, "atoms" (pseudo-parameter names), continuation lines, etc.
• ∆FPTR Create a scalar or list of function ptrs, namespaces that include the function and initial parameters.
• bigInt Provides support for arbitrary-precision integers in convenient and higher-performance formats, along with an arbitrary-precision desk calculator in the tradition of Unix's dc.
• ∆HERE Robust support for "here" documents or "immediate" multiline strings within APL functions/ops, allowing multi-line HTML, documentation, or special strings to be pasted from other sources (or otherwise created) and passed to various APL routines.
• ∆SH Provides a thin cover to ⎕SH, translating UTF-8 format encoded output into Unicode. Makes it easier to list filenames or contents that are encoded. (At least on OS X, while the terminal automatically handles this, ⎕SH does not.)
• ∆WHERE For each object nameN, return the namespace where it was found as well as whether found in caller namespace (see opts), in ⎕PATH, or anywhere in the workspace. opts include the caller (reference) namespace and/or a long-form flag (default 0).
• ∆OPTS Provide a simple package for handing options of the form -opt, -opt=value,-opt= value, etc. including the ability to handle non-string values, e.g. namespaces or object representations (⎕OR).

Descriptions of Packages

1. require: Reminiscent of import in Python and require or use in Perl, require ensures that the "packages" in the right argument are either in the caller's namespace or the ⎕PATH (e.g. were "required" by another function/op or otherwise), in the filesystem search path (Unix environment (extension) FSPATH or (Dyalog) WSPATH or using "extension" ⎕SE.∆FSPATH), or in the workspace indicated (e.g. 'dfns:cmpx'). If in the caller's namespace or ⎕PATH, nothing more is done. Also allows easy importing of an entire workspace ('dfns:') or all the *.dyalog files filesystem directory ('myfns.mymath').

   • ⍝ read cmpx from ws dfns, kt from same ws, tinyDict from subdir src, future from same subdir
⍝ If already in caller's ns or ⎕PATH, return quietly.
⍝ Store newly loaded objects (called packages) into a "standard library" (easily set by the user).
require 'dfns:cmpx' ':kt' 'src::tinyDict' '::future'
   • See require.dyalog and require.help.

2. ∆MY: Creates and manages a private namespace for the current calling function (determined from its actual APL name and the namespace in which it resides). It allows for static variables, i.e. ones that persist between executions, e.g. ∆MY.count+←1 and for initialization, e.g. :IF ∆MY.∆FIRST ⋄ ∆MY.count←0 ⋄ :ENDIF

   • See ∆MY.dyalog and ∆MY.help. If associated functions ∆MYX and ∆THEIR are used, add ∆MYgrp to the path:
     require '∆MYgrp.∆THEIR'
     will make all associated functions visible.

3. ∆DICT in namespace Dict: Create a robust dictionary using ⎕NEW or ∆DICT, with options for string, numeric or arbitrary defaults (vis-a-vis missing keys), sorting, and more.

4. TinyDict / ∆TINYDICT: Similar to ∆DICT, but designed for higher-performance, simpler environments. Uses a namespace, rather than a class; meant for memoization and similar simple, workhorse, situations.

5. gen: Function gen.erator creates generators, a type of iterator used in Python that "yields" multiple values in turn from an active function (passed by the user), rather than returning one at a time. Including yield and other tools. Example: a←{'done'⊣⍺.yield¨⍳10} gen.erator 0 passes values to a.next, signalling a STOPITERATION interrupt after the 10th value. a.value contains the return string done.

6. future: Uses some of the undocumented magic from isolates to create simple, in-workspace, futures, i.e. array elements that will block until their (asynchronous) values are in place. User beware-- none of the features are documented and may work differently than expected. (Based solely on the OS X implementation).
   a←{⎕DL ?⍵}future¨10 10⍴10 10 10 ⋄ ⍴a ⋄ b←100⍴a ⋄ ⊢a

7. ∆format / ∆f in namespace Format: An APL-specific implementation of format-strings, reminiscent of Python's f-strings, but supporting APL multidimensional objects directly and formatting based on ⎕FMT. Supports nice constructions like
   first←'John' ⋄ middle←'Jacob' 'Jingleheimer' ⋄ last←'Schmidt'
∆f'His name is {first} {middle} last. This name has {+/⍴∊first middle last} letters.'
His name is John Jacob Jingleheimer Schmidt. This name has 28 letters.
   Source: format. Help info: format_help.pdf.

8. bigInt: Provides basic arithmetic functions on big integers stored externally as strings and internally as a series of (signed) integers. Built around dfns:nat as its numerical core, extended to handle signed numbers, reduce and scan, factorial, and roll(?). Has both an easy-to-use operator style '2434324' *BI '3443' that takes care of importing and exporting APL numbers and (string-format) big integers, as well as a higher-performance function style bigInt.sqrt '449432342' suitable for user-designed algorithms. Easily extended to work with arbitrary APL arrays.
   Try the big integer desk calculator bi.dc to see how it works (for help: issue ? from the command line).

9. ∆FIX: Obsolete (see ∆PRE). A preprocessor for .dyalog files, which may contain a namespace-class object, functions, and operators, along with

   • preprocessor statements ::IF / ::THEN / ::ELSEIF, ::IFDEF, ::DEF, ::LET, and more,
   • macro-like name substitution,
   • "atoms" (pseudo-parameter names / set members) with the atom pseudo-operator (`)
     red←`red ⋄ colors←`red orange yellow ⋄ red∊colors
     and the parameter pseudo-operator (→)
     (name → 'John Jones')(address → '3432 Maiden Ln')(salaries monthly→ ?3⍴1000)
   • continuation lines,
     etc.

10. ∆FPTR: Create a scalar or list of function "ptrs", namespaces that include the function and initial parameters.

    • ptrs ← [alpha] {fn1} ∆FPTR {fn2} ∆FPTR {fn3} ∆FPTR omega Creates ptrs.∆fn, ptrs.(∆ALPHA, ∆OMEGA, ∆NARGS, ∆ID).

11. ∆HERE: When executed in a traditional function/operator or named dfn/op, generates and returns (as its value) a here document-- i.e. a collection of the contiguous (see options) comment lines that
    follow-- combined into a single string or a vector of string vectors, with the comment prefixes removed from each. Has options for string style, whether blank (non-comment) lines end the here document or not, and other options. Options are included within comments on the same line as the ∆HERE call, e.g.
    

   myHtml←∆HERE ⍝  ⍠ CR BLANKS   ⍝ CR: create a single string with carriage returns to end line; BLANKS: consider blanks part of HERE doc.
      ⍝ <!DOCTYPE html>
      ⍝ <html>
      ⍝ <body>

      ⍝ <p>Browsers usually insert quotation marks around the q element.</p>

      ⍝ <p>WWF's goal is to: <q>Build a future where people live in harmony with nature.</q></p>

     ⍝ </body>
     ⍝ </html>
  processMyHtml myHtml    ⍝ Take the string separated by carriage returns and process it for display, etc.

1. ∆WHERE: For each object nameN, return the namespace where it was found as well as whether found in caller namespace (see opts), in ⎕PATH, or anywhere in the workspace. opts include the caller (reference) namespace and/or a long-form flag (default 0).

   • res ← opts ∆WHERE name1 [name2 ...]

2. opts: ∆OPTS is not meant as a replacement for the ⎕SE.Parser, which is more flexible, but is useful when a user might be passing namespaces, class instances, or arrays. It expects each argument to be passed separately (unless in ⎕TEXT) mode and parses each argument in turn, so that it can distinguish flags (options without values), options with string values, and options with arbitrary values. See Documentation opts.help for details.

    )cs VERS1   
  ⍝ In advance, we set up #.VERS1.SOURCE and #.VERS1.SINK.
  ⍝ We'll use our own source #.MyLib instead of VERS1.SOURCE
  ⍝ ∘ Left of ∆OPTS are "program" specs; right of ∆OPTS are "user" run-time "calls"
  ⍝ ∘ -funOut is a required option (as shown by the option sep ':' not followed by any value)
    ns ←  'funOut:'  'source::'  SOURCE  'sink::'  SINK  ∆OPTS  'john' '-so' #.MyLib '-funOut' 'Schmidt' 'jacob' 'jingleheimer' 
    (ns.source)(⎕NC 'ns.source')'→→→'(ns.sink)(⎕NC 'ns.sink')    
#.MyLib  9  →→→  #.VERS1.SINK  2                                  ⍝ Default -sink was picked up! Note namespaces are refs, not strings.
    ns.(ARGS funOut) ns.(≢¨ARGS funOut)          
john  jacob  jingleheimer   Schmidt   3 1