linebook 0.7.0 → 0.8.0

data/lib/linebook/os/linux/utilities.rb

@@ -0,0 +1,226 @@
+# Generated by Linecook
+
+module Linebook
+  module Os
+    module Linux
+      module Utilities
+        # Returns true if the group exists as determined by checking /etc/group.
+        def group?(name)
+          #  grep "^<%= name %>:" /etc/group >/dev/null 2>&1
+          write "grep \"^"; write(( name ).to_s); write ":\" /etc/group >/dev/null 2>&1"
+          chain_proxy
+        end
+        
+        def _group?(*args, &block) # :nodoc:
+          str = capture_str { group?(*args, &block) }
+          str.strip!
+          str
+        end
+        
+        # Create a new group.
+        # {[Spec]}[http://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/groupadd.html]
+        def groupadd(group, options={})
+          execute 'groupadd', group, options
+          chain_proxy
+        end
+        
+        def _groupadd(*args, &block) # :nodoc:
+          str = capture_str { groupadd(*args, &block) }
+          str.strip!
+          str
+        end
+        
+        # Delete a group.
+        # {[Spec]}[http://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/groupdel.html]
+        def groupdel(group)
+          execute 'groupdel', group
+          chain_proxy
+        end
+        
+        def _groupdel(*args, &block) # :nodoc:
+          str = capture_str { groupdel(*args, &block) }
+          str.strip!
+          str
+        end
+        
+        # Modify a group.
+        # {[Spec]}[http://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/groupmod.html]
+        def groupmod(group, options={})
+          execute 'groupmod', group, options
+          chain_proxy
+        end
+        
+        def _groupmod(*args, &block) # :nodoc:
+          str = capture_str { groupmod(*args, &block) }
+          str.strip!
+          str
+        end
+        
+        # Display a group.
+        # {[Spec]}[http://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/groups.html]
+        def groups(user)
+          execute 'groups', user
+          chain_proxy
+        end
+        
+        def _groups(*args, &block) # :nodoc:
+          str = capture_str { groups(*args, &block) }
+          str.strip!
+          str
+        end
+        
+        # Compress or expand files.
+        # {[Spec]}[http://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/gzip.html]
+        def gzip(*files)
+          execute 'gzip', *files
+          chain_proxy
+        end
+        
+        def _gzip(*args, &block) # :nodoc:
+          str = capture_str { gzip(*args, &block) }
+          str.strip!
+          str
+        end
+        
+        # Show or set the system's host name.
+        # {[Spec]}[http://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/hostname.html]
+        def hostname(name=nil) 
+          execute 'hostname', name
+          chain_proxy
+        end
+        
+        def _hostname(*args, &block) # :nodoc:
+          str = capture_str { hostname(*args, &block) }
+          str.strip!
+          str
+        end
+        
+        # Copy files and set attributes.
+        # {[Spec]}[http://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/install.html]
+        def install(source, dest, options={})
+          execute 'install', source, dest, options
+          chain_proxy
+        end
+        
+        def _install(*args, &block) # :nodoc:
+          str = capture_str { install(*args, &block) }
+          str.strip!
+          str
+        end
+        
+        # Generate or check MD5 message digests.
+        # {[Spec]}[http://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/md5sum.html]
+        def md5sum(*files) 
+          execute 'md5sum', *files
+          chain_proxy
+        end
+        
+        def _md5sum(*args, &block) # :nodoc:
+          str = capture_str { md5sum(*args, &block) }
+          str.strip!
+          str
+        end
+        
+        # Make temporary file name (unique)
+        # {[Spec]}[http://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/mktemp.html]
+        def mktemp(template, options={})
+          execute 'mktemp', template, options
+          chain_proxy
+        end
+        
+        def _mktemp(*args, &block) # :nodoc:
+          str = capture_str { mktemp(*args, &block) }
+          str.strip!
+          str
+        end
+        
+        # Switches to the specified user for the duration of a block.  The current ENV
+        # and pwd are preserved.
+        # {[Spec]}[http://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/su.html]
+        def su(user='root', options={})
+          path = capture_script(options) do
+            functions.each_value do |function|
+              writeln function
+            end
+            yield
+          end
+          execute 'su', user, path, :m => true
+          chain_proxy
+        end
+        
+        def _su(*args, &block) # :nodoc:
+          str = capture_str { su(*args, &block) }
+          str.strip!
+          str
+        end
+        
+        # File archiver. {[Spec]}[http://pubs.opengroup.org/onlinepubs/007908799/xcu/tar.html]
+        def tar(key, *files)
+          execute 'tar', key, files
+          chain_proxy
+        end
+        
+        def _tar(*args, &block) # :nodoc:
+          str = capture_str { tar(*args, &block) }
+          str.strip!
+          str
+        end
+        
+        # Returns true if the user exists as determined by id.
+        def user?(name)
+          #  id <%= quote(name) %> >/dev/null 2>&1
+          write "id "; write(( quote(name) ).to_s); write " >/dev/null 2>&1"
+          chain_proxy
+        end
+        
+        def _user?(*args, &block) # :nodoc:
+          str = capture_str { user?(*args, &block) }
+          str.strip!
+          str
+        end
+        
+        # Create a new user or update default new user information.
+        # {[Spec]}[http://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/useradd.html]
+        def useradd(login, options={}) 
+          execute 'useradd', login, options
+          chain_proxy
+        end
+        
+        def _useradd(*args, &block) # :nodoc:
+          str = capture_str { useradd(*args, &block) }
+          str.strip!
+          str
+        end
+        
+        # Delete a user account and related files.
+        # {[Spec]}[http://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/userdel.html]
+        def userdel(login, options={}) 
+          # TODO - look into other things that might need to happen before:
+          # * kill processes belonging to user
+          # * remove at/cron/print jobs etc. 
+          execute 'userdel', login, options
+          chain_proxy
+        end
+        
+        def _userdel(*args, &block) # :nodoc:
+          str = capture_str { userdel(*args, &block) }
+          str.strip!
+          str
+        end
+        
+        # Modify a user account.
+        # {[Spec]}[http://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/usermod.html]
+        def usermod(login, options={})
+          execute 'usermod', login, options
+          chain_proxy
+        end
+        
+        def _usermod(*args, &block) # :nodoc:
+          str = capture_str { usermod(*args, &block) }
+          str.strip!
+          str
+        end
+      end
+    end
+  end
+end

