{"id":34056772,"url":"https://github.com/veridock/xqr","last_synced_at":"2026-04-01T19:12:35.437Z","repository":{"id":301852089,"uuid":"1010486218","full_name":"veridock/xqr","owner":"veridock","description":"xpath xquery xqr","archived":false,"fork":false,"pushed_at":"2025-06-29T16:51:03.000Z","size":271,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-03T07:42:54.821Z","etag":null,"topics":["svg","xls","xlst","xml","xpath","xquery"],"latest_commit_sha":null,"homepage":"https://veridock.github.io/xqr/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/veridock.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-29T07:06:31.000Z","updated_at":"2025-06-29T16:51:07.000Z","dependencies_parsed_at":"2025-06-29T07:48:40.777Z","dependency_job_id":"38222765-6427-47b0-8dc4-e6c4a28dc613","html_url":"https://github.com/veridock/xqr","commit_stats":null,"previous_names":["veridock/xqr"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/veridock/xqr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veridock%2Fxqr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veridock%2Fxqr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veridock%2Fxqr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veridock%2Fxqr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/veridock","download_url":"https://codeload.github.com/veridock/xqr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veridock%2Fxqr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31029904,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-27T06:08:13.374Z","status":"ssl_error","status_checked_at":"2026-03-27T06:08:07.217Z","response_time":164,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["svg","xls","xlst","xml","xpath","xquery"],"created_at":"2025-12-14T03:03:30.453Z","updated_at":"2026-04-01T19:12:35.403Z","avatar_url":"https://github.com/veridock.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛠️ XQR - XPath Query \u0026 Replace\n\n[![PyPI](https://img.shields.io/pypi/v/xqr)](https://pypi.org/project/xqr/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python Version](https://img.shields.io/pypi/pyversions/xqr)](https://pypi.org/project/xqr/)\n\nXQR is a powerful command-line tool for editing and converting structured documents (SVG, HTML, XML) using XPath and CSS selectors. It's designed for developers, data engineers, and designers who need to manipulate structured data efficiently.\n\n## ✨ Features\n\n- **Universal Document Editor**: Edit SVG, HTML, and XML files with XPath/CSS selectors\n- **PDF to SVG Conversion**: Convert PDFs to SVG with embedded metadata and text extraction\n- **SVG to PDF/Image**: Convert SVGs to PDF, PNG, and JPG formats\n- **Batch Processing**: Process multiple files with a single command\n- **REST API**: Built-in web server for programmatic access\n- **Cross-Platform**: Works on Linux, macOS, and Windows\n\n## 🚀 Quick Start\n\n### Installation\n\nSee the [Installation Guide](docs/INSTALLATION.md) for complete setup instructions.\n\n```bash\n# Basic installation with pip\npip install xqr\n```\n\n### Basic Usage\n\nCheck out the [Examples](docs/EXAMPLES.md) for comprehensive usage patterns.\n\n```bash\n# Query elements with XPath\nxqr query document.html \"//h1\"\n\n# Update content\nxqr set document.html \"//title\" \"New Title\"\n\n# Convert between formats\nxqr convert input.pdf output.svg\n```\n\n## 📚 Documentation\n\nFor detailed documentation, please visit our [documentation website](https://veridock.github.io/xqr/) or check the following resources:\n\n- [Installation Guide](docs/INSTALLATION.md) - Complete setup instructions\n- [PDF to SVG Workflow](docs/WORKFLOW_PDF_TO_SVG.md) - Working with PDF files\n- [SVG to PDF/Image](docs/WORKFLOW_SVG_TO_PDF.md) - Converting SVG files\n- [API Reference](docs/API.md) - Detailed API documentation\n- [Examples](docs/EXAMPLES.md) - Practical usage examples\n- [Troubleshooting](docs/TROUBLESHOOTING.md) - Solutions to common issues\n\n## 💡 Features in Detail\n\n### Document Editing\n- XPath 1.0 and CSS selector support\n- Batch processing of multiple files\n- Automatic backup system\n- Interactive shell for complex operations\n\n### PDF to SVG Conversion\n- Extract text and metadata\n- Handle password-protected PDFs\n- Custom DPI settings for OCR\n- Multiple output formats (SVG, HTML, JSON)\n\n### SVG Processing\n- Convert to PDF, PNG, and JPG\n- Handle embedded resources\n- Advanced image processing options\n- Batch conversion tools\n\n## 🤝 Contributing\n\nContributions are welcome! Please read our [Contributing Guide](docs/CONTRIBUTING.md) for details on how to contribute to this project.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Getting Help\n\nHaving trouble with XQR? Check out our [Troubleshooting Guide](docs/TROUBLESHOOTING.md) or [open an issue](https://github.com/veridock/xqr/issues) if you can't find what you need.\n\nYou can run the XQR CLI in several ways depending on your setup:\n\n#### From Poetry (recommended for development):\n```bash\n# Run a single command\npoetry run xqr --help\n\n# Or activate the environment first\npoetry shell\nxqr --help\n```\n\n#### From virtual environment:\n```bash\n# Activate your virtual environment first\nsource /path/to/venv/bin/activate\n\n# Then run xqr\nxqr --help\n```\n\n#### Using Python module syntax (works without installation):\n```bash\npython -m xqr.cli --help\n```\n\n#### Install globally (not recommended for development):\n```bash\n# Install in development mode\npip install -e .\n\n# Or install from PyPI\npip install xqr\n\n# Then run from anywhere\nxqr --help\n```\n\n### 1. Create Example Files\n```bash\nxqr examples\n```\n\n### 2. Basic Usage - Standard Commands\n```bash\n# Load and query a file\nxqr load example.svg\nxqr query \"//text[@id='text1']\"\n\n# Update content\nxqr set \"//text[@id='text1']\" \"New Content\"\nxqr save\n\n# The file remains loaded between commands\nxqr query \"//text[@id='text2']\"  # Works without reloading\n\n# To load a different file\nxqr load other_file.xml\n```\n\n### 3. Concise File/XPath Operations\nFor quick operations, you can directly specify the file and XPath in one command:\n\n```bash\nxqr example.svg//svg\n\n# Read element content\nxqr example.svg//text[@id='text1']\n\n# Update element content\nxqr example.svg//text[@id='text1'] \"New Value\"\n\n# Delete element content (set to empty string)\nxqr example.svg//text[@id='text1'] \"\"\n\n# Read from XML/HTML files\nxqr config.xml//setting[@name='timeout']\nxqr index.html//title \"New Page Title\"\n\n# This syntax is especially useful for one-off operations and scripts.\n```\n\n### 4. Interactive Shell\n```bash\nxqr shell\n📝 \u003e load example.html\n📝 \u003e query //title\n📝 \u003e set //title \"Updated Title\"\n📝 \u003e save\n📝 \u003e exit\n\n# The shell maintains state between commands automatically\n```\n\n### 5. Web Interface\n```bash\nxqr server --port 8080\n# Open http://localhost:8080 in your browser\n\n# The web interface shares the same state as the CLI\n# Any file loaded in the web interface will be available to the CLI and vice versa\n```\n\n## 🔄 State Persistence\n\nXQR maintains state between commands, making it easy to work with files across multiple operations:\n\n```bash\n# Load a file (state is saved to ~/.local/state/xqr/state.json)\nxqr load example.svg\n\n# The file remains loaded for subsequent commands\nxqr query \"//title\"\nxqr set \"//version\" \"2.0\"\nxqr save\n\n# The state persists even if you close the terminal\n# Next time you run xqr, it will remember the last loaded file\nxqr query \"//title\"  # Still works with the last loaded file\n\n# To clear the state or load a different file\nxqr load different_file.html\n```\n\n### State Management\n- State is stored in `~/.local/state/xqr/state.json`\n- The state includes the path to the last loaded file\n- If the file is moved or deleted, XQR will prompt you to load a new file\n\n## 📖 Usage Examples\n\n### SVG Files - Update Charts \u0026 Graphics\n```bash\n# Update chart title\nxqr set \"//text[@id='title']\" \"Q4 Sales Results\"\n\n# Change visualization colors\nxqr set \"//rect[@id='bar1']\" \"blue\" --type attribute --attr fill\n\n# Update metadata for better organization\nxqr set \"//metadata/description\" \"Updated quarterly sales chart\"\n\n# Batch update multiple SVG files\nfor file in charts/*.svg; do\n    xqr load \"$file\"\n    xqr set \"//metadata/updated\" \"$(date)\"\n    xqr save\ndone\n```\n\n### HTML Files - Content Management\n```bash\n# Update page titles across multiple pages\nxqr set \"//title\" \"New Site Title\"\n\n# Change meta descriptions for SEO\nxqr set \"//meta[@name='description']\" \"Updated SEO description\" --type attribute --attr content\n\n# Update navigation links\nxqr set \"//nav//a[@href='/old-page']\" \"/new-page\" --type attribute --attr href\n\n# CSS selector support in shell mode\nxqr shell\n📝 \u003e load index.html\n📝 \u003e query #main-heading\n📝 \u003e set #main-heading \"Welcome to Our New Site\"\n```\n\n### XML Data Files - Configuration \u0026 Data\n```bash\n# Update configuration values\nxqr set \"//config/timeout\" \"60\" --type attribute --attr value\n\n# Modify data records\nxqr set \"//record[@id='1']/email\" \"newemail@example.com\"\n\n# Update version information\nxqr set \"//metadata/version\" \"2.0\"\n\n# Batch configuration updates\nfind /etc/configs -name \"*.xml\" -exec xqr load {} \\; \\\n    -exec xqr set \"//config/debug\" \"false\" \\; \\\n    -exec xqr save {} \\;\n```\n\n## 🔧 Advanced Features\n\n### Batch Processing Scripts\n```bash\n#!/bin/bash\n# Update copyright year across all HTML files\nfor file in **/*.html; do\n    echo \"Processing $file...\"\n    xqr load \"$file\"\n    xqr set \"//span[@class='copyright-year']\" \"2025\"\n    xqr save\ndone\n\n# Update SVG chart data\n#!/bin/bash\n# Replace old data with new values\nfor chart in reports/*.svg; do\n    xqr load \"$chart\"\n    xqr set \"//metadata/data-source\" \"Q1-2025-data.json\"\n    xqr set \"//text[@class='last-updated']\" \"$(date '+%Y-%m-%d')\"\n    xqr save\ndone\n```\n\n### REST API Integration\n```bash\n# Start server\nxqr server --port 8080\n\n# Load file via API\ncurl -X POST http://localhost:8080/api/load \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"file_path\": \"dashboard.svg\"}'\n\n# Query elements\ncurl -X POST http://localhost:8080/api/query \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"//text[@class=\\\"metric-value\\\"]\", \"type\": \"xpath\"}'\n\n# Update values\ncurl -X POST http://localhost:8080/api/update \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"xpath\": \"//text[@class=\\\"revenue\\\"]\", \"type\": \"text\", \"value\": \"$1.2M\"}'\n\n# Save changes\ncurl -X POST http://localhost:8080/api/save \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"output_path\": \"updated_dashboard.svg\"}'\n```\n\n### XPath Examples\n```bash\n# Find elements by ID\n//element[@id='myid']\n\n# Find elements by attribute value\n//rect[@fill='red']\n\n# Find elements containing specific text\n//text[contains(., 'Revenue')]\n\n# Find elements by position\n//record[position()=1]\n\n# Find parent elements with specific children\n//record[email='john@example.com']\n\n# Complex queries with multiple conditions\n//svg//text[@font-size='16' and contains(@class, 'title')]\n```\n\n### CSS Selector Examples (HTML only)\n```bash\n# By ID\n#main-title\n\n# By class\n.navigation-item\n\n# By attribute\ninput[type='text']\n\n# Descendant selectors\ndiv.content p\n\n# Pseudo-selectors\nli:first-child\n\n# Complex selectors\nnav.primary ul.menu li a[href^=\"/products\"]\n```\n\n## 🏗️ Project Structure\n\n```\nxqr/\n├── pyproject.toml          # Poetry configuration\n├── README.md              # This file\n├── Makefile               # Development automation\n├── xqr/                   # Main package\n│   ├── __init__.py        # Package initialization\n│   ├── core.py           # Core FileEditor class\n│   ├── cli.py            # Command-line interface\n│   ├── server.py         # HTTP server\n│   └── examples.py       # Example file generator\n└── tests/                # Test suite\n    ├── __init__.py\n    ├── test_core.py\n    ├── test_cli.py\n    └── test_server.py\n```\n\n## 🧪 Development\n\n### Setting up Development Environment\n```bash\n# Clone repository\ngit clone https://github.com/veridock/xqr.git\ncd xqr\n\n# Install with development dependencies\npoetry install\n\n# Create example files and run tests\nmake dev-setup\n\n# Run full development cycle\nmake dev\n```\n\n### Available Make Commands\n```bash\nmake help           # Show all available commands\nmake install        # Install package\nmake test           # Run test suite\nmake test-cov       # Run tests with coverage\nmake format         # Format code with black\nmake lint           # Run linting\nmake examples       # Create example files\nmake demo-svg       # Run SVG demo\nmake run-server     # Start web server\nmake run-shell      # Start interactive shell\n```\n\n### Running Tests\n```bash\n# Run all tests\npoetry run pytest\n\n# Run with coverage\npoetry run pytest --cov=xqr --cov-report=html\n\n# Run specific test file\npoetry run pytest tests/test_core.py -v\n```\n\n## 📋 Requirements\n\n- **Python**: 3.8+\n- **lxml**: For XPath support (automatically installed)\n- **beautifulsoup4**: For CSS selector support (automatically installed)\n\n## 🎯 Use Cases\n\n### DevOps \u0026 Configuration Management\n```bash\n# Update configuration across multiple environments\nfor env in dev staging prod; do\n    xqr load \"config-${env}.xml\"\n    xqr set \"//database/host\" \"db-${env}.company.com\"\n    xqr set \"//cache/ttl\" \"3600\"\n    xqr save\ndone\n```\n\n### Content Management\n```bash\n# Update copyright notices across all HTML files\nfind . -name \"*.html\" -exec xqr load {} \\; \\\n    -exec xqr set \"//footer//span[@class='year']\" \"2025\" \\; \\\n    -exec xqr save {} \\;\n```\n\n### Data Processing\n```bash\n# Extract and transform data from XML files\nxqr shell \u003c\u003c EOF\nload sales-data.xml\nlist //record[sales\u003e10000]\nset //record[sales\u003e10000]/status \"high-performer\"\nxqr save\n```\n\n## Documentation\n\n* [Full Documentation](https://github.com/veridock/xqr#readme)\n* [XPath Examples](https://github.com/veridock/xqr#xpath-examples)\n* [CSS Selector Examples](https://github.com/veridock/xqr#css-selector-examples)\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/xpath-improvements`)\n3. Make your changes\n4. Add tests for new functionality\n5. Run the test suite (`make test`)\n6. Format your code (`make format`)\n7. Commit your changes (`git commit -am 'Add XPath improvements'`)\n8. Push to the branch (`git push origin feature/xpath-improvements`)\n9. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🔗 Links\n\n- **Homepage**: https://github.com/veridock/xqr\n- **Documentation**: https://github.com/veridock/xqr#readme\n- **Issues**: https://github.com/veridock/xqr/issues\n- **PyPI**: https://pypi.org/project/xqr/\n\n## 🌟 Why XQR?\n\nTraditional approaches require different tools for each format:\n- **SVG files** → Inkscape, Adobe Illustrator, manual editing\n- **HTML files** → Web browsers, text editors, sed/awk scripts  \n- **XML files** → XML editors, custom parsers, XSLT\n\n**XQR provides a unified interface** using standard web technologies:\n- **XPath** - W3C standard for XML/HTML navigation\n- **CSS Selectors** - Familiar syntax for web developers\n- **Command Line** - Scriptable and automation-friendly\n- **REST API** - Integration with existing workflows\n\nPerfect for:\n- **CI/CD pipelines** - automated content updates\n- **Content management** - bulk HTML modifications\n- **Data processing** - XML transformation workflows  \n- **Design automation** - SVG batch processing\n- **Configuration management** - XML config updates\n\n### Real-world Examples\n\n**E-commerce**: Update product prices across thousands of XML files\n```bash\nfind products/ -name \"*.xml\" -exec xqr set \"//price[@currency='USD']\" \"$(calc_new_price {})\" \\;\n```\n\n**Documentation**: Update version numbers in all HTML docs\n```bash\nxqr set \"//meta[@name='version']\" \"v2.1.0\" --type attribute --attr content\n```\n\n**Analytics**: Update dashboard charts with new data\n```bash\nxqr set \"//svg//text[@class='metric']\" \"$REVENUE_METRIC\"\n```\n\n---\n\n**XQR - Making structured data editing simple, fast, and scriptable.**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveridock%2Fxqr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fveridock%2Fxqr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveridock%2Fxqr/lists"}