{"content":"# aux4/2table\n\nConvert a JSON array of objects to a human-readable table (ASCII or Markdown) or to CSV.\n\nA lightweight aux4 package that reads a JSON array from stdin and prints a table. Use it to inspect JSON data quickly in a terminal, generate Markdown tables for documentation, or emit CSV for machine consumption.\n\n## Installation\n\n``bash\naux4 aux4 pkger install aux4/2table\n`\n\n## Quick Start\n\nPipe a JSON array to the command and specify the columns you want to display.\n\n`bash\ncat data.json | aux4 2table name,age,city\n`\n\nProduce Markdown output with --format:\n\n`bash\ncat data.json | aux4 2table --format md name,age,city\n`\n\nProduce CSV output for machine consumption:\n\n`bash\ncat data.json | aux4 2table --format csv name,age,city\n`\n\n## Usage\n\nThis package converts JSON arrays into table output. You can select simple fields, expand nested objects and arrays, rename columns, and set fixed column widths for wrapping.\n\n### Main Commands\n\n- [aux4 2table](./commands/aux4/2table) - Convert a JSON array of objects to a table format.\n\n### Command Reference\n\nCommand: aux4 2table\n\nVariables (defined in the package):\n\n- --format\n - Description: Table output format\n - Options: ascii (default), md, csv\n- table (positional)\n - Description: The table structure to output (column list)\n - Examples: name,age,city, name,age,address[street,city], name:\"Full Name\",age:Age\n- --lineNumbers\n - Description: Add a first column with line numbers starting from 1\n - Options: true, false (default)\n- --showInvalidLines\n - Description: Show invalid lines as <invalid line> instead of skipping them\n - Options: true, false (default)\n\nTable expression features\n\n- Simple columns: name,age,city\n- Nested objects: address[street,city]\n- Arrays of objects: contacts[name,email]\n- Column renaming: name:\"Full Name\",age:Age\n- Fixed width with wrapping: name{width:8},description{width:20}\n- Value formatting: amount{format:currency,currency:USD},rate{format:percent}\n\nInput: JSON array provided via stdin.\n\n## Examples\n\nAll examples use the full package invocation aux4 2table (recommended for clarity).\n\n### ASCII table (default)\n\nInput (data.json):\n\n`json\n[\n { \"name\": \"Alice\", \"age\": 30, \"city\": \"New York\" },\n { \"name\": \"Bob\", \"age\": 25, \"city\": \"Los Angeles\" },\n { \"name\": \"Charlie\", \"age\": 35, \"city\": \"Chicago\" }\n]\n`\n\nCommand:\n\n`bash\ncat data.json | aux4 2table name,age,city\n`\n\nOutput:\n\n`text\n name age city\n Alice 30 New York\n Bob 25 Los Angeles\n Charlie 35 Chicago\n`\n\n### Markdown table (--format md)\n\nCommand:\n\n`bash\ncat data.json | aux4 2table --format md name,age,city\n`\n\nOutput:\n\n`text\n| name | age | city |\n| --- | --- | --- |\n| Alice | 30 | New York |\n| Bob | 25 | Los Angeles |\n| Charlie | 35 | Chicago |\n`\n\n### CSV output (--format csv)\n\nCSV is intended for machine consumption: colors and column widths are ignored, values are comma-separated, and fields are quoted per RFC 4180 (a field is wrapped in double quotes when it contains a comma, double quote, carriage return or newline; embedded double quotes are doubled).\n\nCommand:\n\n`bash\ncat data.json | aux4 2table --format csv name,age,city\n`\n\nOutput:\n\n`text\nname,age,city\nAlice,30,New York\nBob,25,Los Angeles\nCharlie,35,Chicago\n`\n\nNested/hierarchical structures have no colspan in CSV, so headers are flattened to a single row using dot notation (address[street,city] becomes the columns address.street and address.city):\n\n`bash\ncat nested.json | aux4 2table --format csv name,address[street,city]\n`\n\n`text\nname,address.street,address.city\nJohn,123 Main St,NYC\nJane,456 Oak Ave,SF\n`\n\n### Nested objects\n\nInput (nested.json):\n\n`json\n[\n {\n \"name\": \"John\",\n \"age\": 30,\n \"address\": { \"street\": \"123 Main St\", \"city\": \"NYC\", \"state\": \"NY\", \"zipCode\": \"10001\" }\n },\n { \"name\": \"Jane\", \"age\": 25, \"address\": { \"street\": \"456 Oak Ave\", \"city\": \"SF\", \"state\": \"CA\", \"zipCode\": \"94102\" } }\n]\n`\n\nCommand:\n\n`bash\ncat nested.json | aux4 2table name,age,address[street,city,state,zipCode]\n`\n\nThis produces multi-row headers for the nested address fields and prints each address row beneath the parent record.\n\n### Renaming columns\n\nUse colon syntax to rename columns in the output:\n\n`bash\ncat people.json | aux4 2table name:\"Full Name\",age:\"Years Old\",contact:\"Contact Info\"[email:\"Email Address\",phone:\"Phone Number\"]\n`\n\n### Fixed width and wrapping\n\nSet a width for long text fields to enable wrapping in ASCII output:\n\n`bash\ncat long-text.json | aux4 2table 'name{width:8},description{width:20}'\n`\n\n### Value formatting\n\nUse the {format:...} column modifier to render raw values as numbers, currency, percentages, dates, times or datetimes. Formatting is applied before rendering, so it is consistent across ASCII, Markdown and CSV output. All formats are Intl-based.\n\n| Format | Option keys | Notes |\n| --- | --- | --- |\n| number | decimals, locale | Thousands grouping is on by default. |\n| currency | currency (ISO code, default USD), decimals, locale | |\n| percent | decimals, locale | The value is treated as a ratio (0.25 renders as 25%). |\n| date | style (short\\|medium\\|long\\|full, default medium), dateStyle (override), locale | |\n| time | style (short\\|medium\\|long\\|full, default medium), timeStyle (override), locale | |\n| datetime | style (sets both parts), dateStyle (override, default medium), timeStyle (override, default short), locale | |\n\nMultiple options are comma-separated inside the braces. locale defaults to the host locale (falling back to en-US).\n\n**Temporal style:** the unified style key sets the presentation for temporal formats — the dateStyle for date, the timeStyle for time, and BOTH parts for datetime. The fine-grained dateStyle / timeStyle keys remain available as per-part overrides. Precedence per part is: explicit dateStyle/timeStyle > style > built-in default. For example, ts{format:datetime,style:medium,timeStyle:short} renders the date part medium and the time part short.\n\n`bash\necho '[{\"amount\":1234.5,\"qty\":3,\"rate\":0.1234,\"born\":\"1990-05-01\",\"ts\":\"2026-07-20T14:30:00Z\"}]' \\\n | aux4 2table 'amount{format:currency,currency:USD},qty{format:number,decimals:0},rate{format:percent,decimals:1},born{format:date},ts{format:datetime}'\n`\n\nOutput:\n\n`text\n amount qty rate born ts\n $1,234.50 3 12.3% May 1, 1990 Jul 20, 2026, 2:30 PM\n`\n\n**Note:** number, currency and percent columns right-align automatically (an explicit align: always wins). Empty values render as an empty cell, and an un-parseable date or a non-numeric value given a numeric format falls back to the original raw value.\n\n### Auto-structure generation\n\nWhen no structure is provided, the command automatically analyzes the JSON to generate an optimal table structure:\n\n`bash\ncat complex-data.json | aux4 2table\n`\n\nThis automatically detects nested objects and arrays, creating appropriate column groupings.\n\n### Line numbers and invalid data handling\n\nAdd line numbers for data debugging and control how invalid JSON lines are handled:\n\n`bash\ncat data.json | aux4 2table name,age,city --lineNumbers true --showInvalidLines true\n`\n\nOutput:\n`text\n # name age city\n 1 Alice 30 New York\n 2 <invalid line>\n 3 Charlie 35 Chicago\n`\n\n### Dot notation for nested properties\n\nAccess nested object properties using dot notation:\n\n`bash\ncat nested.json | aux4 2table name,age,address.city,address.state\n`\n\n### Complex nested structures\n\nHandle deeply nested objects and arrays with mixed object types:\n\n`bash\ncat mixed-objects.json | aux4 2table 'type,data[logs[level,message],metrics[cpu,memory,disk]]'\n`\n\nThis creates multi-level headers and handles objects that contain both arrays and nested objects.\n\n## Examples from tests\n\nThe repository includes full example runs in the test/ folder. Reproduce them locally:\n\n- ASCII examples: test/ascii.test.md\n- Markdown examples: test/markdown.test.md\n- CSV examples: test/csv.test.md`\n\nEach test file contains sample input files, the exact command to run, and expected output blocks.\n\n## License\n\nThis package is licensed under the Apache-2.0 License.\n\n\n"}