data/lib/linebook/os/posix.rb

@@ -2,26 +2,33 @@
 
 module Linebook
   module Os
+    # Defines POSIX-compliant functionality, based on the {IEEE 1003.1-2008
+    # standard }[http://pubs.opengroup.org/onlinepubs/9699919799].  See the online
+    # documentation for:
+    #
+    # * {POSIX Shell Command Language
+    #   }[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/xcu_chap02.html]
+    # * {Special Built-in Utilities
+    #   }[http://pubs.opengroup.org/onlinepubs/9699919799/idx/sbi.html]
+    # * {Standard Utilties
+    #   }[http://pubs.opengroup.org/onlinepubs/9699919799/idx/utilities.html]
+    #
+    # In addition, the {Shell Hater's Handbook}[http://shellhaters.heroku.com/]
+    # provides a nice index of the relevant information.
+    #
     module Posix
-      # Returns true if the obj converts to a string which is whitespace or empty.
-      def blank?(obj)
-        # shortcut for nil...
-        obj.nil? || obj.to_s.strip.empty?
-      end
+      require 'linebook/os/posix/variable'
+      require 'linebook/os/posix/utilities'
+      include Utilities
       
-      # Encloses the arg in quotes if the arg is not quoted and is quotable. 
-      # Stringifies arg using to_s.
-      def quote(arg)
-        arg = arg.to_s
-        quoted?(arg) || !quote?(arg) ? arg : "\"#{arg}\""
+      # Returns "$0", the program name.
+      def program_name
+        Variable.new(0)
       end
       
-      # Returns true if the str is not an option (ie it begins with - or +), and is
-      # not already quoted (either by quotes or apostrophes).  The intention is to
-      # check whether a string _should_ be quoted.
-      def quote?(str)
-        c = str[0]
-        c == ?- || c == ?+ || quoted?(str) ? false : true
+      # Encloses the arg in quotes, unless already quoted (see quoted?).
+      def quote(str)
+        quoted?(str) ? str : "\"#{str}\""
       end
       
       # Returns true if the str is quoted (either by quotes or apostrophes).
@@ -29,15 +36,27 @@ module Linebook
         str =~ /\A".*"\z/ || str =~ /\A'.*'\z/ ? true : false
       end
       
