x2c 0.1

data/README

@@ -0,0 +1,103 @@
+= x2c - the interactive ruby compiler
+
+The client itself is an irb shell executing commands on the client object, which
+has been extended to get a powerful and easy interface to playback, playlists
+and collections. As it is all ruby, you can easily extend its functionality,
+create new aliases or functions, or create you own client on top of it.
+
+== First Steps
+=== Installation
+If you want use the gem (to keep you system clean or things like that), just
+build it out of the gemspec and install it:
+    gem build x2c.gemspec
+    sudo gem install x2c-0.1.gem
+But you also can simply copy the x2c folder somewhere on your disc and run ./x2c
+directly or symlink to it.
+
+=== Usage
+If you start x2c, you will be confronted with a short tutorial helping you with
+the first steps in x2c. After you finisched the tutorial and seted up the
+config, you can use x2c normally. You can get descriptions about functions and
+modules with the help command.
+
+== the design
+
+x2c creates a new xmms client objects, and starts a new irb workspace with the
+client as its main object. Both client and workspace are extended to have some
+extra functionalities.
+
+So all you do is calling functions with arguments on the xmms client. Therefore
+you must type valid ruby syntax, but it allows you to get all the power of ruby.
+There are 3 main objects inside the xmms client lib and inside my client:
+* the client itself: where all the function calls go. It is the interface to
+  daemon, you can git information about the medialib and change playback with it.
+* playlists: they are play ;) and song are removed, moved or inserted
+* collections: powerful way to express media queries
+* theres also another thing called Songlist, which is used to pass around song
+  ids
+
+== the interface
+
+All output is formated to give you information about the objects you process and
+the state you are inside
+
+=== understanding the output
+
+==== the commandline
+
+The commandline will show the playback status, e.g. '>>' for PLAY, '||' for PAUSE and
+'[]' for STOP, and the song currently played followed by a Symbol to show you what
+mode you are in, dependent of the command what irb expects you to do.
+
+In addition to that, the async module will put out '->' followed by the new Song,
+whenever the current Song changes.
+
+==== results
+
+The results of your commands will be put after a '=>'. As that results will be
+often used for further processing, there is a variable that holds useful
+results. All results considered useful are marked with a trailing '`' , so
+whenever you see a '`' in front of a output, the last variable is set. You can
+explicitly make a result last, if you append .makelast to your command.
+Furthermore you can push results to the stack to pop them later. Just used 
+(command).push to push the result, or just push to push the last result. You
+also can restore the prelast result with the lost command.
+
+Results will be printed after the => in a readable way:
+* collections will show the hole tree of operations: first the operations and
+  its options are printed, followed by its operands in the next line. Operations
+  are shown as symbols, '%' for pshuffle ':' for idlist, ']' for a queue, '>>'
+  for a reference, '!' for complement, '&' for intersection, '|' for union, '='
+  for a field equals value collection, '~' for a Match, '>' and '<' for
+  comparing and 'E' for existents of an attribute.
+* playlists show the collection on which they are based on and the list of songs.
+  The current song will be marked with a '>'
+* Songlists just how there Songs
+* Arrays and Hashes show all of their members
+
+=== functions calls and message passing
+==== Message passing
+
+All classes have gained additional functions, and messages are often passed to
+other classes. The client object for example will forward messages to
+Collections or the playlist and the last result object. Playlists itself will
+pass unknown functions to its current Collections. Collections will try to make
+itself a playlist when needed. Songlists and id-Arrays will try to be the same,
+just that Songlists have some extra functionality and a nicer output.
+
+==== Functions 
+The help command uses the autogenreate rdoc to give you help about all the
+functions and objects. just uses the help command to get all the information.
+    help
+    help{Client}
+    help{Client::<Inculded Module>}
+    help{<command>}
+    help{Collection::<Inculded Module>}
+    ...
+
+=== Client Configuration
+You can configure the client with the .config/xmms2/x2c/config.rb file. You
+first have to copy the default configuration with the setup command. Afterwords
+you can use the configure command to edit the file.
+
+PS: feel free to ask me or say what you like/dislike.

data/x2c/config.rb

