Skip to main content

add some explanatory comments

ID
658b66e
date
2023-05-13 21:55:21+00:00
author
Alex Chan <alex@alexwlchan.net>
parent
f979de0
message
add some explanatory comments
changed files
2 files, 83 additions, 37 deletions

Changed files

actions/get_structural_metadata.swift (1444) → actions/get_structural_metadata.swift (2010)

diff --git a/actions/get_structural_metadata.swift b/actions/get_structural_metadata.swift
index 37c9ca9..3e4fdf7 100644
--- a/actions/get_structural_metadata.swift
+++ b/actions/get_structural_metadata.swift
@@ -1,3 +1,12 @@
+#!/usr/bin/env swift
+/// This script gets some metadata from my Photos Library, in particular:
+///
+///   - a list of all my albums
+///   - a list of all my photos
+///
+/// This data takes the form of the `Response` struct shown below, and is
+/// formatted as JSON printed to stdout.
+
 import Photos
 
 struct AlbumData: Codable {
@@ -6,56 +15,66 @@ struct AlbumData: Codable {
   var assetIdentifiers: [String]
 }
 
-var allAlbums: [AlbumData] = []
+struct AssetData: Codable {
+  var localIdentifier: String
+  var creationDate: String?
+  var isFavorite: Bool
+}
 
-PHAssetCollection
-  .fetchAssetCollections(with: .album, subtype: .albumRegular, options: nil)
-  .enumerateObjects({ (album, _, _) in
-    var assetIdentifiers: [String] = []
+struct Response: Codable {
+  var albums: [AlbumData]
+  var assets: [AssetData]
+}
 
-    PHAsset
-      .fetchAssets(in: album, options: nil)
-      .enumerateObjects({ (asset, _, _) in
-        assetIdentifiers.append(asset.localIdentifier)
-      })
+/// Get data for all the albums in my library.
+func getAllAlbums() -> [AlbumData] {
+  var allAlbums: [AlbumData] = []
 
-    allAlbums.append(
-      AlbumData(
-        localIdentifier: album.localIdentifier,
-        localizedTitle: album.localizedTitle,
-        assetIdentifiers: assetIdentifiers
+  PHAssetCollection
+    .fetchAssetCollections(with: .album, subtype: .albumRegular, options: nil)
+    .enumerateObjects({ (album, _, _) in
+      var assetIdentifiers: [String] = []
+
+      PHAsset
+        .fetchAssets(in: album, options: nil)
+        .enumerateObjects({ (asset, _, _) in
+          assetIdentifiers.append(asset.localIdentifier)
+        })
+
+      allAlbums.append(
+        AlbumData(
+          localIdentifier: album.localIdentifier,
+          localizedTitle: album.localizedTitle,
+          assetIdentifiers: assetIdentifiers
+        )
       )
-    )
-  })
+    })
 
-struct AssetData: Codable {
-  var localIdentifier: String
-  var creationDate: String?
-  var isFavorite: Bool
+  return allAlbums
 }
 
-var allAssets: [AssetData] = []
+/// Gets data for all the photos in my library.
+func getAllAssets() -> [AssetData] {
+  var allPhotos: [AssetData] = []
 
-PHAsset
-  .fetchAssets(with: PHAssetMediaType.image, options: nil)
-  .enumerateObjects({ (asset, _, _) in
-    allAssets.append(
-      AssetData(
-        localIdentifier: asset.localIdentifier,
-        creationDate: asset.creationDate?.ISO8601Format(),
-        isFavorite: asset.isFavorite
+  PHAsset
+    .fetchAssets(with: PHAssetMediaType.image, options: nil)
+    .enumerateObjects({ (asset, _, _) in
+      allPhotos.append(
+        AssetData(
+          localIdentifier: asset.localIdentifier,
+          creationDate: asset.creationDate?.ISO8601Format(),
+          isFavorite: asset.isFavorite
+        )
       )
-    )
-  })
+    })
 
-struct Response: Codable {
-  var albums: [AlbumData]
-  var assets: [AssetData]
+  return allPhotos
 }
 
 let jsonEncoder = JSONEncoder()
 let jsonData = try jsonEncoder.encode(
-  Response(albums: allAlbums, assets: allAssets)
+  Response(albums: getAllAlbums(), assets: getAllAssets())
 )
 let json = String(data: jsonData, encoding: String.Encoding.utf8)
 print(json!)

actions/run_action.swift (3886) → actions/run_action.swift (4889)

diff --git a/actions/run_action.swift b/actions/run_action.swift
index 07893e8..123a25a 100644
--- a/actions/run_action.swift
+++ b/actions/run_action.swift
@@ -1,4 +1,31 @@
 #!/usr/bin/env swift
+/// This script makes changes to my Photos library.
+///
+/// It takes two argument: an asset ID, and the name of the action to
+/// perform in my Photos library.
+///
+/// The asset ID is the 'localIdentifier' property of a PHAsset.
+///
+/// The available actions are as follows:
+///
+///     toggle-favorite
+///       If an image is already a favorite, unmark it as such.
+///       If an image isn't a favorite, mark it as a favorite.
+///
+///     toggle-flagged
+///     toggle-rejected
+///     toggle-needs-action
+///       When I review an image, it gets sorted into one of three buckets,
+///       which have corresponding albums in Photos: Flagged, Rejected,
+///       Needs Action.
+///
+///       These actions add an asset to the appropriate album, and remove it
+///       from the other albums.  If you run it a second time, it gets
+///       removed from the album, resetting it to zero.
+///
+///     toggle-cross-stitch
+///       Toggles an image's inclusion in my "Cross stitch" album.
+///
 
 import Photos
 
@@ -75,7 +102,7 @@ extension PHAsset {
   ///
   /// This expects to be run inside a performChangesAndWait change block;
   /// see https://developer.apple.com/documentation/photokit/phphotolibrary/1620747-performchangesandwait.
-  func toggle(inAlbum album: String) -> Void {
+  func toggle(inAlbum album: PHAssetCollection) -> Void {
     let changeAlbum =
       PHAssetCollectionChangeRequest(for: album)!