@fnndsc/brasa 0.56.2 → 0.56.4

package/dist/builtins/res/files.js

@@ -1,55 +1,48 @@
 /**
- * @file Builtin files command (and links, dirs).
- * Manages file resources.
+ * @file `files`, `links` and `dirs`: CUBE's file, link and folder resources
+ * as rows (a listing of the records, not of a folder's contents, which `ls`
+ * shows), listed, searched, and their fields named.
+ *
+ * Declared in one record each (`filesCommand`, `linksCommand`,
+ * `dirsCommand`), of one grammar: the subcommands, the path a listing is
+ * under, and the listing options every resource command reads.
+ *
+ * Key components:
+ * - filesCommand / linksCommand / dirsCommand: the declarations.
+ * - builtin_files / builtin_links / builtin_dirs: each run over words already split.
+ *
+ * @module
  */
 import chalk from 'chalk';
-import { commandArgs_process, cliOptions_extract } from '../utils.js';
 import { files_fetchList } from '@fnndsc/chili/commands/files/list.js';
 import { fileFields_fetch } from '@fnndsc/chili/commands/files/fields.js';
 import { table_render } from '@fnndsc/chili/screen/screen.js';
 import { envelope_ok, envelope_error } from '@fnndsc/menu';
 import { exitCode_set } from '../../core/handlerRun.js';
+import { command_declare } from '../../core/commandDeclaration.js';
+import { declaredCommand_run } from '../../core/commandParse.js';
+import { RESOURCE_LIST_OPTIONS_GRAMMAR, resourceListBag_build } from './resourceList.js';
 /**
- * Generic handler for file group commands (files, links, dirs).
+ * Lists one kind of record, under a path when one is given.
  *
- * @param args - command arguments.
- * @param assetName - the asset type ('files', 'links', 'dirs').
- * @returns An envelope carrying the listing or fields.
+ * @param assetName - The kind.
+ * @param options - The bag chili's listing reads.
+ * @param path - The ChRIS path the records are under, or none.
+ * @returns The table, or that there are none, or the error.
  */