@@ -0,0 +1,59 @@
+module Xmms
+    # output things nicely
+    require 'plug/format.rb'
+    # nice interface to genrated docs
+    require 'plug/help.rb'
+    # make Xmms::Client more usable
+    require 'plug/shortcuts.rb'
+    # better playback functions (pause will unpause when pause),
+    # play can load music, skip will skip n track and tickle
+    require 'plug/iplayback'
+    # easy collection creation
+    require 'plug/query.rb'
+    # make classes interact with each other
+    require 'plug/chains.rb'
+    # stack and last functions
+    require 'plug/remember.rb'
+    # we need async module to display playback events
+    require 'plug/async.rb'
+    # shortcuts to load collections
+    require 'plug/listnames.rb'
+    # info gathering for collections
+    require 'plug/info.rb'
+    # load config interface
+    require 'plug/config.rb'
+    # automatically start local daemon
+    require 'plug/daemon.rb'
+    # voting/rating module
+    require 'plug/vote.rb'
+    # mlib interface
+    require 'plug/mlib.rb'
+
+    class Client
+        MEDIA_DIR = '.'
+        def pre_connect
+        end
+        # setup some things
+        def post_connect
+            async_start     # requires async.rb
+            playbacklist    # requires async.rb
+            setup_lists     # requires chains.rb
+        end
+        # for the daemon plugin
+        def pre_daemon
+        end
+        def post_daemon(ipc_path)
+            start
+        end
+        def dead_daemon
+        end
+        shortcut :l, :last
+        shortcut :n, :skip
+        shortcut :p, :pause
+        shortcut :c, :config
+        shortcut :s, :search
+        shortcut :h, :help
+    end
+    # define custom functionality here,
+    # or include you own ruby files
+end

data/x2c/core/args.rb

@@ -0,0 +1,36 @@
+# Copyright by Daniel Waeber, see the LICENSE file for details
+module Xmms
+    module Options
+        @@opts = Hash.new
+        @@help = Hash.new
+        def self.opts
+            @@opts
+        end
+        def self.help
+            "    "+@@help.values.format
+        end
+        def self.get_argv opt, val
+            upt = opt.upcase.gsub(/-/,'_')
+            i = ARGV.index('--'+opt)
+            arg = if i
+                ARGV.delete_at(i) if i
+                ARGV[i].nil? || ARGV[i][0..1]=='--' || ARGV.delete_at(i)
+            end 
+            lambda {arg || Xmms::Client.const_defined?(upt) && Xmms::Client.const_get(upt) || ENV[upt] || val}
+        end
+        def self.[] arg
+            if arg.is_a? Hash
+                arg.each_pair do |k,a|
+                    a.first = false if(a.first == 'false')
+                    @@opts[k] = get_argv(k,a.first)
+                    @@help[k] = "--#{k}\n        #{a.last}\n        default: #{a.first}"
+                end
+            else
+                @@opts[arg].call
+            end
+        end
+        def self.[]= key, val
+            @@opts[key]=lambda{val}
+        end
+    end
+end

data/x2c/core/client.rb

@@ -0,0 +1,61 @@
+# Copyright by Daniel Waeber, see the LICENSE file for details
+
+# this module improves collection handling of the Cleint object and
+# remembers the first started client, any object can access it
+require 'core/args.rb'
+
+module Kernel
+    # returns a xmms2 client object
+    def xmms
+        Xmms::Client.main
+    end
+end
+module Xmms
+    # the Client object is the main interface to the deamon.
+    # by default, all commands will be executed on the Client.
+    # To give you more power, the client will include many plugins/modules
+    # to give you extra functionality. You can get extra help on all of the Includes.
+    class Client
+        Options['xmms-path' => ['unix:///tmp/xmms-ipc', 'the socket path x2c connects to']]
+        @@main = nil
+        # return reference to the first known client
+        def self.main
+            @@main || raise(Client::DisconnectedError,"no running xmms client found")
+        end
+
+        alias_method :__initialize, :initialize
+        # set up xmms Client, connect to deamonn and set main refrence
+        def initialize name='x2c'
+            __initialize(name)
+            @@main ||= self
+        end
+        alias_method :__connect, :connect
+        def handled_connect path
+            puts "...  connecting to daemon at #{path}"
+            __connect(path)
+            on_disconnect do
+                puts "\n...  lost connection to deamon. bye."
+                Kernel.exit 1
+            end
+        end
+        # try to connect to the daemon
+        def connect path=Options['xmms-path']
+            begin
+                handled_connect(path)
+            rescue ClientError => e
+                puts "\n...  #{path}: #{e}"
+                exit 1
+            end
+        end
+        alias_method :__shutdown, :quit
+        # shutdown the daemon
+        def shutdown
+            puts "\n...  shutting down daemon. bye."
+            __shutdown.val
+            exit 0
+        end
+        # exit the client
+        def quit; end
+        undef_method :quit
+    end
+end