+      # Encloses the arg in quotes unless the arg is an option or already quoted
+      # (see option? and quoted?).
+      def option_quote(str)
+        option?(str) ? str : quote(str)
+      end
+      
+      # Returns true if the str is an option (ie it begins with - or +).
+      def option?(str)
+        c = str[0]
+        c == ?- || c == ?+
+      end
+      
       # Formats a command line command.  Arguments are quoted. If the last arg is a
       # hash, then it will be formatted into options using format_options and
       # prepended to args.
-      def format_cmd(command, *args)
+      def command_str(command, *args)
         opts = args.last.kind_of?(Hash) ? args.pop : {}
         args.compact!
-        args.collect! {|arg| quote(arg) }
+        args.collect! {|arg| option_quote(arg.to_s) }
         
-        args = format_options(opts) + args
+        args = options_str(opts) + args
         args.unshift(command)
         args.join(' ')
       end
@@ -56,7 +75,7 @@ module Linebook
       # symbols) such that underscores are converted to dashes, ie :some_key =>
       # 'some-key'.  Note that options are sorted, such that short options appear
       # after long options, and so should 'win' given typical option processing.
-      def format_options(opts)
+      def options_str(opts)
         options = []
         
         opts.each do |(key, value)|
@@ -82,48 +101,66 @@ module Linebook
         options.sort
       end
       
-      # An array of functions defined for self.
+      # A hash of functions defined for self.
       def functions
-        @functions ||= []
+        @functions ||= {}
       end
       
       # Defines a function from the block.  The block content is indented and
