ecommon-sh
Shared shell library for Entrez Direct wrappers. This file defines functions and global variables for argument parsing, retry logic, logging, and ENTREZ_DIRECT envelope handling. It is not a normal end-user CLI.
Quick Start
- Command:
source /home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh
- Local file:
/home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh
- Observed library version when sourced:
24.0
When To Use This Tool
- Inspect the common behavior inherited by EDirect wrappers such as
ecollect.
- Reuse shared shell functions like
ParseCommonArgs, FinishSetup, RunWithLogging, and WriteEDirect in your own wrappers.
- Understand how EDirect normalizes flags, retries failed EUtils requests, and serializes ENTREZ_DIRECT metadata.
- Debug why multiple EDirect shell scripts share the same option handling, logging, or error-reporting behavior.
Common Patterns
# 1) Source the library and inspect its version variable
source /home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh
printf '%s\n' "$version"
# 2) Minimal wrapper skeleton that reuses common flag parsing and setup
#!/usr/bin/env bash
source /home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh
ParseCommonArgs "$@"
shift "$argsConsumed"
FinishSetup
RunWithLogging nquire -url "$base" einfo.fcgi -db pubmed
# 3) Emit an ENTREZ_DIRECT envelope after a wrapper finishes
source /home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh
WriteEDirect "pubmed" "$web_env" "$qry_key" "$num" "$stp" ""
Recommended Workflow
- Treat
ecommon.sh as a library file and source it into a shell or wrapper script instead of executing it directly.
- Call
ParseCommonArgs "$@" first if you want the standard EDirect flags and remember to shift "$argsConsumed" before handling tool-specific options.
- Run
FinishSetup before network work so base URL, API key, email, and related globals are initialized consistently.
- Reuse
RunWithLogging / retry helpers and WriteEDirect rather than reimplementing that behavior piecemeal.
Guardrails
- Running
bash ecommon.sh or bash ecommon.sh -version is silently unhelpful in this environment: both paths exit with no useful output.
- The
24.0 version string is visible only after sourcing the file or through sibling wrappers that expose it.
- This library relies on mutable global state (
db, input, web_env, qry_key, verbose, tranquil, and others). Source it into a clean shell context or isolate your wrapper logic carefully.
- Many helper functions eventually invoke sibling EDirect tools such as
xtract, transmute, and nquire; sourcing the file does not guarantee those commands are on PATH.
- Autogenerated docs that treat
ecommon.sh as a standalone command are misleading. The meaningful interface here is its function set, not its direct process invocation.
1---2name: ecommon-sh3description: Use when auditing or reusing the shared EDirect shell functions that other Entrez Direct wrapper scripts source internally.4---5
6# ecommon-sh
7
8Shared shell library for Entrez Direct wrappers. This file defines functions and global variables for argument parsing, retry logic, logging, and ENTREZ_DIRECT envelope handling. It is not a normal end-user CLI.
9
10## Quick Start
11
12- **Command:** `source /home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh`
13- **Local file:** `/home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh`
14- **Observed library version when sourced:** `24.0`
15
16## When To Use This Tool
17
18- Inspect the common behavior inherited by EDirect wrappers such as `ecollect`.
19- Reuse shared shell functions like `ParseCommonArgs`, `FinishSetup`, `RunWithLogging`, and `WriteEDirect` in your own wrappers.
20- Understand how EDirect normalizes flags, retries failed EUtils requests, and serializes ENTREZ_DIRECT metadata.
21- Debug why multiple EDirect shell scripts share the same option handling, logging, or error-reporting behavior.
22
23## Common Patterns
24
25```bash
26# 1) Source the library and inspect its version variable
27source /home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh
28printf '%s\n' "$version"
29```
30
31```bash
32# 2) Minimal wrapper skeleton that reuses common flag parsing and setup
33#!/usr/bin/env bash
34source /home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh
35
36ParseCommonArgs "$@"
37shift "$argsConsumed"
38FinishSetup
39
40RunWithLogging nquire -url "$base" einfo.fcgi -db pubmed
41```
42
43```bash
44# 3) Emit an ENTREZ_DIRECT envelope after a wrapper finishes
45source /home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh
46WriteEDirect "pubmed" "$web_env" "$qry_key" "$num" "$stp" ""
47```
48
49## Recommended Workflow
50
511. Treat `ecommon.sh` as a library file and source it into a shell or wrapper script instead of executing it directly.
522. Call `ParseCommonArgs "$@"` first if you want the standard EDirect flags and remember to `shift "$argsConsumed"` before handling tool-specific options.
533. Run `FinishSetup` before network work so base URL, API key, email, and related globals are initialized consistently.
544. Reuse `RunWithLogging` / retry helpers and `WriteEDirect` rather than reimplementing that behavior piecemeal.
55
56## Guardrails
57
58- Running `bash ecommon.sh` or `bash ecommon.sh -version` is silently unhelpful in this environment: both paths exit with no useful output.
59- The `24.0` version string is visible only after sourcing the file or through sibling wrappers that expose it.
60- This library relies on mutable global state (`db`, `input`, `web_env`, `qry_key`, `verbose`, `tranquil`, and others). Source it into a clean shell context or isolate your wrapper logic carefully.
61- Many helper functions eventually invoke sibling EDirect tools such as `xtract`, `transmute`, and `nquire`; sourcing the file does not guarantee those commands are on `PATH`.
62- Autogenerated docs that treat `ecommon.sh` as a standalone command are misleading. The meaningful interface here is its function set, not its direct process invocation.
vimalinx