data/x2c/core/collection.rb

@@ -0,0 +1,136 @@
+# Copyright by Daniel Waeber, see the LICENSE file for details
+
+require 'core/meta.rb'
+require 'core/resulteval.rb'
+
+# helpers for eassy collection manipulation
+module Xmms
+    # Collections represent a selection of music out of you MLib.
+    #
+    # you can create them with the normal constructor Collection.new,
+    # or use the special constructors Collection.new_<type>:
+    # * new_equals: a field equals a value
+    # * new_match: a field matches a value
+    # * new_greater: a field is greater as a value
+    # * new_smaller: a field is smaller as a value
+    # * new_smaller: a field is smaller as a value
+    # * new_has: the media has a certain field
+    # * new_queue: create a queue out of ids
+    # * new_idlist: create a queue out of ids
+    # * univierse: get all media
+    # * default: get the default base of collections
+    #
+    # there are some functions on collections, that extract infomation and give you new ghings
+    # * c.attributes and c.operrands give you the internal information
+    # * c.idlist return the internal idlist of queues, pshuffles and idlists
+    # * c.parent return the base of the collection
+    class Collection
+        class Operands
+            def empty?
+                self.to_a.empty?
+            end
+        end
+        class Attributes
+            # get Attribute as Hash: { field => value}
+            def field
+                {self["field"] => self["value"]}
+            end
+            # add the attrHash to the attributes list
+            def add attrHash
+                attrHash.each_pair do |k,v|
+                    self[k.to_s] = v.to_s
+                end
+            end
+        end
+        attr_accessor :name
+        # go through hole operands tree and call block with |collection, depth|
+        def tree_walk d=0, &block
+            yield(self, d)
+            self.operands.each do |o|
+                o.tree_walk(d+1, &block)
+            end
+        end
+        # tree_walk with accumulater
+        def tree_inject a=self, d=0, &block
+            a = yield(a,d,self) #unless a=self
+            self.operands.each do |o|
+                a = o.tree_inject(a,d+1,&block)
+            end;a
+        end
+
+        # return an attribute
+        def [] field
+            attributes[field]
+        end
+        # set an attribute
+        def []= field, val
+            self.name ||= val
+            attributes[field]= val
+        end
+        # return the default base collection for new collections
+        def self.default
+            universe
+        end
+
+        # create pshuffle out of the collection
+        def pshuffle
+            Collection.new_pshuffle(self)
+        end
+        # create queue out of the collection
+        def queue
+            Collection.new_queue(self.list.ids)
+        end
+        # get the parent of the collection, eg. the collection this one is based on
+        def parent
+            operands.find{true}
+        end
+
+        # construct new constructor, used to define all of the new_<type> functions
+        def self.new_constructor ref, hash
+            hash.each_pair do |n,t|
+                module_eval <<-EOE
+                def self.#{n.to_s} *args
+                    u = args.first.is_a?(Collection) ? args.shift : Collection.default
+                    self.#{ref.to_s}(#{t},u,*args)
+                end
+                EOE
+            end
+        end
+        # create a new list (queue or idlist)
+        def self.new_list type, base, ids
+            ids = ids.ids if ids.is_a?(Songlist)
+            c = Collection.new(type)
+            c.name = "#{base.name}:"
+            c.idlist = ids
+            return c
+        end
+        # create a new selection, eg. equals, less, ... 
+        # type is by default equals and the base of the list is the default one
+        # and an attribute has of type :field => :value, ...
+        def self.new_selection type, base, hash
+            hash.each_pair do|f,v|
+                c = Collection.new(type) 
+                c.name ||= "#{base.name+'.' if base.name}#{v}"
+                c.operands.push base
+                c.attributes.add(:field => f, :value =>v)
+                base = c
+            end;base
+        end
+
+        # create a pshuffle out of base, if base is a hash, create an new_equals
+        def self.new_pshuffle base=Collection.default
+            base = Collection.new_equals(base) if base.is_a? Hash
+            c = Collection.new(TYPE_PARTYSHUFFLE)
+            c.name = "#{base.name}%"
+            c.operands.push(base)
+            return c
+        end
+        # create new_equals, new_has, new_greater and new_smaller constructors
+        new_constructor :new_selection, 
+            :new_equals => TYPE_EQUALS, :new_match => TYPE_MATCH, :new_has => TYPE_HAS,
+            :new_greater => TYPE_GREATER, :new_smaller => TYPE_SMALLER
+        # create new_queue and new_idlist constructors
+        new_constructor :new_list,
+            :new_queue => TYPE_QUEUE, :new_idlist => TYPE_IDLIST
+    end
+end

