extra/id3/id3-docs.factor

   1 ! Copyright (C) 2008 Tim Wawrzynczak
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax id3.private kernel sequences
   4 strings ;
   5 IN: id3
   6
   7 HELP: mp3>id3
   8 { $values
   9     { "path" "a path string" }
  10     { "id3/f" { $maybe "tuple storing ID3v2 metadata" } } }
  11     { $description "Return a tuple containing the ID3 information parsed out of the MP3 file, or " { $link f } " if no metadata is present. Words to access the ID3v1 information are here:"
  12         { $list
  13           { $link title }
  14           { $link artist }
  15           { $link album }
  16           { $link year }
  17           { $link genre }
  18           { $link comment }
  19         }
  20         "For other fields, use the " { $link find-id3-frame } " word."
  21     } ;
  22
  23 HELP: album
  24 { $values
  25     { "id3" id3 }
  26     { "string/f" { $maybe string } }
  27 }
  28 { $description "Returns the album, or " { $link f } " if this field is missing, from a parsed id3 tag." } ;
  29
  30 HELP: artist
  31 { $values
  32     { "id3" id3 }
  33     { "string/f" { $maybe string } }
  34 }
  35 { $description "Returns the artist, or " { $link f } " if this field is missing, from a parsed id3 tag." } ;
  36
  37 HELP: comment
  38 { $values
  39     { "id3" id3 }
  40     { "string/f" { $maybe string } }
  41 }
  42 { $description "Returns the comment, or " { $link f } " if this field is missing, from a parsed id3 tag." } ;
  43
  44 HELP: genre
  45 { $values
  46     { "id3" id3 }
  47     { "string/f" { $maybe string } }
  48 }
  49 { $description "Returns the genre, or " { $link f } " if this field is missing, from a parsed id3 tag." } ;
  50
  51 HELP: title
  52 { $values
  53     { "id3" id3 }
  54     { "string/f" { $maybe string } }
  55 }
  56 { $description "Returns the title, or " { $link f } " if this field is missing, from a parsed id3 tag." } ;
  57
  58 HELP: year
  59 { $values
  60     { "id3" id3 }
  61     { "string/f" { $maybe string } }
  62 }
  63 { $description "Returns the year, or " { $link f } " if this field is missing, from a parsed id3 tag." } ;
  64
  65 HELP: find-id3-frame
  66 { $values
  67     { "id3" id3 } { "name" string }
  68     { "obj/f" { $maybe object } }
  69 }
  70 { $description "Returns the " { $slot "data" } " slot of the ID3 frame with the given name, or " { $link f } "." } ;
  71
  72 HELP: mp3-paths>id3s
  73 { $values
  74     { "seq" sequence }
  75     { "seq'" sequence }
  76 }
  77 { $description "From a sequence of pathnames, parses each ID3 header and returns a sequence of key/value pairs of pathnames and ID3 objects." } ;
  78
  79 HELP: find-mp3s
  80 { $values
  81     { "path" "a pathname string" }
  82     { "seq" sequence }
  83 }
  84 { $description "Returns a sequence of MP3 pathnames from a directory and all of its subdirectories." } ;
  85
  86 HELP: parse-mp3-directory
  87 { $values
  88     { "path" "a pathname string" }
  89     { "seq" sequence }
  90 }
  91 { $description "Returns a sequence of key/value pairs where the key is the path of an MP3 and the value is the parsed ID3 header or " { $link f } " recursively for each MP3 file in the directory and all subdirectories." } ;
  92
  93 ARTICLE: "id3" "ID3 tags"
  94 "The " { $vocab-link "id3" } " vocabulary contains words for parsing " { $emphasis "ID3" } " tags, which are textual fields storing an MP3's title, artist, and other metadata." $nl
  95 "Parsing ID3 tags for a directory of MP3s, recursively:"
  96 { $subsections parse-mp3-directory }
  97 "Finding MP3 files recursively:"
  98 { $subsections find-mp3s }
  99 "Parsing a sequence of MP3 pathnames:"
 100 { $subsections mp3-paths>id3s }
 101 "Parsing an MP3 file's ID3 tags:"
 102 { $subsections mp3>id3 }
 103 "ID3v1 frame tag accessors:"
 104 { $subsections
 105     album
 106     artist
 107     comment
 108     genre
 109     title
 110     year
 111 }
 112 "Access any frame tag:"
 113 { $subsections find-id3-frame } ;
 114
 115 ABOUT: "id3"