brian/cupsadmin
1
0
Fork 0
mirror of https://github.com/kfattic/cupsadmin.git synced 2026-11-13 19:06:43 -05:00
Code Issues Packages Projects Releases 1 Wiki Activity

Vendor-neutral Quick Actions: driver profiles, generic fallback, ppdreport

Browse Source 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
kfattic
2026-09-16 13:22:19 -05:00
parent 3af6a4e88f
commit 8d39bafb6f
12 changed files with 496 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files

150
Sources/CupsKit/QuickActions.swift
View File

@@ -1,108 +1,112 @@
import Foundation
/// Task-named shortcuts that set queue defaults without knowing option keywords.
/// Each one is data: which PPD keyword/value pairs to write (first variant the PPD supports wins).
/// Keywords and values come from docs/ricoh-ppd-options.md — never guessed.
/// What each one writes comes from the driver profiles in Resources/driver-profiles.json.
public struct QuickAction: Identifiable, Hashable {
public enum Input: Hashable {
case none
/// Digits, up to the PPD's own limit. An empty value clears the code.
/// Digits, up to the PPD's own limit.
case userCode
}
public enum Effect: Hashable {
/// `lpadmin -p queue -o ...` with the first variant whose keywords and values this PPD has.
/// `{value}` in a value is replaced with the input.
case options(variants: [[String: String]], clearVariants: [[String: String]])
/// `lpadmin -d queue`.
case defaultPrinter
}
/// CLI name: `cupsadmin quick <id> <queue>`.
/// CLI name (`cupsadmin quick <id> <queue>`) and the key in driver-profiles.json.
public let id: String
public let title: String
public let systemImage: String
public let input: Input
public let effect: Effect
/// One line for the CLI list and tooltips.
public let summary: String
public var isDefaultPrinter: Bool { id == "default" }
public static let all: [QuickAction] = [
QuickAction(id: "color", title: "Always Print in Color", systemImage: "paintpalette", input: .none,
effect: .options(variants: [["ColorModel": "CMYK"], ["HQColorMode": "COLOR"]], clearVariants: []),
summary: "Color by default (ColorModel=CMYK, or HQColorMode=COLOR)"),
summary: "Color by default"),
QuickAction(id: "bw", title: "Always Print Black & White", systemImage: "circle.lefthalf.filled", input: .none,
effect: .options(variants: [["ColorModel": "Gray"], ["HQColorMode": "BW"]], clearVariants: []),
summary: "Black & white by default (ColorModel=Gray, or HQColorMode=BW)"),
summary: "Black & white by default"),
QuickAction(id: "usercode", title: "Set User Code…", systemImage: "person.badge.key", input: .userCode,
effect: .options(variants: [["RIEnableUserCode": "True", "RIUserCode": "Custom.{value}"]],
clearVariants: [["RIEnableUserCode": "False", "RIUserCode": "None"]]),
summary: "Ricoh user code for every job (RIEnableUserCode=True, RIUserCode=Custom.<code>)"),
summary: "User/department code sent with every job (--clear to remove)"),
QuickAction(id: "duplex", title: "Default to Duplex", systemImage: "doc.on.doc", input: .none,
effect: .options(variants: [["Duplex": "DuplexNoTumble"]], clearVariants: []),
summary: "Two-sided, long edge (Duplex=DuplexNoTumble)"),
summary: "Two-sided, long edge"),
QuickAction(id: "simplex", title: "Default to Single-Sided", systemImage: "doc", input: .none,
effect: .options(variants: [["Duplex": "None"]], clearVariants: []),
summary: "One-sided (Duplex=None)"),
summary: "One-sided"),
QuickAction(id: "letter", title: "Use Letter Paper, Fit to Nearest Size", systemImage: "arrow.up.left.and.arrow.down.right",
input: .none,
effect: .options(variants: [["PageSize": "Letter", "RIPaperPolicy": "NearestSizeAdjust"]], clearVariants: []),
summary: "Letter, never prompt at the printer (PageSize=Letter, RIPaperPolicy=NearestSizeAdjust)"),
input: .none, summary: "Letter paper, and fit to the nearest size where the driver can (never prompt at the printer)"),
QuickAction(id: "default", title: "Make Default Printer", systemImage: "star", input: .none,
effect: .defaultPrinter, summary: "Server default printer (lpadmin -d)"),
summary: "Server default printer (lpadmin -d)"),
]
public static func named(_ id: String) -> QuickAction? {
all.first { $0.id == id }
}
/// The option changes for this PPD, or why the action isn't available on it.
public func changes(for ppd: PPD?, value: String? = nil) -> Result<[OptionChange], QuickActionUnavailable> {
guard case .options(let variants, let clearVariants) = effect else { return .success([]) }
let clearing = input == .userCode && (value ?? "").isEmpty
let candidates = clearing ? clearVariants : variants
guard let ppd else { return .failure(QuickActionUnavailable(reason: "\(title) needs a PPD; this queue has none")) }
for variant in candidates {
var changes: [OptionChange] = []
for key in variant.keys.sorted() {
guard let option = ppd.option(key) else { changes = []; break }
let raw = variant[key]!
if raw.contains("{value}") {
guard !option.customParameters.isEmpty else { changes = []; break }
changes.append(OptionChange(key: key, value: raw.replacingOccurrences(of: "{value}", with: value ?? ""), isSecret: false))
} else {
guard option.choices.contains(raw) else { changes = []; break }
changes.append(OptionChange(key: key, value: raw, isSecret: false))
/// The profile and option changes this action would write on a queue, or why it can't.
public func resolve(_ context: DriverContext, value: String? = nil, clearing: Bool = false,
profiles: [DriverProfile] = DriverProfiles.builtIn) -> Result<ResolvedQuickAction, QuickActionUnavailable> {
let key = clearing ? id + "-clear" : id
var firstMissing: String?
for profile in DriverProfiles.matching(context, in: profiles) {
guard let alternatives = profile.actions[key] else { continue }
for pairs in alternatives {
let parsed = pairs.compactMap(Self.parse)
let filled = parsed.map { ($0.key, $0.value.replacingOccurrences(of: "{value}", with: value ?? "")) }
if let missing = filled.first(where: { !context.supports(key: $0.0, value: $0.1) }) {
if firstMissing == nil { firstMissing = "\(missing.0)=\(parsed.first { $0.key == missing.0 }!.value)" }
continue
}
let changes = filled.map { OptionChange(key: $0.0, value: $0.1, isSecret: false) }
return .success(ResolvedQuickAction(profile: profile, changes: changes))
}
if !changes.isEmpty { return .success(changes) }
}
let needed = Set(candidates.flatMap { $0.keys }).sorted().joined(separator: " / ")
return .failure(QuickActionUnavailable(reason: "This printer’s PPD has no \(needed) with the needed choice"))
let detail = firstMissing.map { " (no \($0))" } ?? " (no driver profile maps \(key))"
return .failure(QuickActionUnavailable(reason: "Not available for \(context.driverName)\(detail)"))
}
public func isAvailable(for ppd: PPD?) -> Bool {
if case .defaultPrinter = effect { return true }
if case .success = changes(for: ppd, value: input == .userCode ? "0" : nil) { return true }
return false
/// nil when the action can run on this queue; otherwise the reason (for tooltips and CLI errors).
public func unavailableReason(in context: DriverContext) -> String? {
if isDefaultPrinter { return nil }
switch resolve(context, value: input == .userCode ? "0" : nil) {
case .success: return nil
case .failure(let unavailable): return unavailable.reason
}
}
/// For Set User Code: digits only, within the PPD's RIUserCode length. nil when valid.
public func validationError(_ value: String, ppd: PPD?) -> String? {
public func isAvailable(in context: DriverContext) -> Bool { unavailableReason(in: context) == nil }
/// For Set User Code: digits only, within the PPD's limit for the code option. nil when valid.
public func validationError(_ value: String, context: DriverContext) -> String? {
guard input == .userCode, !value.isEmpty else { return nil }
guard value.allSatisfy({ ("0"..."9").contains($0) }) else { return "Digits only" }
if let max = ppd?.option("RIUserCode")?.customParameters.first.flatMap({ Int($0.maximum) }), value.count > max {
if let keyword = codeKeyword(context),
let max = context.ppd?.option(keyword)?.customParameters.first.flatMap({ Int($0.maximum) }), value.count > max {
return "At most \(max) digits"
}
return nil
}
/// The current user code on the queue, without the Custom. prefix (nil when none is set).
public static func currentUserCode(_ ppd: PPD?) -> String? {
guard let value = ppd?.option("RIUserCode")?.defaultChoice, value.hasPrefix("Custom.") else { return nil }
/// The code currently set on the queue, without the Custom. prefix (nil when none).
public func currentCode(_ context: DriverContext) -> String? {
guard let keyword = codeKeyword(context),
let value = context.ppd?.option(keyword)?.defaultChoice, value.hasPrefix("Custom.") else { return nil }
return String(value.dropFirst("Custom.".count))
}
/// The option that receives `{value}` for this queue's profile (e.g. RIUserCode).
private func codeKeyword(_ context: DriverContext) -> String? {
guard input == .userCode, case .success(let resolved) = resolve(context, value: "0") else { return nil }
let profilePairs = resolved.profile.actions[id]?.first ?? []
return profilePairs.compactMap(Self.parse).first { $0.value.contains("{value}") }?.key
}
static func parse(_ pair: String) -> (key: String, value: String)? {
guard let eq = pair.firstIndex(of: "="), eq != pair.startIndex else { return nil }
return (String(pair[..<eq]), String(pair[pair.index(after: eq)...]))
}
}
public struct ResolvedQuickAction {
public let profile: DriverProfile
public let changes: [OptionChange]
}
public struct QuickActionUnavailable: Error, Hashable {
@@ -112,6 +116,8 @@ public struct QuickActionUnavailable: Error, Hashable {
public struct QuickActionOutcome {
public let command: String
public let succeeded: Bool
/// The driver profile used; nil for Make Default Printer.
public let profile: DriverProfile?
/// Per-option read-back; empty for Make Default Printer.
public let readBack: [OptionReadBack]
public let changes: [OptionChange]
@@ -119,21 +125,19 @@ public struct QuickActionOutcome {
}
extension QuickAction {
/// Runs the action on a queue with read-back. Throws QuickActionUnavailable when the PPD lacks the options.
public func run(queue: String, value: String? = nil, client: CupsClient) async throws -> QuickActionOutcome {
switch effect {
case .defaultPrinter:
/// Runs the action on a queue with read-back. Throws QuickActionUnavailable when no profile fits.
public func run(queue: String, value: String? = nil, clearing: Bool = false, client: CupsClient) async throws -> QuickActionOutcome {
if isDefaultPrinter {
let outcome = try await QueueActions.setDefault(queue: queue, client: client)
return QuickActionOutcome(command: outcome.command, succeeded: outcome.succeeded, readBack: [],
changes: [], message: outcome.message)
case .options:
let ppd = try await client.getPPD(queue: queue).map(PPD.init(text:))
let changes = try self.changes(for: ppd, value: value).get()
let (result, readBack, _) = try await OptionApplier.apply(client: client, queue: queue, changes: changes)
let failed = readBack.filter { !$0.applied }
return QuickActionOutcome(command: OptionApplier.displayCommand(queue: queue, changes: changes),
succeeded: result.succeeded && failed.isEmpty, readBack: readBack, changes: changes,
message: failed.first?.reason)
return QuickActionOutcome(command: outcome.command, succeeded: outcome.succeeded, profile: nil,
readBack: [], changes: [], message: outcome.message)
}
let context = try await DriverContext.load(client: client, queue: queue)
let resolved = try resolve(context, value: value, clearing: clearing).get()
let (result, readBack, _) = try await OptionApplier.apply(client: client, queue: queue, changes: resolved.changes)
let failed = readBack.filter { !$0.applied }
return QuickActionOutcome(command: OptionApplier.displayCommand(queue: queue, changes: resolved.changes),
succeeded: result.succeeded && failed.isEmpty, profile: resolved.profile,
readBack: readBack, changes: resolved.changes, message: failed.first?.reason)
}
}