-async function builtin_fileGroup(args, assetName) {
-    const parsed = commandArgs_process(args);
-    const subcommand = parsed._[0];
-    if (!subcommand) {
-        return envelope_ok(`${chalk.red(`Usage: ${assetName} <list|search|inspect> ...`)}\n`);
-    }
+async function fileGroupList_render(assetName, options, path) {
     try {
-        if (subcommand === 'list') {
-            const path = parsed._[1];
-            const results = await files_fetchList(cliOptions_extract(parsed), assetName, path);
-            if (!results) {
-                return envelope_error('', undefined, `No ${assetName} resources found. Perhaps check your current context?\n`);
-            }
-            if (results.tableData.length === 0) {
-                return envelope_ok(`No ${assetName} found matching the criteria.\n`);
-            }
-            return envelope_ok(table_render(results.tableData, results.selectedFields, {
-                title: { title: assetName, justification: "center" },
-                pagination: results.totalCount !== undefined ? { shown: results.tableData.length, total: results.totalCount } : undefined,
-            }));
-        }
-        else if (subcommand === 'search') {
-            const query = parsed._[1] ?? '';
-            return builtin_fileGroup([...args.filter((a) => a !== subcommand), '--search', query], assetName);
+        const results = await files_fetchList(options, assetName, path);
+        if (!results) {
+            return envelope_error('', undefined, `No ${assetName} resources found. Perhaps check your current context?\n`);
         }
-        else if (subcommand === 'inspect' || subcommand === 'fieldslist') {
-            const fields = await fileFields_fetch(assetName);
-            if (fields && fields.length > 0) {
-                return envelope_ok(table_render(fields.map(f => ({ fields: f })), ["fields"]));
-            }
-            return envelope_ok(`No resource fields found for ${assetName}.\n`);
+        if (results.tableData.length === 0) {
+            return envelope_ok(`No ${assetName} found matching the criteria.\n`);
         }
-        exitCode_set(1);
-        return envelope_error(`${chalk.yellow(`Unknown subcommand: ${subcommand}. Usage: ${assetName} <list|search|inspect>`)}\n`);
+        return envelope_ok(table_render(results.tableData, results.selectedFields, {
+            title: { title: assetName, justification: 'center' },
+            pagination: results.totalCount !== undefined ? { shown: results.tableData.length, total: results.totalCount } : undefined,
+        }));
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
@@ -58,30 +51,117 @@ async function builtin_fileGroup(args, assetName) {
     }
 }
 /**
- * Handles files commands.
+ * Names the fields one kind of record has.
+ *
+ * @param assetName - The kind.
+ * @returns The fields' table, or that there are none.
+ */
+async function fileGroupFields_render(assetName) {
+    const fields = await fileFields_fetch(assetName);
+    if (fields && fields.length > 0) {
+        return envelope_ok(table_render(fields.map((f) => ({ fields: f })), ['fields']));
+    }
+    return envelope_ok(`No resource fields found for ${assetName}.\n`);
+}
+/** What a `files`, `links` or `dirs` line may hold. */
+const FILE_GROUP_GRAMMAR = {
+    subcommands: {
+        list: {
+            summary: 'List the records, 20 to a page, under a path when one is given',
+            operands: [{ name: 'path', kind: 'cfsPath', optional: true, summary: 'The ChRIS path the records are under' }],
+            options: { ...RESOURCE_LIST_OPTIONS_GRAMMAR },
+        },
+        search: {
+            summary: 'List the records a filter matches (list --search <term>)',
+            operands: [{ name: 'term', kind: 'word', summary: 'The filter, field:value (inspect names the fields)' }],
+            options: { ...RESOURCE_LIST_OPTIONS_GRAMMAR },
+        },
+        inspect: { summary: 'Name the fields a record has' },
+        fieldslist: { summary: 'The same as inspect' },
+    },
+};
+/**
+ * The handler of one kind of record's command.
+ *
+ * @param assetName - The kind.
+ * @returns The handler.
+ */
+function fileGroupHandler_make(assetName) {
+    return async (args) => {
+        switch (args.subcommand) {
+            case 'list': return fileGroupList_render(assetName, resourceListBag_build(args.options), args.operands.path);
+            case 'search': return fileGroupList_render(assetName, resourceListBag_build(args.options, args.operands.term), undefined);
+            case 'inspect':
+            case 'fieldslist': return fileGroupFields_render(assetName);
+        }
+    };
+}
+/**
+ * One kind of record's declaration.
+ *
+ * @param assetName - The kind, which names the command.
+ * @param noun - What a record is, for the help.
+ * @returns The declaration.
+ */
+function fileGroupCommand_make(assetName, noun) {
+    return command_declare({
+        name: assetName,
+        grammar: FILE_GROUP_GRAMMAR,
+        help: {
+            summary: `CUBE's ${noun} records: list them, search them, name their fields`,
+            description: `List CUBE's ${noun} records as rows, under a ChRIS path when one is given, a page at a time or every page, filtered by a field:value search and in the columns asked for; inspect names the fields a record has. These are the records themselves; ls lists a folder's contents.`,
+            category: 'Resources',
+            examples: [`${assetName} list`, `${assetName} list ~/uploads --fields fname,fsize`, `${assetName} search fname:dicom`, `${assetName} inspect`],
+        },
+        handler: fileGroupHandler_make(assetName),
+    });
+}
+/** `files <list|search|inspect>`: the declaration. */
+export const filesCommand = fileGroupCommand_make('files', 'file');
+/** `links <list|search|inspect>`: the declaration. */
+export const linksCommand = fileGroupCommand_make('links', 'link');
+/** `dirs <list|search|inspect>`: the declaration. */
+export const dirsCommand = fileGroupCommand_make('dirs', 'folder');
+/**
+ * `files` over words already split: the declaration's parse and handler.
  *
  * @param args - command arguments.
  * @returns An envelope carrying the files listing or fields.
+ *
+ * @example
+ * ```ts
+ * await builtin_files(['list', '/home/chris/uploads']);
+ * ```
  */
 export async function builtin_files(args) {
-    return builtin_fileGroup(args, 'files');
+    return declaredCommand_run(filesCommand, args);
 }
 /**
- * Handles links commands.
+ * `links` over words already split: the declaration's parse and handler.
  *
  * @param args - command arguments.
  * @returns An envelope carrying the links listing or fields.
+ *
+ * @example
+ * ```ts
+ * await builtin_links(['list']);
+ * ```
  */
 export async function builtin_links(args) {
-    return builtin_fileGroup(args, 'links');
+    return declaredCommand_run(linksCommand, args);
 }
 /**
- * Handles dirs commands.
+ * `dirs` over words already split: the declaration's parse and handler.
  *
  * @param args - command arguments.
  * @returns An envelope carrying the dirs listing or fields.
+ *
+ * @example
+ * ```ts
+ * await builtin_dirs(['list']);
+ * ```
  */
 export async function builtin_dirs(args) {
-    return builtin_fileGroup(args, 'dirs');
+    return declaredCommand_run(dirsCommand, args);
 }
 //# sourceMappingURL=files.js.map

package/dist/builtins/res/files.js.map

@@ -1 +1 @@
-{"version":3,"file":"files.js","sourceRoot":"","sources":["../../../src/builtins/res/files.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../../src/builtins/res/files.ts"],"names":[],"mappings":"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"}

package/dist/builtins/res/gather.d.ts

@@ -2,9 +2,119 @@ import { CommandEnvelope } from '@fnndsc/menu';
 import { GATHER_MODEL_KIND } from './gather.kind.js';
 export { GATHER_MODEL_KIND };
 /**
- * Builtin handler for the `gather` command.
+ * `gather [list | add | remove | rm | clear | name | feed | process]`: the declaration.
  *
- * @param args - Parsed command arguments.
- * @returns An envelope carrying the cohort, or a usage refusal.
+ * @example
+ * ```ts
+ * commands_register({ declarations: [gatherCommand] }, 'backend');
+ * ```
+ */
+export declare const gatherCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly bare: {
+        readonly summary: "Show the cohort (as list)";
+    };
+    readonly subcommands: {
+        readonly list: {
+            readonly summary: "Show the cohort";
+        };
+        readonly add: {
+            readonly summary: "Take series, directories or files into it";
+            readonly operands: readonly [{
+                readonly name: "paths";
+                readonly kind: "cfsPath";
+                readonly optional: true;
+                readonly repeat: true;
+                readonly glob: true;
+                readonly summary: "Paths, handles (@SER3, @SER1-4) or ${listing}; with none, a listing piped in";
+            }];
+        };
+        readonly remove: {
+            readonly summary: "Drop members, by path or by listed index";
+            readonly operands: readonly [{
+                readonly name: "members";
+                readonly kind: "cfsPath";
+                readonly optional: true;
+                readonly repeat: true;
+                readonly glob: true;
+                readonly summary: "Paths, handles or listed indices (2, #2); with none, a listing piped in";
+            }];
+        };
+        readonly rm: {
+            readonly summary: "As remove";
+            readonly operands: readonly [{
+                readonly name: "members";
+                readonly kind: "cfsPath";
+                readonly optional: true;
+                readonly repeat: true;
+                readonly glob: true;
+                readonly summary: "Paths, handles or listed indices (2, #2); with none, a listing piped in";
+            }];
+        };
+        readonly clear: {
+            readonly summary: "Empty it, name and feed included";
+        };
+        readonly name: {
+            readonly summary: "Read the cohort's name, or give it one";
+            readonly operands: readonly [{
+                readonly name: "name";
+                readonly kind: "word";
+                readonly optional: true;
+                readonly repeat: true;
+                readonly summary: "The new name; its words are joined";
+            }];
+        };
+        readonly feed: {
+            readonly summary: "The cohort's feed, made now if it has none: series still at the PACS are pulled first, then one feed is rooted on every member";
+            readonly options: {
+                readonly title: {
+                    readonly long: "title";
+                    readonly summary: "The feed's title, when one is made (the cohort's name otherwise)";
+                    readonly value: {
+                        readonly name: "title";
+                        readonly kind: "word";
+                    };
+                };
+            };
+        };
+        readonly process: {
+            readonly summary: "Run a plugin or pipeline ONCE over the whole cohort, off one feed whose root holds every member";
+            readonly operands: readonly [{
+                readonly name: "executable";
+                readonly kind: "word";
+                readonly summary: "The plugin's /bin name or the pipeline's own name";
+            }, {
+                readonly name: "arguments";
+                readonly kind: "word";
+                readonly optional: true;
+                readonly repeat: true;
+                readonly summary: "After --: the run's own arguments";
+            }];
+            readonly options: {
+                readonly title: {
+                    readonly long: "title";
+                    readonly summary: "The feed's title, when one is made (the cohort's name otherwise)";
+                    readonly value: {
+                        readonly name: "title";
+                        readonly kind: "word";
+                    };
+                };
+                readonly detach: {
+                    readonly long: "detach";
+                    readonly summary: "Return at once rather than wait for the run";
+                };
+            };
+        };
+    };
+}>;
+/**
+ * `gather` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `gather`.
+ * @returns An envelope carrying the cohort, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_gather(['add', '~/uploads/brain']);
+ * ```
  */
 export declare function builtin_gather(args: string[]): Promise<CommandEnvelope>;

package/dist/builtins/res/gather.js

@@ -2,6 +2,7 @@
  * @file Builtin gather command: the session's cohort as a kernel subject.
  *
  * Subcommands: list (the default), add, remove, clear, name, feed, process.
+ * Declared in one record (`gatherCommand`).
  *
  * Gathering was a surface gesture before it was a verb, which meant the set
  * a session was working on could only be built by pressing on it. As a
@@ -9,6 +10,18 @@
  * the surface becomes one client of the cohort rather than the only place
  * it exists.
  *
+ * Key components:
+ * - gatherCommand: the declaration.
+ * - builtin_gather: the declaration run over words already split.
+ *
+ * Typical usage:
+ * ```ts
+ * await builtin_gather(['add', '@SER3']);
+ * ```
+ *
+ * Dependencies: the cohort store; `gather.process.js`, loaded when a feed is
+ * made or a run starts.
+ *
  * @module
  */
 import { listingIn_take, listingOperands_extract } from '../../core/listing.js';
@@ -16,7 +29,9 @@ import { answerNumbering_derive, handleWords_map, numberedFooter_render } from '
 import chalk from 'chalk';
 import path from 'path';
 import { table_render } from '@fnndsc/chili/screen/screen.js';
-import { commandArgs_process, path_resolve } from '../utils.js';
+import { path_resolve } from '../utils.js';
+import { command_declare } from '../../core/commandDeclaration.js';
+import { declaredCommand_run } from '../../core/commandParse.js';
 import { cohort_read, cohort_write, cohortModel_wrap, cohortFolders_fill, member_key, members_drop, members_merge, pathKind_determine, seriesUID_parse, } from './gather.store.js';
 import { placeImagery_is, seriesFacts_fill } from './gather.facts.js';
 import { envelope_ok, envelope_error } from '@fnndsc/menu';
@@ -217,14 +232,14 @@ async function gather_name(operands) {
 /**
  * Makes the cohort's feed, or names the one it has.
  *
- * @param words - The words after `gather feed`, raw.
+ * @param title - The feed's title as `--title` gave it, or null for the cohort's name.
  * @returns The cohort, with its feed.
  */
-async function gather_feed(words) {
+async function gather_feed(title) {
     // Loaded on demand, as `process` is: making a feed carries the pull and
     // feed machinery, which the cohort's own verbs never need.
     const { cohortFeed_make } = await import('./gather.process.js');
-    const made = await cohortFeed_make(words);
+    const made = await cohortFeed_make(title);
     if (typeof made === 'string')
         return gather_error(`gather feed: ${made}`);
     const feedId = made.state.feed?.feedId;
@@ -232,53 +247,147 @@ async function gather_feed(words) {
     const envelope = cohort_render(made.state);
     return envelope_ok(`${chalk.green(said)}\n${envelope.rendered}`, envelope.model);
 }
+/** What `add` takes. */
+const ADD_OPERAND = {
+    name: 'paths', kind: 'cfsPath', optional: true, repeat: true, glob: true,
+    summary: 'Paths, handles (@SER3, @SER1-4) or ${listing}; with none, a listing piped in',
+};
+/** What `remove` and `rm` take. */
+const REMOVE_OPERAND = {
+    name: 'members', kind: 'cfsPath', optional: true, repeat: true, glob: true,
+    summary: 'Paths, handles or listed indices (2, #2); with none, a listing piped in',
+};
+/** The title of a feed `feed` or `process` makes. */
+const TITLE_OPTION = { long: 'title', summary: "The feed's title, when one is made (the cohort's name otherwise)", value: { name: 'title', kind: 'word' } };
+/** What a `gather` line may hold. */
+const GATHER_GRAMMAR = {
+    bare: { summary: 'Show the cohort (as list)' },
+    subcommands: {
+        list: { summary: 'Show the cohort' },
+        add: { summary: 'Take series, directories or files into it', operands: [ADD_OPERAND] },
+        remove: { summary: 'Drop members, by path or by listed index', operands: [REMOVE_OPERAND] },
+        rm: { summary: 'As remove', operands: [REMOVE_OPERAND] },
+        clear: { summary: 'Empty it, name and feed included' },
+        name: {
+            summary: "Read the cohort's name, or give it one",
+            operands: [{ name: 'name', kind: 'word', optional: true, repeat: true, summary: 'The new name; its words are joined' }],
+        },
+        feed: {
+            summary: "The cohort's feed, made now if it has none: series still at the PACS are pulled first, then one feed is rooted on every member",
+            options: { title: TITLE_OPTION },
+        },
+        process: {
+            summary: 'Run a plugin or pipeline ONCE over the whole cohort, off one feed whose root holds every member',
+            operands: [
+                { name: 'executable', kind: 'word', summary: "The plugin's /bin name or the pipeline's own name" },
+                { name: 'arguments', kind: 'word', optional: true, repeat: true, summary: "After --: the run's own arguments" },
+            ],
+            options: {
+                title: TITLE_OPTION,
+                detach: { long: 'detach', summary: 'Return at once rather than wait for the run' },
+            },
+        },
+    },
+};
 /**
- * Builtin handler for the `gather` command.
+ * `gather [list | add | remove | rm | clear | name | feed | process]`: the declaration.
  *
- * @param args - Parsed command arguments.
- * @returns An envelope carrying the cohort, or a usage refusal.
+ * @example
+ * ```ts
+ * commands_register({ declarations: [gatherCommand] }, 'backend');
+ * ```
  */
-export async function builtin_gather(args) {
-    const parsed = commandArgs_process(args);
-    const subcommand = parsed._[0];
-    const operands = parsed._.slice(1);
-    try {
-        if (subcommand === undefined || subcommand === 'list')
-            return cohort_render(await cohort_read());
-        if (subcommand === 'add' || subcommand === 'remove' || subcommand === 'rm') {
-            // With no operands, a listing piped in is the operand list (#1103):
-            // `query … | gather add`. With neither, the verb says what it needs
-            // rather than taking the held listing behind the operator's back.
-            let given = operands;
-            if (given.length === 0) {
-                const piped = listingIn_take();
-                if (piped === null) {
-                    return gather_error(`gather ${subcommand}: what? give paths or handles (@SER3), \${listing}, or pipe a listing in (query … | gather ${subcommand === 'rm' ? 'remove' : subcommand})`);
+export const gatherCommand = command_declare({
+    name: 'gather',
+    grammar: GATHER_GRAMMAR,
+    help: {
+        summary: 'Hold the set of things this session is working on',
+        description: "Hold the set of things this session is working on: the cohort. add and remove take paths, handles (@SER3, @SER1-4), ${listing}, or a listing piped in with no operands: query … | gather add. With none of these they refuse rather than guess. process runs off the cohort's own feed when it has one, refuses while a series is unpulled, and answers as the bare run would: R=$(gather process …). <executable> is the /bin name or the pipeline's own name: gather process \"FreeSurfer 8.2.0 mri_convert\". A plugin that starts jobs of its own (pl-dymap) finishes once they are submitted; watch them in the feed.",
+        category: 'Workflows',
+        examples: [
+            'gather',
+            'gather add /net/pacs/queries/qid:3125/Study_1.2.3/Series_4.5.6',
+            'gather add ~/uploads/brain',
+            'gather add @SER3 @SER7',
+            'query PatientID:1234567,Modality:MR | gather add',
+            'gather remove 2',
+            'gather name "sag cohort"',
+            'gather feed',
+            'R=$(gather process pl-dcm2niix-v1.0.2 --title "sag nifti")',
+            'gather process pl-x -- --threshold 0.5',
+        ],
+    },
+    holds: ['cohort'],
+    handler: async (args) => {
+        try {
+            switch (args.subcommand) {
+                case null:
+                case 'list':
+                    return cohort_render(await cohort_read());
+                case 'add':
+                    return await gatherMembers_change('add', args.operands.paths);
+                case 'remove':
+                case 'rm':
+                    return await gatherMembers_change(args.subcommand, args.operands.members);
+                case 'clear':
+                    return await gather_clear();
+                case 'name':
+                    return await gather_name(args.operands.name);
+                case 'feed':
+                    return await gather_feed(args.options.title ?? null);
+                case 'process': {
+                    // Loaded on demand: running carries the plugin and pipeline
+                    // machinery, which the cohort's own verbs never need.
+                    const { gather_process } = await import('./gather.process.js');
+                    return await gather_process({
+                        name: args.operands.executable,
+                        title: args.options.title ?? null,
+                        detach: args.options.detach,
+                        forwarded: args.operands.arguments,
+                    });
                 }
-                given = listingOperands_extract(piped) ?? [];
-                if (given.length === 0)
-                    return gather_error(`gather ${subcommand}: the listing piped in has nothing to ${subcommand === 'add' ? 'gather' : 'remove'}.`);
             }
-            return subcommand === 'add' ? await gather_add(given) : await gather_remove(given);
         }
-        if (subcommand === 'clear')
-            return await gather_clear();
-        // Raw words: the run's own arguments follow `--`, and a generic parser
-        // would read them as gather's options.
-        // Loaded on demand: running carries the plugin and pipeline machinery,
-        // which the cohort's own verbs never need.
-        if (subcommand === 'process') {
-            const { gather_process } = await import('./gather.process.js');
-            return await gather_process(args.slice(args.indexOf('process') + 1));
+        catch (e) {
+            return gather_error(`gather: ${e instanceof Error ? e.message : String(e)}`);
         }
-        if (subcommand === 'name')
-            return await gather_name(operands);
-        if (subcommand === 'feed')
-            return await gather_feed(args.slice(args.indexOf('feed') + 1));
-    }
-    catch (e) {
-        return gather_error(`gather: ${e instanceof Error ? e.message : String(e)}`);
+    },
+});
+/**
+ * `gather` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `gather`.
+ * @returns An envelope carrying the cohort, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_gather(['add', '~/uploads/brain']);
+ * ```
+ */
+export async function builtin_gather(args) {
+    return declaredCommand_run(gatherCommand, args);
+}
+/**
+ * Adds members to the cohort or drops them. With no operands, a listing
+ * piped in is the operand list (#1103): `query … | gather add`. With
+ * neither, the verb says what it needs rather than taking the held listing
+ * behind the operator's back.
+ *
+ * @param verb - `add`, `remove` or `rm`.
+ * @param operands - The paths, handles or indices given.
+ * @returns The cohort after the change, or a refusal.
+ */
+async function gatherMembers_change(verb, operands) {
+    let given = operands;
+    if (given.length === 0) {
+        const piped = listingIn_take();
+        if (piped === null) {
+            return gather_error(`gather ${verb}: what? give paths or handles (@SER3), \${listing}, or pipe a listing in (query … | gather ${verb === 'rm' ? 'remove' : verb})`);
+        }
+        given = listingOperands_extract(piped) ?? [];
+        if (given.length === 0)
+            return gather_error(`gather ${verb}: the listing piped in has nothing to ${verb === 'add' ? 'gather' : 'remove'}.`);
     }
-    return gather_error(`Unknown subcommand: ${subcommand}. Usage: gather <list|add|remove|clear|name|feed|process>`);
+    return verb === 'add' ? await gather_add(given) : await gather_remove(given);
 }
 //# sourceMappingURL=gather.js.map