usb: add help, implement higher level functions

contrib/usb/load.factor

@@ -8,5 +8,6 @@ PROVIDE: contrib/usb {
 	{ "usb-win32.factor" [ win32? ] }
 	{ "usb-macosx.factor" [ macosx? ] }
 	"usb.factor" 
+	"usb.facts" 
 } { 
 } ;

contrib/usb/usb.factor

@@ -2,7 +2,7 @@
 ! See http://factorcode.org/license.txt for BSD license.
 !
 IN: usb
-USING: kernel alien io math ;
+USING: kernel alien io math arrays sequences ;
 
 LIBRARY: usb
 
@@ -38,27 +38,51 @@ FUNCTION: int usb_find_devices ( ) ;
 FUNCTION: usb_device* usb_device ( usb_dev_handle* dev ) ;
 FUNCTION: usb_bus* usb_get_busses ( ) ;
 
+: bus-each ( usb_bus quot -- ) 
+  [ call ] 2keep >r usb_bus-next r> over [ bus-each ] [ 2drop ] if ;
 
-: t1 ( -- string )
+: device-each ( usb_device quot -- )
-  usb_find_busses drop usb_find_devices drop usb_get_busses usb_bus-dirname ;
+  [ call ] 2keep >r usb_device-next r> over [ device-each ] [ 2drop ] if ;
 
-: ((t2)) ( device -- )
+: vendor-id-matches? ( id usb_device -- bool )
-  terpri
+  usb_device-descriptor usb_device_descriptor-idVendor = ;
-  [
-    "  " write
-    dup usb_device-filename write 
-    " - " write dup usb_device-descriptor usb_device_descriptor-bLength number>string write 
-    " - " write dup usb_device-descriptor usb_device_descriptor-idVendor >hex write 
-    " - " write usb_device-descriptor usb_device_descriptor-idProduct >hex write 
-  ] when* ;
 
-: (t2) ( bus -- )
+: product-id-matches? ( id usb_device  -- bool )
-  [
+  usb_device-descriptor usb_device_descriptor-idProduct = ;
+
+: is-device? ( vendor-id product-id usb_device -- bool )
+  tuck product-id-matches? >r vendor-id-matches? r> and ;
+
+: find-devices ( vendor-id product-id -- seq )
+  2array
+  V{ } clone
+  usb_get_busses [
+    usb_bus-devices [
+      pick first2 pick is-device? [
+        over push
+      ] [
+        drop
+      ] if
+    ] device-each
+  ] bus-each nip ;
+
+: init ( -- )
+  #! Initialize libusb and find devices and busses
+  usb_init usb_find_busses drop usb_find_devices drop ;
+	
+: display-devices ( -- )
+  #! Example function to list all usb devices on system
+  usb_get_busses [
     dup usb_bus-dirname write " - " write 
-    dup usb_bus-devices ((t2))
+    usb_bus-devices [
+      terpri "  " write
+      dup usb_device-filename write 
+      " - " write 
+      dup usb_device-descriptor usb_device_descriptor-bLength number>string write 
+      " - " write 
+      dup usb_device-descriptor usb_device_descriptor-idVendor >hex write 
+      " - " write 
+      usb_device-descriptor usb_device_descriptor-idProduct >hex write
+    ] device-each
     terpri
-    usb_bus-next (t2) 
+  ] bus-each ;
-  ] when* ;
-
-: t2 ( -- )
-  usb_get_busses (t2) ;

contrib/usb/usb.facts

@@ -0,0 +1,44 @@
+! Copyright (C) 2006 Chris Double.
+! See http://factorcode.org/license.txt for BSD license.
+
+USING: help usb ;
+
+HELP: bus-each 
+{ $values { "usb_bus" "an alien pointing to a usb_bus structure" } { "quot" "A quotation with stack effect " { $snippet "( usb_bus -- )" } } }
+{ $description "Starting with the given usb_bus, traverse the linked list of busses calling the quotation on each one." } 
+{ $examples
+  { $example "usb_get_busses [ display-devices ]" }
+}
+{ $see-also device-each find-devices } ;
+
+HELP: device-each 
+{ $values { "usb_device" "an alien pointing to a usb_device structure" } { "quot" "A quotation with stack effect " { $snippet "( usb_device -- )" } } }
+{ $description "Starting with the given usb_device, traverse the linked list of devices calling the quotation on each one." } 
+{ $examples
+  { $example "usb_get_busses [\n  usb_bus-devices [ display-device ]\n] bus-each" }
+}
+{ $see-also bus-each find-devices } ;
+
+HELP: vendor-id-matches?
+{ $values { "id" "the integer vendor id" } { "usb_device" "an alien pointing to a usb_device structure" } { "bool" "a boolean" } }
+{ $description "Return true if the device has the given vendor id." } 
+{ $see-also product-id-matches? is-device? } ;
+
+HELP: product-id-matches?
+{ $values { "id" "the integer product id" } { "usb_device" "an alien pointing to a usb_device structure" } { "bool" "a boolean" } }
+{ $description "Return true if the device has the given product id." } 
+{ $see-also vendor-id-matches? is-device? } ;
+
+HELP: is-device?
+{ $values { "vendor-id" "the integer vendor id" } { "product-id" "the integer product-id" } { "usb_device" "an alien pointing to a usb_device structure" } { "bool" "a boolean" } }
+{ $description "Return true if the device has the given vendor and product id." } 
+{ $see-also vendor-id-matches? product-id-matches? } ;
+
+HELP: find-devices 
+{ $values { "vendor-id" "the integer vendor id for the device to find" } { "product-id" "the integer product id for the device to find" } { "seq" "a sequence containing the usb_devices found" } }
+{ $description "Traverse the devices on all USB busses looking for a device with the given vendor and product id's. Return a sequence containing all the usb_device structures found matcing the vendor and product id's." } 
+{ $examples
+  { $example "HEX: 10D6 HEX: 1100 find-devices" }
+}
+{ $see-also bus-each device-each } ;
+