module GrassGis

Constants

VERSION

Public Class Methods

error(command, error_mode = :raise) click to toggle source
# File lib/grassgis/context.rb, line 406
def self.error(command, error_mode = :raise)
  if command
    if command.error # :silent mode for testing/debugging?
      # Errors that prevent command execution
      # (usually ENOENT because the command does not exist)
      # are always raised
      raise command.error unless error_mode == :silent
    elsif error_mode == :raise
      if (command.status_value && command.status_value != 0)
        raise Error.new, error_info(command)
      end
    end
  end
end
error?(command) click to toggle source
# File lib/grassgis/context.rb, line 390
def self.error?(command)
  command && (!!command.error || (command.status_value && command.status_value != 0))
end
error_info(command) click to toggle source
# File lib/grassgis/context.rb, line 394
def self.error_info(command)
  if command
    if command.error
      info = "Error (#{command.error.class}):\n"
      info << command.error.to_s
    elsif (command.status_value && command.status_value != 0)
      info = "Exit code #{command.status_value}\n"
      info << command.error_output if command.error_output
    end
  end
end
session(config, &blk) click to toggle source

Evaluate a block in a GRASS session environment The configuration must include at leaast:

  • :gibase The base GRASS instalation directory

  • :location The location to work with

Optional parameters:

  • :gisdbase The base GRASS data directory

  • :mapset The default mapset

  • :version The GRASS version

Example:

configuration = {
  gisbase: '/usr/local/Cellar/grass-70/7.0.0/grass-7.0.0',
  location: 'world'
}

GrassGis.session configuration do
  r.resamp.stats '-n', input: "map1@mapset1", output: "map2"
  cmd = g.list 'vect'
  puts cmd.output
end

Note that block is evaluated in a spacial context, so that the lexical scope's self and instance variables are not directly available inside it. Local variables in the scope can be used to access self-related information. Also, local values can be injected in the block with the :locals option:

this = self # make self available a local variable
locals = { context: self } # inject locals
GrassGis.session configuration.merge(locals:) do
     r.resamp.stats '-n', input: this.input, output: context.output
end

Other pararameters:

:errors to define the behaviour when a GRASS command fails:

  • :raise is the default and raises on errors

  • :console shows standar error output of commands

  • :quiet error output is retained but not shown; no exceptions are raise except when the command cannot be executed (e.g. when the command name is ill-formed)

If :errors is anything other than :raise, it is up to the user to check each command for errors. With the :console option the standar error output of commands is sent to the console and is not accessible through the command's error_output method.

:log is used to define a loggin file where executed commands and its output is written.

:history is used to define a loggin file where only executed commands are written.

:echo controls what is echoed to the standard output and can be one of the following options:

  • :commands show all executed commands (the default)

  • :output show the output of commands too

  • false don't echo anything

Testing/debugging options:

  • :dry prevents actual execution of any command

  • errors: :silent omits raising exceptions (as :quiet) even when a command cannot be executed (usually because of an invalid command name)

# File lib/grassgis/context.rb, line 380
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
version(version) click to toggle source

Return a comparable Version object from a version number string

# File lib/grassgis/context.rb, line 422
def self.version(version)
  Gem::Version.new version
end

Private Class Methods

create(context, options) click to toggle source
# File lib/grassgis/context.rb, line 428
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