grassgis 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c0fd89fb91b60e769c7f1a29f2a683525a162480
-  data.tar.gz: ab57d26849db6fdbada05be7803b3c67df94f0ff
+  metadata.gz: ecfff7260f29f4ce2f8add71b7ddba2160855b38
+  data.tar.gz: 263eacdcc9a5abe048d75855c226c583add5a472
 SHA512:
-  metadata.gz: b35d3856bc5b77a5fd8eb104db5cddb113140841e59b840bfa99dc74625fa4cc3e97efbce586536b8005756b5ef4d894121d35f5b092258620c702d4e78c12fd
-  data.tar.gz: 4cd8093c0acb3c25556e1cefc01f0642c9220f76a7e17c3fe7c2b60a034904519d821b090bfc9ecb9f80196721bb8a87a6a5707dda20f3533115eb3cf65c064a
+  metadata.gz: c8a33caff0aa903fe0e5e86676b345b57db4028d8e309de3e8ef360a303473056325abad6c2543d46c5381d12dae53b2481eb54d1825a62b5ba8e2cf5d7bf53e
+  data.tar.gz: 15598756b12558e632c200efbaf660fd3e030e17011d89335f57fb4b79b81b033b2c5b573d81c1af07d6a1289782499280ec889f28bb346c5a6501f9bec09ae1

data/README.md

