purl 1.3.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c6c3fd2d17a4601a4c296b18ce67d41c423a5893aeb2b79cd484c0028863abd
-  data.tar.gz: 2c5e92ca69e3bb8442df158f34944fad645319cdbac5fb45875c7c8521be5d0c
+  metadata.gz: 4a3bf4cd374d69577598e05fa94658b7768c94b3522314a3382d1f9b872b203b
+  data.tar.gz: e1ddc0ec9b9ec7d675c9eeff8527af612610bcce7bc344313fe5c79a4975bd7d
 SHA512:
-  metadata.gz: 34e7c52f43f92146d605e06338f25b5d12f80f495e320901aed32206dc3e743029be9b51eb5bcd1f84ef46ca450a76ac45fa7c74da5b2506eb3d53b82db6c840
-  data.tar.gz: 7941f3f3cb65695448599c590e75ef06198fdafe4739e7587e0f7518f6e58fc948896452c38136a3c1a1e6e0d52acac4b766c2a5f2dd22d0a33f8b2e1b61feb1
+  metadata.gz: 6a4e84903907467f13205f4f9c31c29e67945f83c87d68f577008598d50da3f702d98b1c0e115a5c4a441a2babfdae6b6463da5e125f5f1630476d983a116849
+  data.tar.gz: b6e45ef48f2fb2d52eea945b658a24a3e3cc4236c7656ba21b8287bb5eb7b662d7adf9d46148771b48cfcb884f5f3fcce0bbbaffb54f3d7126a3d4f1f5f297a8

data/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.0] - 2025-01-06
+
+### Added
+- Command-line interface with parse, validate, convert, url, generate, and info commands plus JSON output support
+
 ## [1.3.1] - 2025-08-04
 
 ### Fixed

data/README.md

@@ -16,6 +16,7 @@ This library features comprehensive error handling with namespaced error types,
 
 ## Features
 
+- **Command-line interface** with parse, validate, convert, generate, and info commands plus JSON output
 - **Comprehensive PURL parsing and validation** with 37 package types (32 official + 5 additional ecosystems)
 - **Better error handling** with namespaced error classes and contextual information
 - **Bidirectional registry URL conversion** - generate registry URLs from PURLs and parse PURLs from registry URLs