data/x2c/core/configure.rb

@@ -0,0 +1,43 @@
+# interface for client configuration. it will load config.
+module Xmms
+    # don't quit on excetions in user code
+    def self.save_call
+        begin
+            yield
+        rescue Exception => e
+            puts "!!  check your config: #{e}"
+            puts "!!      "+e.backtrace.format("!!      ")
+        end
+    end
+    class Client
+        # edit you config file
+        def configure editor=ENV['EDITOR']||'vi'
+            system "#{editor} #{File.join(X2C_CONF,'config.rb')}"
+        end
+        # copy config into userconfdir
+        def setup
+            src = File.join(X2C_ROOT,'config.rb')
+            [`mkdir #{X2C_CONF} 2>&1`+
+             `mkdir #{File.join(X2C_CONF,'plug')} 2>&1`+
+             `cp #{src} #{X2C_CONF} 2>&1`+
+             "created confdir #{X2C_CONF} with the files",
+             `ls #{X2C_CONF} 2>&1`.split.map{|n| '> '+n}]
+        end
+        # empty methods that can be overwritten
+        def pre_connect; end
+        def post_connect; end
+        def welcome; end
+    end
+    begin
+        require File.join(X2C_CONF,'config.rb') 
+    rescue LoadError => l
+        if l.message =~ /#{File.join(X2C_CONF,'config.rb')}/
+            require 'config.rb'
+            require 'plug/tutorial.rb'
+        else
+            require 'config.rb'
+            puts "!!  check your config: #{l}"
+            puts "!!      "+l.backtrace.format("!!      ")
+        end
+    end
+end

data/x2c/core/meta.rb

@@ -0,0 +1,77 @@
+# Copyright by Daniel Waeber, see the LICENSE file for details
+# some metaprogrammming stuff
+module Help
+    @@ignore ||= Hash.new
+    def self.ignore klass, hash
+        @@ignore[klass] = (@@ignore[klass] || Hash.new).merge hash
+    end
+end
+
+def shortcut  new, old
+    Help.ignore(self, new.to_sym => :skip)
+    class_eval <<-EVAL
+        def #{new} *args, &block
+            #{old} *args, &block
+        end
+    EVAL
+end
+def alias_forward new, target, old=new
+    if target.is_a?(Symbol)
+        Help.ignore(self,
+            new => {target.to_sym => :over})
+        define_method(new) do |*args|
+            send(target).send(old,*args)
+        end
+    else
+        Help.ignore(self, new => {})
+        define_method(new) do |*args|
+            target.send(old, *args)
+        end
+    end
+end
+
+def dynamic_forward target
+    respond = "__respond_to_#{target}?"
+    methods = "__methods_#{target}"
+    missing = "__method_missing_#{target}"
+    Help.ignore(self, 
+        :method_missing => {respond.to_sym => :over, 
+                            target.to_sym => :over,
+                            missing.to_sym => :skip})
+    Help.ignore(Kernel, respond.to_sym => :over)
+    class_eval <<-EVAL
+        alias_method :#{respond}, :respond_to?
+        alias_method :#{methods}, :methods
+        def respond_to? *args
+            #{respond}(*args) || #{target}.respond_to?(*args)
+        end
+        def methods
+            #{methods} + #{target}.methods
+        end
+        alias_method :#{missing}, :method_missing
+        def method_missing id, *args, &block
+            if #{respond}(id)
+                #{missing}(id,*args,&block)
+            else
+                #{target}.send(id,*args,&block)
+            end
+        end
+    EVAL
+end
+
+def after_method_hook id, &block
+    oid = "__#{id}".to_sym
+    alias_method oid, id
+    define_method id do |*args|
+        block.call(send(oid,*args))
+    end
+end
+def before_method_hook id, &block
+    oid = "__#{id}".to_sym
+    alias_method oid, id
+    define_method id do |*args|
+        catch(:nocall) do
+            send(oid, *block.call(*args))
+        end
+    end
+end