@@ -5,6 +5,34 @@
 
 Support for scripting GRASS with Ruby.
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Configuration](#configuration)
+  - [Running a GRASS Session](#running-a-grass-session)
+  - [Creating new locations and mapsets](#creating-new-locations-and-mapsets)
+  - [History](#history)
+  - [Options](#options)
+    - [Echo](#echo)
+    - [Errors](#errors)
+    - [Logging](#logging)
+  - [Technicalities](#technicalities)
+    - [Session scopes](#session-scopes)
+    - [Invalid commands](#invalid-commands)
+- [Helper methods](#helper-methods)
+  - [Examples](#examples)
+    - [1. Map existence](#1-map-existence)
+    - [2. Information as Hashes](#2-information-as-hashes)
+    - [3. Average angle](#3-average-angle)
+- [Roadmap](#roadmap)
+  - [GRASS cooking DSL](#grass-cooking-dsl)
+- [Contributing](#contributing)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -113,10 +141,212 @@ d.erase.run
 g.list.run
 ```
 
+### Creating new locations and mapsets
+
+To create a new location and/or mapset, open a session to it
+and use a `:create` parameter like this:
+
+```ruby
+options = configuration.merge(
+  location: 'new_location',
+  mapset: 'new_mapset',
+  create: {
+    epsg: 4326               # coordinate system for the new location
+    limits: [-5, 30, 5, 50], # optional E, S, W, N limits
+    res: 2                   # optional resolution
+  }
+)
+GrassGis.session options do
+  g.region '-p'
+  puts output
+end
+```
+
+Use `nil` or `PERMANENT` for the mapset to avoid creating a new mapset.
+
+Existing locations or mapsets are not changed.
+
+### History
+
+The return value of a GRASS command invocation inside a session is
+a `SysCmd::Command`
+(see the [sys_cmd gem](https://github.com/jgoizueta/sys_cmd)).
+
+```ruby
+GrassGis.session configuration do+
+  cmd = g.region '-p'
+  puts cmd.output # command output is kept in the Command object
+  puts cmd.status_value # 0 for success
+end
+```
+
+You don't need to assign commands to variables as in the example
+to access them, because they're all kept in an array accesible
+through the `history` method of the session:
+
+```ruby
+GrassGis.session configuration do+
+  r.info 'slope'
+  g.region '-p'
+  puts history.size       # 2
+  puts history[-1].output # output of g.region
+  puts history[-2].output # output of r.info
+end
+```
+
+The last executed command (`history[-1]`) is also accessible through
+the `last` method and its output through `output`:
+
+```ruby
+GrassGis.session configuration do+
+  r.info 'slope'
+  g.region '-p'
+  puts output # output of g.region (same as last.output)
+  puts last.status_value # result status of g.region
+end
+```
+
+### Options
+
+By default the commands executed in a session are echoed to standard output
+(just the command, not its output) and error return status causes
+an exception to be raised.
+
+This behaviour can be changed with some options:
+
+#### Echo
+
+Pass `false` as the `:echo` option it you don't want to output
+command names and `:output` if you want to output both
+the command name and its output.
+
+```ruby
+GrassGis.session configuration.merge(echo: false) do
+  # Command names not echoed now ...
+end
+
+GrassGis.session configuration.merge(echo: :output) do
+  # Command names and its output echoed ...
+end
+```
+
+#### Errors
+
+To avoid raising exceptions when commands return an error status you can pass
+`:quiet` to the `:errors` option. In that case the `error?` method of the
+session can be used to check if the previous messatge returned an error status;
+`error_info` to get its error message and the status of the command
+of the command can be obtained through the `last` command method.
+
+```ruby
+GrassGis.session configuration.merge(errors: :quiet) do
+  r.surf.rst 'randpts', elev: 'rstdef', zcol: 'value'
+  if error?
+    puts "Last command didn't go well..."
+    puts "It returned the code: #{last.status_value}"
+    puts "Here's what it said about the problem:"
+    puts error_info
+  end
+end
+```
+
+With the `:quiet` option errors during command execution are not raised,
+but if a problem prevents the command from being executed (e.g. the
+module does not exist) an exception is still generated. This exception
+can be avoided too, with the `:silent` option, intended for tests and
+debugging.
+
+Passing the `:console` value to the `:errors` option is like `:quiet`,
+with the additional effect of relaying the command standard error output
+to the error output of the script.
+
+#### Logging
+
+With the `:log` option you can specify the name of a file
+where to record the commands executed and its output.
+
+### Technicalities
+
+#### Session scopes
+
+In a session block, the Ruby `self` object is altered to
+refer to a `GrassGis::Context` object. That means that in addition
+to the enclosing `self`, any instance variables of the enclosing
+scope are not directly available. This may cause some surprises
+but is easy to overcome.
+
+```ruby
+@value = 10
+GrassGis.session configuration do
+  puts @value # nil!
+end
+```
+
+A possible workaround is to assign instance variables that we need
+in the session to local variables:
+
+```ruby
+@value = 10
+value = @value
+GrassGis.session configuration do
+  puts value # 10
+end
+```
+
+To avoid defining these variables you can pass a `:locals` Hash
+in the configuration to define values that you need to access
+in the session (but you won't be able to assign to them, because
+they're not local variables!)
+
+```ruby
+@value = 10
+
+GrassGis.session configuration.merge(locals: { value: @value }) do
+  puts value # 10
+  value = 11 # don't do this: you're creating a local in the session
+end
+```
+
+A different approach is prevent the session block from using a special
+`self` by defining a parameter to the block. This parameter will have
+the value of a `GrassGis::Context` which you'll need to explicitly use
+to execute any commands:
+
+```ruby
+@value = 10
+GrassGis.session configuration do |grass|
+  puts @value # 10
+  grass.g.region res: 10 # now you need to use the object to issue commans
+end
+```
+
+#### Invalid commands
+
+Currently the generation of GRASS commands inside a session is
+implemented in a versy simple way which allows to generate any command
+name even if it is invalid or does not exist. This has the advantage
+of supporting any version of GRASS, but doesn't allow for early
+detection of invalid commands (e.g. due to typos) or invalid command
+parameters.
+
+```ruby
+GrassGis.session configuration do |grass|
+  g.regoin res: 10     # Oops (runtime error)
+  g.anything.goes.run  # another runtime error
+end
+```
+
+If the command generated does not exist a runtime `ENOENT` exception will
+occur.
+
+If the command exists, then if parameters are not valid, the command
+will execute but will return an error status. This will be handled
+as explaned above.
+
 ## Helper methods
 
 When writing a non-trivial program you'll probably
-find you want to define methods to avoid innecesary repetition.
+find you want to define methods to avoid unnecessary repetition.
 
 Let's see how you can call methdos from your session and be
 able to execute GRASS commands from the method in the context of the session.
@@ -125,7 +355,7 @@ Inside a session, `self` refers to an object of class
 `GrassGis::Context` which represents the current GRASS session.
 
 You can invoke grass commands directly on this object, so, if you pass
-this object aroung you can use it to execute GRASS commands:
+this object around you can use it to execute GRASS commands:
 
 ```ruby
 def helper_method(grass)
@@ -195,8 +425,7 @@ GrassGis.session configuration do
 end
 ```
 
-
-### 2. Information as Hashes
+#### 2. Information as Hashes
 
 Following methods show how to obtain information about a raster map
 and the current region as a Hash:
@@ -229,7 +458,7 @@ def region_res(grass)
 end
 ```
 
-### 3. Average angle
+#### 3. Average angle
 
 Let's assume we have a raster map `aspect` which is
 a direction angle (i.e. a cyclic value from 0 to 360).
@@ -291,91 +520,8 @@ GrassGis.session configuration do
 end
 ```
 
-### Options
-
-TODO: Explain options for error handling, echoing, logging, ...
-
-### Technicalities
-
-#### Session scopes
-
-In a session block, the Ruby `self` object is altered to
-refer to a `GrassGis::Context` object. That means that in addition
-to the enclosing `self`, any instance variables of the enclosing
-scope are not directly available. This may cause some surprises
-but is easy to overcome.
-
-```ruby
-@value = 10
-GrassGis.session configuration do
-  puts @value # nil!
-end
-```
-
-A possible workaround is to assign instance variables that we need
-in the session to local variables:
-
-```ruby
-@value = 10
-value = @value
-GrassGis.session configuration do
-  puts value # 10
-end
-```
-
-To avoid defining these variables you can pass a `:locals` Hash
-in the configuration to define values that you need to access
-in the session (but you won't be able to assign to them, because
-they're not local variables!)
-
-```ruby
-@value = 10
-
-GrassGis.session configuration.merge(locals: { value: @value }) do
-  puts value # 10
-  value = 11 # don't do this: you're creating a local in the session
-end
-```
-
-A different approach is prevent the session block from using a special
-`self` by defining a parameter to the block. This parameter will have
-the value of a `GrassGis::Context` which you'll need to explicitly use
-to execute any commands:
-
-```ruby
-@value = 10
-GrassGis.session configuration do |grass|
-  puts @value # 10
-  grass.g.region res: 10 # now you need to use the object to issue commans
-end
-```
-
-#### Invalid commands
-
-Currently the generation of GRASS commands inside a session is
-implemented in a versy simple way which allows to generate any command
-name even if it is invalid or does not exist. This has the advantage
-of supporting any version of GRASS, but doesn't allow for early
-detection of invalid commands (e.g. due to typos) or invalid command
-parameters.
-
-```ruby
-GrassGis.session configuration do |grass|
-  g.regoin res: 10     # Oops (runtime error)
-  g.anything.goes.run  # another runtime error
-end
-```
-
-If the command generated does not exist a runtime `ENOENT` exception will
-occur.
-
-If the command exists, then if parameters are not valid, the command
-will execute but will return an error status. This will be handled
-as explaned above.
-
 ## Roadmap
 
-* Methods to create new locations and mapsets.
 * Change Module to define explicitly available GRASS commands instead of
   accepting anything with `method_missing`. Declare commands with permitted
   arguments and options, etc.
@@ -385,6 +531,8 @@ as explaned above.
   - Methods to check if maps exist
   - Methods that return information as objects (arrays, hashes), e.g.
     values returned by r.what, the current region, etc.
+  - Methods that execute operations in a GRASS-version independent
+    manner (higher level, version independent interface to modules).
 
 ### GRASS cooking DSL
 

data/lib/grassgis/context.rb

@@ -7,6 +7,7 @@ module GrassGis
     REQUIRED_CONFIG = [:gisbase, :location]
 
     def initialize(config)
+      # TODO: raise error unless required parameters are present
       # apply configuration defaults
       config[:gisdbase] ||= File.join(ENV['HOME'], 'grassdata')
       config[:mapset]  ||= ENV['USER']
@@ -82,16 +83,12 @@ module GrassGis
     end
 
     def allocate
-      @gisrc = Tempfile.new('gisrc')
-      @gisrc.puts "LOCATION_NAME: #{@config[:location]}"
-      @gisrc.puts "GISDBASE: #{@config[:gisdbase]}"
-      @gisrc.puts "MAPSET: #{@config[:mapset]}"
-      @gisrc.puts "GUI: #{@config[:gui]}"
-      @gisrc.close
-
       @original_env = {}
 
-      replace_var 'GISRC', @gisrc.path
+      mapset = Mapset.new(self)
+      actual_mapset = mapset.exists? ? mapset.to_s : 'PERMANENT'
+      set_gisrc @config.merge(mapset: actual_mapset)
+
       replace_var 'GISBASE', @config[:gisbase]
       replace_var 'GRASS_VERSION', @config[:version]
       replace_var 'GRASS_MESSAGE_FORMAT', @config[:message_format].to_s
@@ -123,8 +120,10 @@ module GrassGis
     def dispose
       @gisrc.unlink if @gisrc
       @gisrc = nil
-      @original_env.each do |var, value|
-        ENV[var] = value
+      if @original_env
+        @original_env.each do |var, value|
+          ENV[var] = value
+        end
       end
       @original_env = {}
     end
@@ -177,11 +176,7 @@ module GrassGis
       if @config[:echo]
         puts cmd.to_s(with_input: false)
       end
-      log_file = @config[:log] || @config[:history]
-      if log_file
-        log_timestamp log_file
-        log log_file, cmd.to_s(with_input: true)
-      end
+      log("Execute command:") { cmd.to_s(with_input: true) }
       unless dry?
         cmd.run error_output: :separate
       end
@@ -192,15 +187,82 @@ module GrassGis
       cmd
     end
 
+    def log(text, options = {})
+      log_file = logging_file
+      if log_file
+        timestamp = Time.now.strftime("%H:%M:%S")
+        msg = "#{timestamp} - #{text}"
+        log_message log_file, msg
+        indented_text = options[:indented]
+        indented_text ||= yield if !indented_text && block_given?
+        if indented_text
+          log_message log_file, indented_text, indentation: '  '
+        end
+      end
+    end
+
+    def logging?
+      !!logging_file
+    end
+
+    # This should be used instead of g.mapset to avoid problems under Windows
+    def change_mapset(new_mapset)
+      log "Change mapset to #{new_mapset}"
+      set_gisrc @config.merge(mapset: new_mapset)
+    end
+
+    def log_header
+      log_file = logging_file
+      if log_file
+        msg = "Start GrassGis Session [#{Time.now}]"
+        log_message log_file, "# #{'='*msg.size}"
+        log_message log_file, "# #{msg}"
+        log_message log_file, configuration.to_yaml, indentation: '# '
+        log_message log_file, "# #{'-'*msg.size}"
+      end
+    end
+
+    # Version of GRASS in use in the session, as a comparable version
+    # object.
+    #
+    # Example of use:
+    #
+    #     GrassGis.session configuration do
+    #       if grass_version >= GrassGis.version('7.0.0')
+    #         r.relief input: 'dem', output: 'relief'
+    #       else
+    #         r.shaded.relief map: 'dem', shadedmap: 'relief'
+    #       end
+    #     end
+    #
+    def grass_version
+      Gem::Version.new @config[:version]
+    end
+
   private
 
-    def log_timestamp(file)
-      log file, Time.now
+    def set_gisrc(options)
+      @old_gisrc = @gisrc
+      @gisrc = Tempfile.new('gisrc')
+      @gisrc.puts "GISDBASE: #{options[:gisdbase]}"      if options[:gisdbase]
+      @gisrc.puts "LOCATION_NAME: #{options[:location]}" if options[:location]
+      @gisrc.puts "MAPSET: #{options[:mapset]}"          if options[:mapset]
+      @gisrc.puts "GUI: #{options[:gui]}"                if options[:gui]
+      @gisrc.close
+      replace_var 'GISRC', @gisrc.path
+      @old_gisrc.unlink if @old_gisrc
     end
 
-    def log(file, message)
+    def logging_file
+      @config[:log] || @config[:history]
+    end
+
+    def log_message(file, message, options = {})
       if file && message
         File.open(file, 'a') do |log_file|
+          if options[:indentation]
+            message = message.gsub(/^/, options[:indentation])
+          end
           log_file.puts message
         end
       end
@@ -214,7 +276,7 @@ module GrassGis
           if @config[:errors] == :console || @config[:echo] == :output
             STDERR.puts error_info
           end
-          log @config[:log], error_info
+          log "Error:", indented: error_info
         end
       end
     end
@@ -233,7 +295,7 @@ module GrassGis
     end
 
     def replace_var(var, value)
-      @original_env[var] = ENV[var]
+      @original_env[var] ||= ENV[var]
       ENV[var] = value
     end
 
@@ -312,14 +374,13 @@ module GrassGis
   def self.session(config, &blk)
     context = Context.new(config)
     context.allocate
+    context.log_header
+    create context, config[:create]
     context.session &blk
   ensure
     context.dispose if context
   end
 
-  class Error < StandardError
-  end
-
   def self.error?(command)
     command && (!!command.error || (command.status_value && command.status_value != 0))
   end
@@ -351,4 +412,32 @@ module GrassGis
     end
   end
 
+  # Return a comparable Version object from a version number string
+  def self.version(version)
+    Gem::Version.new version
+  end
+
+  class <<self
+    private
+    def create(context, options)
+      return unless options
+      gisdbase = context.configuration[:gisdbase]
+      unless File.directory?(gisdbase)
+        context.log "Create GISDBASE #{gisdbase}"
+        FileUtils.mkdir_p gisdbase
+      end
+      location = Location.new(context)
+      unless location.exists?
+        context.log "Create location #{location} at #{gisdbase}"
+        location.create! options
+      end
+      mapset = Mapset.new(context)
+      unless mapset.exists?
+        context.log "Create mapset #{mapset} at location #{location.path}"
+        mapset.create! options
+      end
+      # context.g.mapset mapset: mapset.to_s, location: location.to_s, dbase: gisdbase
+      context.change_mapset mapset.to_s
+    end
+  end
 end

data/lib/grassgis/error.rb

@@ -0,0 +1,4 @@
+module GrassGis
+  class Error < StandardError
+  end
+end

data/lib/grassgis/location.rb

@@ -0,0 +1,53 @@
+module GrassGis
+  class Location
+    def initialize(context)
+      @context = context
+      @configuration = @context.configuration
+      @gisdbase = @configuration[:gisdbase]
+      @location = @configuration[:location]
+      @path = File.join(@gisdbase, @location)
+    end
+
+    attr_reader :path
+
+    def to_s
+      @location
+    end
+
+    def exists?
+      File.directory?(@path)
+    end
+
+    def create!(options = {})
+      raise Error, "Location #{@location} already exists" if exists?
+      raise Error, "A file with the same name #{@location} exists" if File.exists?(@path)
+      raise Error, "GRASSDBASE doesn't exist" unless File.directory?(@gisdbase)
+      epsg = options[:epsg]
+      limits = options[:limits]
+      desc = options[:desc]
+      raise Error, "An EPSG code is needed to define a new loaction" unless epsg
+      @context.g.proj '-t', epsg: epsg, location: @location
+      permanent = permanent_path
+      if desc
+        desc_file = File.join(permanent, 'MYNAME')
+        File.write desc_file, desc
+      end
+      if limits
+        w, s, e, n = limits
+        res = options[:res]
+        # @context.g.mapset mapset: 'PERMANENT', location: @location
+        @context.change_mapset 'PERMANENT'
+        @context.g.region w: w, s: s, e: e, n: n, res: res
+        FileUtils.cp File.join(permanent, 'WIND'), File.join(permanent, 'DEFAULT_WIND')
+      end
+    end
+
+    def mapset_path(mapset)
+      File.join(@path, mapset)
+    end
+
+    def permanent_path
+      mapset_path('PERMANENT')
+    end
+  end
+end

data/lib/grassgis/mapset.rb

@@ -0,0 +1,31 @@
+module GrassGis
+  class Mapset
+    def initialize(context)
+      @context = context
+      @configuration = @context.configuration
+      @location = Location.new(@context)
+      @mapset = @configuration[:mapset]
+      @path = File.join(@location.path, @mapset)
+    end
+
+    attr_reader :path
+
+    def to_s
+      @mapset
+    end
+
+    def exists?
+      File.directory?(@path)
+    end
+
+    def create!(options = {})
+      raise Error, "Mapset #{@mapset} already exists" if exists?
+      raise Error, "A file with the same name #{@mapset} exists" if File.exists?(@path)
+      raise Error, "Location doesn't exist" unless @location.exists?
+      # @context.g.mapet '-c', mapset: @mapset, location: @location.to_s, dbase: @configuration[:gisdbase]
+      FileUtils.mkdir_p @path
+      permanent = @location.permanent_path
+      FileUtils.cp File.join(permanent, 'DEFAULT_WIND'), File.join(@path, 'WIND')
+    end
+  end
+end

data/lib/grassgis/module.rb

@@ -34,6 +34,7 @@ module GrassGis
           case arg
           when Hash
             arg.each do |key, value|
+              next if value.nil?
               case value
               when Array
                 value = value*","

data/lib/grassgis/version.rb

@@ -1,3 +1,3 @@
 module GrassGis
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

data/lib/grassgis.rb

@@ -1,5 +1,8 @@
 require 'sys_cmd'
 require 'grassgis/version'
+require 'grassgis/error'
 require 'grassgis/support'
 require 'grassgis/module'
+require 'grassgis/location'
+require 'grassgis/mapset'
 require 'grassgis/context'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grassgis
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Javier Goizueta
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-25 00:00:00.000000000 Z
+date: 2015-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sys_cmd
@@ -82,6 +82,9 @@ files:
 - grassgis.gemspec
 - lib/grassgis.rb
 - lib/grassgis/context.rb
+- lib/grassgis/error.rb
+- lib/grassgis/location.rb
+- lib/grassgis/mapset.rb
 - lib/grassgis/module.rb
 - lib/grassgis/support.rb
 - lib/grassgis/version.rb