@@ -46,7 +47,175 @@ Or install it yourself as:
 gem install purl
 ```
 
-## Usage
+## Command Line Interface
+
+The purl gem includes a command-line interface that provides convenient access to all parsing, validation, conversion, and generation functionality.
+
+### Installation
+
+The CLI is automatically available after installing the gem:
+
+```bash
+gem install purl
+purl --help
+```
+
+### Available Commands
+
+```bash
+purl parse <purl-string>              # Parse and display PURL components
+purl validate <purl-string>           # Validate a PURL (exit code indicates success)
+purl convert <registry-url>           # Convert registry URL to PURL
+purl url <purl-string>                # Convert PURL to registry URL
+purl generate [options]               # Generate PURL from components
+purl info [type]                      # Show information about PURL types
+```
+
+### JSON Output
+
+All commands support JSON output with the `--json` flag:
+
+```bash
+purl --json parse "pkg:gem/rails@7.0.0"
+purl --json info gem
+```
+
+### Command Examples
+
+#### Parse a PURL
+```bash
+$ purl parse "pkg:gem/rails@7.0.0"
+Valid PURL: pkg:gem/rails@7.0.0
+Components:
+  Type:       gem
+  Namespace:  (none)
+  Name:       rails
+  Version:    7.0.0
+  Qualifiers: (none)
+  Subpath:    (none)
+
+$ purl --json parse "pkg:npm/@babel/core@7.0.0"
+{
+  "success": true,
+  "purl": "pkg:npm/%40babel/core@7.0.0",
+  "components": {
+    "type": "npm",
+    "namespace": "@babel",
+    "name": "core",
+    "version": "7.0.0",
+    "qualifiers": {},
+    "subpath": null
+  }
+}
+```
+
+#### Validate a PURL
+```bash
+$ purl validate "pkg:gem/rails@7.0.0"
+Valid PURL
+
+$ purl validate "invalid-purl"
+Invalid PURL: PURL must start with 'pkg:'
+```
+
+#### Convert Registry URL to PURL
+```bash
+$ purl convert "https://rubygems.org/gems/rails"
+pkg:gem/rails
+
+$ purl convert "https://www.npmjs.com/package/@babel/core"
+pkg:npm/@babel/core
+```
+
+#### Convert PURL to Registry URL
+```bash
+$ purl url "pkg:gem/rails@7.0.0"
+https://rubygems.org/gems/rails
+
+$ purl url "pkg:npm/@babel/core@7.0.0"
+https://www.npmjs.com/package/@babel/core
+
+$ purl --json url "pkg:gem/rails@7.0.0"
+{
+  "success": true,
+  "purl": "pkg:gem/rails@7.0.0",
+  "registry_url": "https://rubygems.org/gems/rails",
+  "type": "gem"
+}
+```
+
+#### Generate a PURL
+```bash
+$ purl generate --type gem --name rails --version 7.0.0
+pkg:gem/rails@7.0.0
+
+$ purl generate --type npm --namespace @babel --name core --version 7.0.0 --qualifiers "arch=x64,os=linux"
+pkg:npm/%40babel/core@7.0.0?arch=x64&os=linux
+```
+
+#### Show Type Information
+```bash
+$ purl info gem
+Type: gem
+Known: Yes
+Description: RubyGems
+Default registry: https://rubygems.org
+Registry URL generation: Yes
+Reverse parsing: Yes
+Examples:
+  pkg:gem/ruby-advisory-db-check@0.12.4
+  pkg:gem/rails@7.0.4
+  pkg:gem/bundler@2.3.26
+Registry URL patterns:
+  https://rubygems.org/gems/:name
+  https://rubygems.org/gems/:name/versions/:version
+
+$ purl info  # Shows all types
+Known PURL types:
+
+  alpm
+    Description: Arch Linux packages
+    Registry support: No
+    Reverse parsing: No
+  ...
+Total types: 37
+Registry supported: 20
+```
+
+### Generate Options
+
+The `generate` command supports all PURL components:
+
+```bash
+purl generate --help
+Usage: purl generate [options]
+    --type TYPE                      Package type (required)
+    --name NAME                      Package name (required)
+    --namespace NAMESPACE            Package namespace
+    --version VERSION                Package version
+    --qualifiers QUALIFIERS          Qualifiers as key=value,key2=value2
+    --subpath SUBPATH                Package subpath
+    -h, --help                       Show this help
+```
+
+### Exit Codes
+
+The CLI uses standard exit codes:
+- `0` - Success
+- `1` - Error (invalid PURL, unsupported operation, etc.)
+
+This makes the CLI suitable for use in scripts and CI/CD pipelines:
+
+```bash
+if purl validate "pkg:gem/rails@7.0.0"; then
+  echo "Valid PURL"
+else
+  echo "Invalid PURL"
+  exit 1
+fi
+```
+
+## Library Usage
 
 ### Basic PURL Parsing
 

data/exe/purl

@@ -0,0 +1,435 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+require_relative "../lib/purl"
+
+class PurlCLI
+  def self.run(args = ARGV)
+    new.run(args)
+  end
+
+  def initialize
+    @json_output = false
+  end
+
+  def run(args)
+    if args.empty?
+      puts usage
+      exit 1
+    end
+
+    # Check for global --json flag
+    if args.include?("--json")
+      @json_output = true
+      args.delete("--json")
+    end
+
+    command = args.shift
+    case command
+    when "parse"
+      parse_command(args)
+    when "validate"
+      validate_command(args)
+    when "convert"
+      convert_command(args)
+    when "generate"
+      generate_command(args)
+    when "url"
+      url_command(args)
+    when "info"
+      info_command(args)
+    when "--help", "-h", "help"
+      puts usage
+      exit 0
+    when "--version", "-v"
+      puts Purl::VERSION
+      exit 0
+    else
+      puts "Unknown command: #{command}"
+      puts usage
+      exit 1
+    end
+  end
+
+  private
+
+  def usage
+    <<~USAGE
+      purl - Parse, validate, convert and generate Package URLs (PURLs)
+
+      Usage:
+        purl [--json] parse <purl-string>     Parse and display PURL components
+        purl [--json] validate <purl-string>  Validate a PURL (exit code indicates success)
+        purl [--json] convert <registry-url>  Convert registry URL to PURL
+        purl [--json] url <purl-string>       Convert PURL to registry URL
+        purl [--json] generate [options]      Generate PURL from components
+        purl [--json] info [type]             Show information about PURL types
+        purl --version                        Show version
+        purl --help                           Show this help
+
+      Global Options:
+        --json                                Output results in JSON format
+
+      Examples:
+        purl parse "pkg:gem/rails@7.0.0"
+        purl --json parse "pkg:gem/rails@7.0.0"
+        purl validate "pkg:npm/@babel/core@7.0.0"
+        purl convert "https://rubygems.org/gems/rails"
+        purl url "pkg:gem/rails@7.0.0"
+        purl generate --type gem --name rails --version 7.0.0
+        purl --json info gem
+    USAGE
+  end
+
+  def parse_command(args)
+    if args.empty?
+      output_error("PURL string required")
+      exit 1
+    end
+
+    purl_string = args[0]
+    
+    begin
+      purl = Purl.parse(purl_string)
+      
+      if @json_output
+        result = {
+          success: true,
+          purl: purl.to_s,
+          components: {
+            type: purl.type,
+            namespace: purl.namespace,
+            name: purl.name,
+            version: purl.version,
+            qualifiers: purl.qualifiers || {},
+            subpath: purl.subpath
+          }
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Valid PURL: #{purl.to_s}"
+        puts "Components:"
+        puts "  Type:       #{purl.type}"
+        puts "  Namespace:  #{purl.namespace || '(none)'}"
+        puts "  Name:       #{purl.name}"
+        puts "  Version:    #{purl.version || '(none)'}"
+        
+        if purl.qualifiers && !purl.qualifiers.empty?
+          puts "  Qualifiers:"
+          purl.qualifiers.each do |key, value|
+            puts "    #{key}: #{value}"
+          end
+        else
+          puts "  Qualifiers: (none)"
+        end
+        
+        puts "  Subpath:    #{purl.subpath || '(none)'}"
+      end
+    rescue Purl::Error => e
+      output_error("Error parsing PURL: #{e.message}")
+      exit 1
+    end
+  end
+
+  def validate_command(args)
+    if args.empty?
+      output_error("PURL string required")
+      exit 1
+    end
+
+    purl_string = args[0]
+    
+    begin
+      purl = Purl.parse(purl_string)
+      if @json_output
+        result = {
+          success: true,
+          valid: true,
+          purl: purl.to_s,
+          message: "Valid PURL"
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Valid PURL"
+      end
+      exit 0
+    rescue Purl::Error => e
+      if @json_output
+        result = {
+          success: false,
+          valid: false,
+          purl: purl_string,
+          error: e.message
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Invalid PURL: #{e.message}"
+      end
+      exit 1
+    end
+  end
+
+  def convert_command(args)
+    if args.empty?
+      output_error("Registry URL required")
+      exit 1
+    end
+
+    registry_url = args[0]
+    
+    begin
+      purl = Purl.from_registry_url(registry_url)
+      if @json_output
+        result = {
+          success: true,
+          registry_url: registry_url,
+          purl: purl.to_s,
+          components: {
+            type: purl.type,
+            namespace: purl.namespace,
+            name: purl.name,
+            version: purl.version,
+            qualifiers: purl.qualifiers || {},
+            subpath: purl.subpath
+          }
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts purl.to_s
+      end
+    rescue Purl::Error => e
+      if @json_output
+        result = {
+          success: false,
+          registry_url: registry_url,
+          error: e.message
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Error converting URL: #{e.message}"
+      end
+      exit 1
+    end
+  end
+
+  def url_command(args)
+    if args.empty?
+      output_error("PURL string required")
+      exit 1
+    end
+
+    purl_string = args[0]
+    
+    begin
+      purl = Purl.parse(purl_string)
+      
+      unless purl.supports_registry_url?
+        if @json_output
+          result = {
+            success: false,
+            purl: purl_string,
+            error: "Registry URL generation not supported for type '#{purl.type}'"
+          }
+          puts JSON.pretty_generate(result)
+        else
+          puts "Error: Registry URL generation not supported for type '#{purl.type}'"
+        end
+        exit 1
+      end
+      
+      registry_url = purl.registry_url
+      
+      if @json_output
+        result = {
+          success: true,
+          purl: purl.to_s,
+          registry_url: registry_url,
+          type: purl.type
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts registry_url
+      end
+    rescue Purl::Error => e
+      if @json_output
+        result = {
+          success: false,
+          purl: purl_string,
+          error: e.message
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Error: #{e.message}"
+      end
+      exit 1
+    end
+  end
+
+  def generate_command(args)
+    options = {}
+    OptionParser.new do |opts|
+      opts.banner = "Usage: purl generate [options]"
+      
+      opts.on("--type TYPE", "Package type (required)") do |v|
+        options[:type] = v
+      end
+      
+      opts.on("--name NAME", "Package name (required)") do |v|
+        options[:name] = v
+      end
+      
+      opts.on("--namespace NAMESPACE", "Package namespace") do |v|
+        options[:namespace] = v
+      end
+      
+      opts.on("--version VERSION", "Package version") do |v|
+        options[:version] = v
+      end
+      
+      opts.on("--qualifiers QUALIFIERS", "Qualifiers as key=value,key2=value2") do |v|
+        qualifiers = {}
+        v.split(",").each do |pair|
+          key, value = pair.split("=", 2)
+          if key && value
+            qualifiers[key.strip] = value.strip
+          end
+        end
+        options[:qualifiers] = qualifiers unless qualifiers.empty?
+      end
+      
+      opts.on("--subpath SUBPATH", "Package subpath") do |v|
+        options[:subpath] = v
+      end
+      
+      opts.on("-h", "--help", "Show this help") do
+        puts opts
+        exit 0
+      end
+    end.parse!(args)
+
+    unless options[:type] && options[:name]
+      output_error("--type and --name are required")
+      puts "Use 'purl generate --help' for more information" unless @json_output
+      exit 1
+    end
+
+    begin
+      purl = Purl::PackageURL.new(**options)
+      if @json_output
+        result = {
+          success: true,
+          purl: purl.to_s,
+          components: {
+            type: purl.type,
+            namespace: purl.namespace,
+            name: purl.name,
+            version: purl.version,
+            qualifiers: purl.qualifiers || {},
+            subpath: purl.subpath
+          }
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts purl.to_s
+      end
+    rescue Purl::Error => e
+      if @json_output
+        result = {
+          success: false,
+          error: e.message,
+          options: options
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Error generating PURL: #{e.message}"
+      end
+      exit 1
+    end
+  end
+
+  def info_command(args)
+    if args.empty?
+      # Show all types
+      all_info = Purl.all_type_info
+      metadata = Purl.types_config_metadata
+      
+      if @json_output
+        result = {
+          success: true,
+          types: all_info,
+          metadata: metadata
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Known PURL types:"
+        puts
+        
+        all_info.each do |type, info|
+          puts "  #{type}"
+          puts "    Description: #{info[:description] || 'No description available'}"
+          puts "    Registry support: #{info[:registry_url_generation] ? 'Yes' : 'No'}"
+          puts "    Reverse parsing: #{info[:reverse_parsing] ? 'Yes' : 'No'}"
+          puts
+        end
+        
+        puts "Total types: #{metadata[:total_types]}"
+        puts "Registry supported: #{metadata[:registry_supported_types]}"
+      end
+    else
+      # Show specific type info
+      type = args[0]
+      info = Purl.type_info(type)
+      
+      if @json_output
+        result = {
+          success: true,
+          type: info
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Type: #{info[:type]}"
+        puts "Known: #{info[:known] ? 'Yes' : 'No'}"
+        puts "Description: #{info[:description] || 'No description available'}"
+        
+        if info[:default_registry]
+          puts "Default registry: #{info[:default_registry]}"
+        end
+        
+        puts "Registry URL generation: #{info[:registry_url_generation] ? 'Yes' : 'No'}"
+        puts "Reverse parsing: #{info[:reverse_parsing] ? 'Yes' : 'No'}"
+        
+        if info[:examples] && !info[:examples].empty?
+          puts "Examples:"
+          info[:examples].each do |example|
+            puts "  #{example}"
+          end
+        end
+        
+        if info[:route_patterns] && !info[:route_patterns].empty?
+          puts "Registry URL patterns:"
+          info[:route_patterns].each do |pattern|
+            puts "  #{pattern}"
+          end
+        end
+      end
+    end
+  end
+
+  def output_error(message)
+    if @json_output
+      result = {
+        success: false,
+        error: message
+      }
+      puts JSON.pretty_generate(result)
+    else
+      puts "Error: #{message}"
+    end
+  end
+end
+
+if __FILE__ == $0
+  PurlCLI.run
+end

data/lib/purl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Purl
-  VERSION = "1.3.1"
+  VERSION = "1.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: purl
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.0
 platform: ruby
 authors:
 - Andrew Nesbitt
@@ -28,7 +28,8 @@ description: |-
   It supports 37 package types (32 official + 5 additional ecosystems) and is fully compliant with the official PURL specification test suite.
 email:
 - andrewnez@gmail.com
-executables: []
+executables:
+- purl
 extensions: []
 extra_rdoc_files: []
 files:
@@ -40,6 +41,7 @@ files:
 - README.md
 - Rakefile
 - SECURITY.md
+- exe/purl
 - lib/purl.rb
 - lib/purl/errors.rb
 - lib/purl/package_url.rb