-      # cleaned up some to make a nice function definition.  To avoid formatting,
-      # provide the body directly.
-      #
-      # A body and block given together raises an error. Raises an error if the
-      # function is already defined with a different body.
-      def function(name, body=nil)
-        if body && block_given?
-          raise "define functions with body or block"
-        end
-        
-        if body.nil?
-          str  = capture_str { indent { yield } }
-          body = "\n#{str.chomp("\n")}\n"
-        end
-        
-        function = "#{name}() {#{body}}"
+      # cleaned up some to make a nice function definition.
+      def function(name, method_name=name)
+        str = capture_str { indent { yield(*signature(Proc.new.arity)) } }
+        function = %{#{name}() {\n#{str.chomp("\n")}\n}}
         
-        if current = functions.find {|func| func.index("#{name}()") == 0 }
-          if current != function
+        if function?(name)
+          unless functions[name] == function
             raise "function already defined: #{name.inspect}"
           end
+        else
+          functions[name] = function
+          
+          if method_name
+            instance_eval %{
+              def self.#{method_name}(*args)
+                execute '#{method_name}', *args
+                chain_proxy
+              end
+            }
+          end
         end
         
-        functions << function
         writeln function
-        
         name
       end
       
-      # Returns true if the function is defined.
+      # Returns true if a function with the given name is defined.
       def function?(name)
-        declaration = "#{name}()"
-        functions.any? {|func| func.index(declaration) == 0 }
+        functions.has_key?(name)
       end
       
-      CHECK_STATUS = /(\s*(?:\ncheck_status.*?\n\s*)?)\z/
+      # Returns an array of positional variables for use as inputs to a function
+      # block.  Splat blocks are supported; the splat expression behaves like $*.
+      def signature(arity)
+        variables = Array.new(arity.abs) {|i| var(i+1) }
+        
+        if arity < 0
+          # This works for defaults...
+          # $(shift 1; echo ${*:-NONE})
+          # You can't do this:
+          # ${$(shift 1; echo $*):-NONE}
+          variables[-1] = "$(shift #{arity.abs - 1}; echo $*)"
+        end
+        
+        variables
+      end
+      
+      def var(name)
+        Variable.new(name)
+      end
+      
+      def trailer
+        /(\s*(?:\ncheck_status.*?\n\s*)?)\z/
+      end
       
       # Adds a redirect to append stdout to a file.
       def append(path=nil)
@@ -137,6 +174,22 @@ module Linebook
         str
       end
       
+      # Exit from for, while, or until loop.
+      # {[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_15]
+      def break_()
+        #  break
+        #  
+        write "break\n"
+      
+        chain_proxy
+      end
+      
+      def _break_(*args, &block) # :nodoc:
+        str = capture_str { break_(*args, &block) }
+        str.strip!
+        str
+      end
+      
       # Adds a check that ensures the last exit status is as indicated. Note that no
       # check will be added unless check_status_function is added beforehand.
       def check_status(expect_status=0, fail_status='$?')
@@ -157,9 +210,20 @@ module Linebook
         str
       end
       
-      # Adds the check status function.
+      # Defines the check status function.
       def check_status_function()
-        function 'check_status', ' if [ $2 -ne $1 ]; then echo "[$2] $0:${4:-?}"; exit $3; else return $2; fi '
+        function('check_status', nil) do |expected, actual, error, message|
+          message.default = '?'
+          
+          if_ actual.ne(expected) do
+            writeln %{echo [#{actual}] #{program_name}:#{message}}
+            exit_ error
+          end
+          
+          else_ do
+            return_ actual
+          end
+        end
         chain_proxy
       end
       
@@ -184,18 +248,80 @@ module Linebook
         str
       end
       
-      # Executes a command and checks the output status.  Quotes all non-option args
+      # Continue for, while, or until loop.
+      # {[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_17]
+      def continue_()
+        #  continue
+        #  
+        write "continue\n"
+      
+        chain_proxy
+      end
+      
+      def _continue_(*args, &block) # :nodoc:
+        str = capture_str { continue_(*args, &block) }
+        str.strip!
+        str
+      end
+      
+      # Chains to if_ to make an else-if statement.
+      def elif_(expression)
+        unless match = rewrite(/(\s+)(fi\s*)/)
+          raise "elif_ used outside of if_ statement"
+        end
+        #  <%= match[1] %>
+        #  elif <%= expression %>
+        #  then
+        #  <% indent { yield } %>
+        #  <%= match[2] %>
+        write(( match[1] ).to_s)
+        write "elif "; write(( expression ).to_s); write "\n"
+        write "then\n"
+        indent { yield } 
+        write(( match[2] ).to_s)
+        chain_proxy
+      end
+      
+      def _elif_(*args, &block) # :nodoc:
+        str = capture_str { elif_(*args, &block) }
+        str.strip!
+        str
+      end
+      
+      # Chains to if_ or unless_ to make an else statement.
+      def else_()
+        unless match = rewrite(/(\s+)(fi\s*)/)
+          raise "else_ used outside of if_ statement"
+        end
+        #  <%= match[1] %>
+        #  else
+        #  <% indent { yield } %>
+        #  <%= match[2] %>
+        write(( match[1] ).to_s)
+        write "else\n"
+        indent { yield } 
+        write(( match[2] ).to_s)
+        chain_proxy
+      end
+      
+      def _else_(*args, &block) # :nodoc:
+        str = capture_str { else_(*args, &block) }
+        str.strip!
+        str
+      end
+      
+      # Executes a command and checks the output status. Quotes all non-option args
       # that aren't already quoted. Accepts a trailing hash which will be transformed
       # into command line options.
       def execute(command, *args)
         if chain?
-          rewrite(CHECK_STATUS)
+          rewrite(trailer)
           write ' | '
         end
-        #  <%= format_cmd(command, *args) %>
+        #  <%= command_str(command, *args) %>
         #  
         #  <% check_status %>
-        write(( format_cmd(command, *args) ).to_s)
+        write(( command_str(command, *args) ).to_s)
         write "\n"
         check_status 
         chain_proxy
@@ -207,17 +333,26 @@ module Linebook
         str
       end
       
-      # Exports a variable.
-      def export(key, value)
-        #  export <%= key %>=<%= quote(value) %>
+      # Cause the shell to exit.
+      # {[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_21]
+      def exit_(status=nil)
+        #  <% if status.nil? %>
+        #  exit
+        #  <% else %>
+        #  exit <%= status %>
+        #  <% end %>
         #  
-        write "export "; write(( key ).to_s); write "="; write(( quote(value) ).to_s); write "\n"
+        if status.nil? 
+        write "exit\n"
+        else 
+        write "exit "; write(( status ).to_s); write "\n"
+        end 
       
         chain_proxy
       end
       
-      def _export(*args, &block) # :nodoc:
-        str = capture_str { export(*args, &block) }
+      def _exit_(*args, &block) # :nodoc:
+        str = capture_str { exit_(*args, &block) }
         str.strip!
         str
       end
@@ -240,7 +375,7 @@ module Linebook
       #   outdent     add '-' before the delimiter
       #   quote       quotes the delimiter
       def heredoc(options={})
-        tail = chain? ? rewrite(CHECK_STATUS) {|m| write ' '; m[1].lstrip } : nil
+        tail = chain? ? rewrite(trailer) {|m| write ' '; m[1].lstrip } : nil
         
         unless options.kind_of?(Hash)
           options = {:delimiter => options}
@@ -255,11 +390,13 @@ module Linebook
         #  <%= delimiter %><% end %>
         #  
         #  <%= tail %>
+        #  
         write "<<"; write(( options[:outdent] ? '-' : ' ').to_s); write(( options[:quote] ? "\"#{delimiter}\"" : delimiter ).to_s);  outdent(" # :#{delimiter}:") do ; write "\n"
         yield 
         write(( delimiter ).to_s);  end 
         write "\n"
         write(( tail ).to_s)
+      
         chain_proxy
       end
       
@@ -297,7 +434,7 @@ module Linebook
         source = source.nil? || source.kind_of?(Fixnum) ? source : "#{source} "
         target = target.nil? || target.kind_of?(Fixnum) ? "&#{target}" : " #{target}"
         
-        match = chain? ? rewrite(CHECK_STATUS) : nil
+        match = chain? ? rewrite(trailer) : nil
         write " #{source}#{redirection}#{target}"
         write match[1] if match
         chain_proxy
@@ -309,21 +446,45 @@ module Linebook
         str
       end
       
-      # Sets the options to on (true) or off (false) as specified.
-      def set(options)
-        #  <% options.keys.sort_by {|opt| opt.to_s }.each do |opt| %>
-        #  set <%= options[opt] ? '-' : '+' %>o <%= opt %>
+      # Return from a function.
+      # {[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_24]
+      def return_(status=nil)
+        #  <% if status.nil? %>
+        #  return
+        #  <% else %>
+        #  return <%= status %>
         #  <% end %>
         #  
-        options.keys.sort_by {|opt| opt.to_s }.each do |opt| 
-        write "set "; write(( options[opt] ? '-' : '+' ).to_s); write "o "; write(( opt ).to_s); write "\n"
+        if status.nil? 
+        write "return\n"
+        else 
+        write "return "; write(( status ).to_s); write "\n"
         end 
       
         chain_proxy
       end
       
-      def _set(*args, &block) # :nodoc:
-        str = capture_str { set(*args, &block) }
+      def _return_(*args, &block) # :nodoc:
+        str = capture_str { return_(*args, &block) }
+        str.strip!
+        str
+      end
+      
+      # Write a comment to delimit sections.  The comment takes the format:
+      # 
+      #   #### name ###
+      def section(name="")
+        n = (78 - name.length)/2
+        str = "-" * n
+        #  #<%= str %><%= name %><%= str %><%= "-" if name.length % 2 == 1 %>
+        #  
+        write "#"; write(( str ).to_s); write(( name ).to_s); write(( str ).to_s); write(( "-" if name.length % 2 == 1 ).to_s); write "\n"
+      
+        chain_proxy
+      end
+      
+      def _section(*args, &block) # :nodoc:
+        str = capture_str { section(*args, &block) }
         str.strip!
         str
       end
@@ -352,19 +513,25 @@ module Linebook
         str
       end
       
-      # Unsets a list of variables.
-      def unset(*keys)
-        #  <% keys.each do |key| %>
-        #  unset <%= key %>
-        #  <% end %>
-        keys.each do |key| 
-        write "unset "; write(( key ).to_s); write "\n"
-        end 
+      # Executes the block until the expression evaluates to zero.
+      def until_(expression)
+        #  until <%= expression %>
+        #  do
+        #  <% indent { yield } %>
+        #  done
+        #  
+        #  
+        write "until "; write(( expression ).to_s); write "\n"
+        write "do\n"
+        indent { yield } 
+        write "done\n"
+        write "\n"
+      
         chain_proxy
       end
       
-      def _unset(*args, &block) # :nodoc:
-        str = capture_str { unset(*args, &block) }
+      def _until_(*args, &block) # :nodoc:
+        str = capture_str { until_(*args, &block) }
         str.strip!
         str
       end
@@ -385,6 +552,29 @@ module Linebook
         str.strip!
         str
       end
+      
+      # Executes the block while the expression evaluates to zero.
+      def while_(expression)
+        #  while <%= expression %>
+        #  do
+        #  <% indent { yield } %>
+        #  done
+        #  
+        #  
+        write "while "; write(( expression ).to_s); write "\n"
+        write "do\n"
+        indent { yield } 
+        write "done\n"
+        write "\n"
+      
+        chain_proxy
+      end
+      
+      def _while_(*args, &block) # :nodoc:
+        str = capture_str { while_(*args, &block) }
+        str.strip!
+        str
+      end
     end
   end
 end