excel_to_code 0.3.17 → 0.3.18.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a6c7853f4e0ce66da8f073d561bbd0dabd2a390d
-  data.tar.gz: b9e44bda2488d15ede19254374a9b19fb1320762
+SHA256:
+  metadata.gz: 295445022d29e71173d548f2fbfae87804c2fc19f6ba111c5efdec35657cf7a6
+  data.tar.gz: 025fd8e7080d061732be7f357ff242e2fb51fe64bb985c33c2703b8ae342cf01
 SHA512:
-  metadata.gz: aed1ca40db11c54a816035989e1f68427028dbd2ed3c7328e134efa225842b52c72e6db1df32090d75a45da8d95caa29102b52a028d413ff397ecd946d4dfed9
-  data.tar.gz: 87131c81c57f7d7705833b0f18f14e797fb553c304367f47c688c1c6593feaebd9589e278fbb92792add54442cdfa833508187ff090fd60169754f9332c0486a
+  metadata.gz: 6049e42f81bcecf1942c68141cc735406f0227c59c77d0008249bc8e7c3f7480f9090b554ceb62ab27a519861cc00a11c0ccd2673b89de91213fbd90336a12fd
+  data.tar.gz: aa5aba794f98a99481171bf0753f090495f556c8da38a9ff37be8a1c0994fe92b9df15a9bf1f5f787120a23061c17ca6436cf486b2844dbbd628b4cc7cfe4d80

data/README.md

@@ -1,50 +1,83 @@
-# excel_to_code
+# Excel to Code
 
-Converts some excel spreadsheets (.xlsx, not .xls) into some other programming languages (currently ruby or c).
-This allows the excel spreadsheets to be run programatically, without excel.
+[![Tests Passing](https://travis-ci.org/tamc/excel_to_code.svg?branch=master)](https://travis-ci.org/tamc/excel_to_code)
 
-Its cannonical source is at http://github.com/tamc/excel_to_code
+excel_to_c - roughly translate some Excel files into C.
 
-# Running excel_to_code
+excel_to_ruby - roughly translate some Excel files into Ruby.
 
-To just have a go:
+This allows spreadsheets to be:
 
-	./bin/excel_to_c <excel_file_name>
-	
-NB:For small spreadsheets this will take a minute or so. For large spreadsheets it is best to run it overnight.
-	
-for more detail:
-	
-	./bin/excel_to_c --compile --run-tests --settable <name of input worksheet> --prune-except <name of output worksheet> <excel file name> 
-	
-this should work:
+1. Embedded in other programs, such as web servers, or optimisers
+2. Without depending on any Microsoft code
+
+For example, running [these commands](examples/simple/compile.sh) turns [this spreadsheet](examples/simple/simple.xlsx) into [this Ruby code](examples/simple/ruby/simple.rb) or [this C code](examples/simple/c/simple.c).
 
-	./bin/excel_to_c --help
+# Install
 
-# Testing excel_to_code
+Requires Ruby. Install by:
 
-1. Make sure you have ruby 1.9.2 or later installed
-2. gem install bundler # May need to use sudo
-3. bundle
-4. rspec spec/*
+    gem install excel_to_code
 
-To test the C runtime:
-1. cd src/compile/c
-2. cc excel_to_c_runtime
-3. ./a.out
+# Run
 
-# Hacking excel_to_code
+To just have a go:
+
+	excel_to_c <excel_file_name>
+
+This will produce a file called excelspreadsheet.c
+
+For a more complex spreadsheet:
+	
+	excel_to_c --compile --run-tests --settable <name of input worksheet> --prune-except <name of output worksheet> <excel file name> 
+	
+See the full list of options:
 
-There are some how to guides in the doc folder. 
+	excel_to_c --help
 
-# Limitations
+# Gotchas, limitations and bugs
 
-1. Not tested at all on Windows
-2. INDIRECT and OFFSET formula must be convertable at runtime into a standard formula
-3. Doesn't implement all functions (see doc/Which_functions_are_implemented.md)
+0. No custom functions, no macros for generating results
+1. Results are cached. So you must call reset(), then set values, then read values.
+2. It must be possible to replace INDIRECT and OFFSET formula with standard references at compile time (e.g., INDIRECT("A"&"1") is fine, INDIRECT(userInput&"3") is not.
+3. Doesn't implement all functions. [See which functions are implemented](docs/Which_functions_are_implemented.md).
 4. Doesn't implement references that involve range unions and lists (but does implement standard ranges)
 5. Sometimes gives cells as being empty, when excel would give the cell as having a numeric value of zero
-6. The generated C version does not multithread and will give bad results if you try
-7. The generated code uses floating point, rather than fully precise arithmetic, so results can differ slightly
+6. The generated C version does not multithread and will give bad results if you try.
+7. The generated code uses floating point, rather than fully precise arithmetic, so results can differ slightly.
 8. The generated code uses the sprintf approach to rounding (even-odd) rather than excel's 0.5 rounds away from zero.
-90. Ranges like this: Sheet1!A10:Sheet1!B20 and 3D ranges don't work
+9. Ranges like this: Sheet1!A10:Sheet1!B20 and 3D ranges don't work.
+
+Report bugs: <https://github.com/tamc/excel_to_code/issues>
+
+# Changelog
+
+See [Changes](CHANGES.md).
+
+# License
+
+See [License](LICENSE.md)
+
+# Hacking
+
+Source code: <https://github.com/tamc/excel_to_code>
+
+Documentation:
+
+* [Installing from source](docs/installing_from_source.md)
+* [Structure of this project](docs/structure_of_this_project.md)
+* [How does the calculation work](docs/how_does_the_calculation_work.md)
+* [How to fix parsing errors](docs/How_to_fix_parsing_errors.md)
+* [How to implement a new Excel function](docs/How_to_add_a_missing_function.md)
+
+Some notes on how Excel works under the hood:
+
+* [The Excel file structure](docs/implementation/excel_file_structure.md)
+* [Relationships](docs/implementation/relationships.md)
+* [Workbooks](docs/implementation/workbook.md)
+* [Worksheets](docs/implementation/worksheets.md)
+* [Cells](docs/implementation/cell.md)
+* [Tables](docs/implementation/tables.md)
+* [Shared Strings](docs/implementation/shared_strings.md)
+* [Array formulae](docs/implementation/array_formulae.md)
+

data/bin/excel_to_c

@@ -5,98 +5,28 @@ require_relative '../src/excel_to_code'
 command = ExcelToC.new
 
 opts = OptionParser.new do |opts|
-  opts.banner = <<-END
-
-A command to approximately translate excel files into c code.
-
-Usage: excel_to_c [options] input_excel_file <output_directory>
-  input_excel_file    the name of a .xlsx excel file (i.e., produced by Excel 2007+, not a .xls file) 
-  output_directory    the name of a folder in which to place the generated code. If not specified will have the same name as the input_excel_file, without the .xlsx
-  
-Support: http://github.com/tamc/excel_to_code
-END
-  
-  opts.separator ""
-  opts.separator "Specific options:"
+  CommonCommandLineOptions.set(command: command, options: opts, generates: "C", extension: "c")
   
-  opts.on('-v','--version', 'Prints the version number of this code') do 
-    puts ExcelToCode.version
-    exit
-  end
-
-  opts.on('-o','--output-name NAME','Filename to give to c version of code (and associated ruby interface). Defaults to a folder with the same name as the excel file.') do |name|
-    command.output_name = name
-  end
-
-  opts.on('-c','--compile',"Compile the generated code (where relevant)") do
+  opts.on('-c','--compile',"Compile the C") do
     command.actually_compile_code = true
   end
   
-  opts.on('-r','--run-tests',"Compile the generated code and then run the tests") do
-    command.actually_run_tests = true
+  opts.on('--[no-]makefile', 'Generate a makefile. Default: no.') do |b|
+    command.create_makefile = b
   end
 
-  opts.on('-n','--named-references',"Transfer named references from spreadsheet to generated code") do
-    command.named_references_that_can_be_set_at_runtime = :where_possible
-    command.named_references_to_keep = :all
-  end
-
-  opts.on('-s','--settable WORKSHEET','Make it possible to set the values of cells in this worksheet at runtime. By default no values are settable.') do |sheet|
-    command.cells_that_can_be_set_at_runtime = { sheet => :all }
-  end
-
-  opts.on('-p','--prune-except WORKSHEET',"Remove all cells except those on this worksheet, or that are required to calculate values on that worksheet. By default keeps all cells.") do |sheet|
-    command.cells_to_keep = { sheet => :all }
-  end
   
-  opts.on('--isolate WORKSHEET', "Only performs translation and optimiation of that one worksheet. Useful for debugging an incorrect translation of a large worksheet") do |sheet|
-    command.isolate = sheet
-  end
-
-  opts.on('-d','--debug', "Does not perform final optimisations of spreadsheet, leaving the resulting code more similar to the original worksheet, but potentially slower") do |sheet|
-    command.should_inline_formulae_that_are_only_used_once = false
-    command.extract_repeated_parts_of_formulae = false
+  opts.on('--[no-]rakefile', 'Generate a rakefile. Default: yes.') do |b|
+    command.create_rakefile = b
   end
 
-  opts.on('--makefile', 'Generate a makefile') do
-    command.create_makefile = true
-  end
-
-  opts.on('--no-makefile', 'Do not generate a makefile (default)') do
-    command.create_makefile = false
-  end
-  
-  opts.on('--rakefile', 'Generate a rakefile (default)') do
-    command.create_rakefile = true
-  end
-
-  opts.on('--no-rakefile', 'Do not generate a rakefile') do
-    command.create_rakefile = false
-  end
-
-  opts.on('--write-tests-in-c', "Write tests in pure C (normally written in ruby") do
+  opts.on('--write-tests-in-c', "Write tests in C. Default: Ruby.") do
     command.write_tests_in_c = true
   end
-
-  opts.on("-h", "--help", "Show this message") do
-    puts opts
-    exit
-  end
 end
 
-begin
-  opts.parse!(ARGV)
-rescue OptionParser::ParseError => e 
-  STDERR.puts e.message, "\n", opts 
+unless CommonCommandLineOptions.parse(options: opts, command: command, arguments: ARGV)
   exit(-1)
 end
 
-unless ARGV.size > 0
-  puts opts
-  exit(-1)
-end
-
-command.excel_file = ARGV[0]
-command.output_directory = ARGV[1] if ARGV[1]
-
 command.go!

data/bin/excel_to_go

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+require 'optparse'
+require_relative '../src/excel_to_code'
+
+$stderr.puts
+$stderr.puts "WARNING: excel_to_go is unfinished"
+$stderr.puts
+
+command = ExcelToGo.new
+
+opts = OptionParser.new do |opts|
+  CommonCommandLineOptions.set(command: command, options: opts, generates: "Go", extension: "go")
+
+  opts.banner += <<~END
+  
+  \nA note on GOPATH: The generated go file has a dependency, excel.go, which has no further
+  dependencies outside of the core Go packages. This dependency is copied into the same destination 
+  as the generated go file. The tricky bit is how the generated go file can import excel.go
+  given that Go does not like relative references in import statements.
+
+  You can either:
+
+  1. Manually specify the import statement to use with the --import-excel-go [PATH] switch
+  2. Let excel_to_go guess the right path. It will do this by:
+     a. If [output_directory] is under GOPATH, calculating the path relative to GOPATH.
+     b. If [output_directory] has src/ somewhere in its path, calculating the path relative to that
+     c. Falling back to 'excel.go' which you will then have to manually fix.
+
+  END
+
+  opts.on('--import-excel-go [PATH]', 'Manually set the path to be used to import excel.go') do |p|
+    command.excel_go_lib = p
+  end
+
+end
+
+unless CommonCommandLineOptions.parse(options: opts, command: command, arguments: ARGV)
+  exit(-1)
+end
+
+command.go!

data/bin/excel_to_ruby

@@ -5,78 +5,11 @@ require_relative '../src/excel_to_code'
 command = ExcelToRuby.new
 
 opts = OptionParser.new do |opts|
-  opts.banner = <<-END
-
-A command to approximately translate excel files into c code.
-
-Usage: excel_to_ruby [options] input_excel_file <output_directory>
-  input_excel_file    the name of a .xlsx excel file (i.e., produced by Excel 2007+, not a .xls file) 
-  output_directory    the name of a folder in which to place the generated code. If not specified will have the same name as the input_excel_file, without the .xlsx
-  
-Support: http://github.com/tamc/excel_to_code
-END
-  
-  opts.separator ""
-  opts.separator "Specific options:"
-  
-  opts.on('-v','--version', 'Prints the version number of this code') do 
-    puts ExcelToCode.version
-    exit
-  end
-
-  opts.on('-o','--output-name NAME','Filename to give to c version of code (and associated ruby interface). Defaults to a folder with the same name as the excel file.') do |name|
-    command.output_name = name
-  end
-
-  opts.on('-c','--compile',"Compile the generated code (where relevant)") do
-    command.actually_compile_code = true
-  end
-  
-  opts.on('-r','--run-tests',"Compile the generated code and then run the tests") do
-    command.actually_run_tests = true
-  end
-
-  opts.on('-n','--named-references',"Transfer named references from spreadsheet to generated code") do
-    command.named_references_that_can_be_set_at_runtime = :where_possible
-    command.named_references_to_keep = :all
-  end
-
-  opts.on('-s','--settable WORKSHEET','Make it possible to set the values of cells in this worksheet at runtime. By default no values are settable.') do |sheet|
-    command.cells_that_can_be_set_at_runtime = { sheet => :all }
-  end
-
-  opts.on('-p','--prune-except WORKSHEET',"Remove all cells except those on this worksheet, or that are required to calculate values on that worksheet. By default keeps all cells.") do |sheet|
-    command.cells_to_keep = { sheet => :all }
-  end
-  
-  opts.on('--isolate WORKSHEET', "Only performs translation and optimiation of that one worksheet. Useful for debugging an incorrect translation of a large worksheet") do |sheet|
-    command.isolate = sheet
-  end
-
-  opts.on('-d','--debug', "Does not perform final optimisations of spreadsheet, leaving the resulting code more similar to the original worksheet, but potentially slower") do |sheet|
-    command.should_inline_formulae_that_are_only_used_once = false
-    command.extract_repeated_parts_of_formulae = false
-  end
-  
-  opts.on("-h", "--help", "Show this message") do
-    puts opts
-    exit
-  end
-end
-
-begin
-  opts.parse!(ARGV)
-rescue OptionParser::ParseError => e 
-  STDERR.puts e.message, "\n", opts 
-  exit(-1)
+  CommonCommandLineOptions.set(command: command, options: opts, generates: "Ruby", extension: "rb")
 end
 
-unless ARGV.size > 0
-  puts opts
+unless CommonCommandLineOptions.parse(options: opts, command: command, arguments: ARGV)
   exit(-1)
 end
 
-command.excel_file = ARGV[0]
-command.output_directory = ARGV[1] if ARGV[1]
-
 command.go!

data/src/commands.rb

@@ -1,4 +1,6 @@
 require_relative "commands/excel_to_x"
 require_relative "commands/excel_to_ruby"
 require_relative "commands/excel_to_c"
+require_relative "commands/excel_to_go"
 require_relative "commands/excel_to_test"
+require_relative "commands/common_command_line_options"

data/src/commands/common_command_line_options.rb

@@ -0,0 +1,81 @@
+class CommonCommandLineOptions
+  def self.set(command:, options:, generates:, extension:)
+    banner = <<-EOT
+      #{$0} [options] <excel_file> [output_directory]
+
+      Roughly translate some Excel files into plain #{generates}
+
+      http://github.com/tamc/excel_to_code
+    EOT
+
+    options.separator "Options:"
+
+    options.banner = banner.split("\n").map(&:strip).join("\n")
+
+    options.on_tail('-v', '--version', '') do
+      puts ExcelToCode.version
+      exit
+    end
+
+    options.on('-o', '--output-name NAME', "Name the generated code files. Default excelspreadsheet.#{extension}") do |name|
+      command.output_name = name
+    end
+
+    options.on('-r', '--run-tests', "Test whether the #{generates} matches the Excel.") do
+      command.actually_run_tests = true
+    end
+
+    options.on('-n', '--named-references', "Include Excel named references as variables in the #{generates}.") do
+      command.named_references_that_can_be_set_at_runtime = :where_possible
+      command.named_references_to_keep = :all
+    end
+
+    options.on('-s', '--settable INPUT_WORKSHEET', "Translate value cells in INPUT_WORKSHEET as settable variables in the #{generates}.") do |sheet|
+       
+      command.cells_that_can_be_set_at_runtime = { sheet => :all }
+    end
+
+    options.on('-p', '--prune-except OUTPUT_WORKSHEET', 'Only translate OUTPUT_WORKSHEET and the cells its results depend on.') do |sheet|
+      command.cells_to_keep = { sheet => :all }
+    end
+
+    options.on('--isolate FAULTY_WORKSHEET', 'Only translate FAULTY_WORKSHEET. Useful for debugging.') do |sheet|
+      command.isolate = sheet
+    end
+
+    options.on('-d', '--debug', "Fewer optimisations; the #{generates} should be more similar to the original Excel.") do
+      command.should_inline_formulae_that_are_only_used_once = false
+      command.extract_repeated_parts_of_formulae = false
+    end
+
+    options.on('--persevere', "Continue through some errors in order to fully appreciate the scale of problems in the Excel.") do
+      command.persevere = true
+    end
+
+    options.on_tail('-h', '--help', '') do
+      puts options
+      exit
+    end
+    
+    options.set_summary_width 35
+
+  end
+  
+  def self.parse(options:, command:, arguments:)
+    begin
+      options.parse!(arguments)
+    rescue OptionParser::ParseError => e 
+      STDERR.puts e.message, "\n", options 
+      return false
+    end
+
+    unless arguments.size > 0
+      puts options
+      return false
+    end
+
+    command.excel_file = arguments[0]
+    command.output_directory = arguments[1] if arguments[1]
+    return true
+  end
+end