annotate 2.6.3 → 3.2.0

data/lib/tasks/annotate_models.rake

@@ -1,47 +1,70 @@
 annotate_lib = File.expand_path(File.dirname(File.dirname(__FILE__)))
 
-if(!ENV['is_cli'])
+unless ENV['is_cli']
   task :set_annotation_options
-  task :annotate_models => :set_annotation_options
+  task annotate_models: :set_annotation_options
 end
 
-desc "Add schema information (as comments) to model and fixture files"
-task :annotate_models => :environment do
+desc 'Add schema information (as comments) to model and fixture files'
+task annotate_models: :environment do
   require "#{annotate_lib}/annotate/annotate_models"
   require "#{annotate_lib}/annotate/active_record_patch"
 
-  options={ :is_rake => true }
-  ENV['position'] = options[:position] = Annotate.fallback(ENV['position'], 'before')
-  options[:position_in_class] = Annotate.fallback(ENV['position_in_class'], ENV['position'])
-  options[:position_in_fixture] = Annotate.fallback(ENV['position_in_fixture'], ENV['position'])
-  options[:position_in_factory] = Annotate.fallback(ENV['position_in_factory'], ENV['position'])
-  options[:position_in_test] = Annotate.fallback(ENV['position_in_test'], ENV['position'])
-  options[:show_indexes] = Annotate.true?(ENV['show_indexes'])
-  options[:simple_indexes] = Annotate.true?(ENV['simple_indexes'])
-  options[:model_dir] = ENV['model_dir']
-  options[:include_version] = Annotate.true?(ENV['include_version'])
+  options = {is_rake: true}
+  ENV['position'] = options[:position] = Annotate::Helpers.fallback(ENV['position'], 'before')
+  options[:additional_file_patterns] = ENV['additional_file_patterns'] ? ENV['additional_file_patterns'].split(',') : []
+  options[:position_in_class] = Annotate::Helpers.fallback(ENV['position_in_class'], ENV['position'])
+  options[:position_in_fixture] = Annotate::Helpers.fallback(ENV['position_in_fixture'], ENV['position'])
+  options[:position_in_factory] = Annotate::Helpers.fallback(ENV['position_in_factory'], ENV['position'])
+  options[:position_in_test] = Annotate::Helpers.fallback(ENV['position_in_test'], ENV['position'])
+  options[:position_in_serializer] = Annotate::Helpers.fallback(ENV['position_in_serializer'], ENV['position'])
+  options[:show_foreign_keys] = Annotate::Helpers.true?(ENV['show_foreign_keys'])
+  options[:show_complete_foreign_keys] = Annotate::Helpers.true?(ENV['show_complete_foreign_keys'])
+  options[:show_indexes] = Annotate::Helpers.true?(ENV['show_indexes'])
+  options[:simple_indexes] = Annotate::Helpers.true?(ENV['simple_indexes'])
+  options[:model_dir] = ENV['model_dir'] ? ENV['model_dir'].split(',') : ['app/models']
+  options[:root_dir] = ENV['root_dir']
+  options[:include_version] = Annotate::Helpers.true?(ENV['include_version'])
   options[:require] = ENV['require'] ? ENV['require'].split(',') : []
-  options[:exclude_tests] = Annotate.true?(ENV['exclude_tests'])
-  options[:exclude_factories] = Annotate.true?(ENV['exclude_factories'])
-  options[:exclude_fixtures] = Annotate.true?(ENV['exclude_fixtures'])
-  options[:ignore_model_sub_dir] = Annotate.true?(ENV['ignore_model_sub_dir'])
-  options[:format_bare] = Annotate.true?(ENV['format_bare'])
-  options[:format_rdoc] = Annotate.true?(ENV['format_rdoc'])
-  options[:format_markdown] = Annotate.true?(ENV['format_markdown'])
-  options[:sort] = Annotate.true?(ENV['sort'])
-  options[:force] = Annotate.true?(ENV['force'])
-  options[:trace] = Annotate.true?(ENV['trace'])
+  options[:exclude_tests] = Annotate::Helpers.true?(ENV['exclude_tests'])
+  options[:exclude_factories] = Annotate::Helpers.true?(ENV['exclude_factories'])
+  options[:exclude_fixtures] = Annotate::Helpers.true?(ENV['exclude_fixtures'])
+  options[:exclude_serializers] = Annotate::Helpers.true?(ENV['exclude_serializers'])
+  options[:exclude_scaffolds] = Annotate::Helpers.true?(ENV['exclude_scaffolds'])
+  options[:exclude_controllers] = Annotate::Helpers.true?(ENV.fetch('exclude_controllers', 'true'))
+  options[:exclude_helpers] = Annotate::Helpers.true?(ENV.fetch('exclude_helpers', 'true'))
+  options[:exclude_sti_subclasses] = Annotate::Helpers.true?(ENV['exclude_sti_subclasses'])
+  options[:ignore_model_sub_dir] = Annotate::Helpers.true?(ENV['ignore_model_sub_dir'])
+  options[:format_bare] = Annotate::Helpers.true?(ENV['format_bare'])
+  options[:format_rdoc] = Annotate::Helpers.true?(ENV['format_rdoc'])
+  options[:format_yard] = Annotate::Helpers.true?(ENV['format_yard'])
+  options[:format_markdown] = Annotate::Helpers.true?(ENV['format_markdown'])
+  options[:sort] = Annotate::Helpers.true?(ENV['sort'])
+  options[:force] = Annotate::Helpers.true?(ENV['force'])
+  options[:frozen] = Annotate::Helpers.true?(ENV['frozen'])
+  options[:classified_sort] = Annotate::Helpers.true?(ENV['classified_sort'])
+  options[:trace] = Annotate::Helpers.true?(ENV['trace'])
+  options[:wrapper_open] = Annotate::Helpers.fallback(ENV['wrapper_open'], ENV['wrapper'])
+  options[:wrapper_close] = Annotate::Helpers.fallback(ENV['wrapper_close'], ENV['wrapper'])
+  options[:ignore_columns] = ENV.fetch('ignore_columns', nil)
+  options[:ignore_routes] = ENV.fetch('ignore_routes', nil)
+  options[:hide_limit_column_types] = Annotate::Helpers.fallback(ENV['hide_limit_column_types'], '')
+  options[:hide_default_column_types] = Annotate::Helpers.fallback(ENV['hide_default_column_types'], '')
+  options[:with_comment] = Annotate::Helpers.true?(ENV['with_comment'])
+  options[:ignore_unknown_models] = Annotate::Helpers.true?(ENV.fetch('ignore_unknown_models', 'false'))
+
   AnnotateModels.do_annotations(options)
 end
 
-desc "Remove schema information from model and fixture files"
-task :remove_annotation => :environment do
+desc 'Remove schema information from model and fixture files'
+task remove_annotation: :environment do
   require "#{annotate_lib}/annotate/annotate_models"
   require "#{annotate_lib}/annotate/active_record_patch"
 
-  options={ :is_rake => true }
+  options = {is_rake: true}
   options[:model_dir] = ENV['model_dir']
+  options[:root_dir] = ENV['root_dir']
   options[:require] = ENV['require'] ? ENV['require'].split(',') : []
-  options[:trace] = Annotate.true?(ENV['trace'])
+  options[:trace] = Annotate::Helpers.true?(ENV['trace'])
   AnnotateModels.remove_annotations(options)
 end

data/lib/tasks/annotate_models_migrate.rake

@@ -0,0 +1,63 @@
+# These tasks are added to the project if you install annotate as a Rails plugin.
+# (They are not used to build annotate itself.)
+
+# Append annotations to Rake tasks for ActiveRecord, so annotate automatically gets
+# run after doing db:migrate.
+
+migration_tasks = %w(db:migrate db:migrate:up db:migrate:down db:migrate:reset db:migrate:redo db:rollback)
+if defined?(Rails::Application) && Rails.version.split('.').first.to_i >= 6
+  require 'active_record'
+
+  databases = ActiveRecord::Tasks::DatabaseTasks.setup_initial_database_yaml
+
+  ActiveRecord::Tasks::DatabaseTasks.for_each(databases) do |spec_name|
+    migration_tasks.concat(%w(db:migrate db:migrate:up db:migrate:down).map { |task| "#{task}:#{spec_name}" })
+  end
+end
+
+migration_tasks.each do |task|
+  next unless Rake::Task.task_defined?(task)
+
+  Rake::Task[task].enhance do
+    Rake::Task[Rake.application.top_level_tasks.last].enhance do
+      annotation_options_task = if Rake::Task.task_defined?('app:set_annotation_options')
+                                  'app:set_annotation_options'
+                                else
+                                  'set_annotation_options'
+                                end
+      Rake::Task[annotation_options_task].invoke
+      Annotate::Migration.update_annotations
+    end
+  end
+end
+
+module Annotate
+  class Migration
+    @@working = false
+
+    def self.update_annotations
+      unless @@working || Annotate::Helpers.skip_on_migration?
+        @@working = true
+
+        self.update_models if Annotate::Helpers.include_models?
+        self.update_routes if Annotate::Helpers.include_routes?
+      end
+    end
+
+    def self.update_models
+      if Rake::Task.task_defined?("annotate_models")
+        Rake::Task["annotate_models"].invoke
+      elsif Rake::Task.task_defined?("app:annotate_models")
+        Rake::Task["app:annotate_models"].invoke
+      end
+    end
+
+    def self.update_routes
+      if Rake::Task.task_defined?("annotate_routes")
+        Rake::Task["annotate_routes"].invoke
+      elsif Rake::Task.task_defined?("app:annotate_routes")
+        Rake::Task["app:annotate_routes"].invoke
+      end
+    end
+  end
+end

data/lib/tasks/annotate_routes.rake

@@ -1,12 +1,21 @@
+annotate_lib = File.expand_path(File.dirname(File.dirname(__FILE__)))
+
+unless ENV['is_cli']
+  task :set_annotation_options
+  task annotate_routes: :set_annotation_options
+end
+
 desc "Adds the route map to routes.rb"
 task :annotate_routes => :environment do
-  annotate_lib = File.expand_path(File.dirname(File.dirname(__FILE__)))
   require "#{annotate_lib}/annotate/annotate_routes"
 
   options={}
-  ENV['position'] = options[:position] = Annotate.fallback(ENV['position'], 'before')
-  options[:position_in_routes] = Annotate.fallback(ENV['position_in_routes'], ENV['position'])
+  ENV['position'] = options[:position] = Annotate::Helpers.fallback(ENV['position'], 'before')
+  options[:position_in_routes] = Annotate::Helpers.fallback(ENV['position_in_routes'], ENV['position'])
+  options[:ignore_routes] = Annotate::Helpers.fallback(ENV['ignore_routes'],  nil)
   options[:require] = ENV['require'] ? ENV['require'].split(',') : []
+  options[:wrapper_open] = Annotate::Helpers.fallback(ENV['wrapper_open'], ENV['wrapper'])
+  options[:wrapper_close] = Annotate::Helpers.fallback(ENV['wrapper_close'], ENV['wrapper'])
   AnnotateRoutes.do_annotations(options)
 end
 

data/potato.md

@@ -0,0 +1,41 @@
+Colons can be used to align columns.
+
+| Tables        | Are           | Cool  |
+| ------------- |:-------------:| -----:|
+| col 3 is      | right-aligned | $1600 |
+| col 2 is      | centered      |   $12 |
+| zebra stripes | are neat      |    $1 |
+
+There must be at least 3 dashes separating each header cell.
+The outer pipes (|) are optional, and you don't need to make the
+raw Markdown line up prettily. You can also use inline Markdown.
+
+Markdown | Less | Pretty
+--- | --- | ---
+*Still* | `renders` | **nicely**
+1 | 2 | 3
+
+
+ ## Route Map
+
+  Prefix    | Verb       | URI Pattern     | Controller#Action    
+  --------- | ---------- | --------------- | --------------------
+  myaction1 | GET        | /url1(.:format) | mycontroller1#action
+  myaction2 | POST       | /url2(.:format) | mycontroller2#action
+  myaction3 | DELETE-GET | /url3(.:format) | mycontroller3#action \n")
+
+
+
+ Table name: `users`
+
+ ### Columns
+
+ Name                    | Type               | Attributes
+ ----------------------- | ------------------ | ---------------------------
+ **`id`**                | `integer`          | `not null, primary key`
+ **`foreign_thing_id`**  | `integer`          | `not null`
+
+ ### Foreign Keys
+
+ * `fk_rails_...` (_ON DELETE => on_delete_value ON UPDATE => on_update_value_):
+     * **`foreign_thing_id => foreign_things.id`**

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: annotate
 version: !ruby/object:Gem::Version
-  version: 2.6.3
+  version: 3.2.0
 platform: ruby
 authors:
 - Alex Chaffee
@@ -12,41 +12,53 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-05 00:00:00.000000000 Z
+date: 2022-02-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.8.7
+        version: '10.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '10.4'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 0.8.7
+        version: '14.0'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: '3.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
 description: Annotates Rails/ActiveRecord Models, routes, fixtures, and others based
   on the database schema.
 email:
 - alex@stinky.com
-- cuong@gmail.com
+- cuong.tran@gmail.com
 - x@nofxx.com
 - turadg@aleahmad.net
 - jon@cloudability.com
@@ -54,54 +66,59 @@ executables:
 - annotate
 extensions: []
 extra_rdoc_files:
-- README.rdoc
-- CHANGELOG.rdoc
-- TODO.rdoc
+- README.md
+- CHANGELOG.md
 files:
-- .travis.yml
-- AUTHORS.rdoc
-- CHANGELOG.rdoc
+- AUTHORS.md
+- CHANGELOG.md
 - LICENSE.txt
-- README.rdoc
-- TODO.rdoc
+- README.md
+- RELEASE.md
 - annotate.gemspec
 - bin/annotate
 - lib/annotate.rb
 - lib/annotate/active_record_patch.rb
 - lib/annotate/annotate_models.rb
+- lib/annotate/annotate_models/file_patterns.rb
 - lib/annotate/annotate_routes.rb
+- lib/annotate/annotate_routes/header_generator.rb
+- lib/annotate/annotate_routes/helpers.rb
+- lib/annotate/constants.rb
+- lib/annotate/helpers.rb
+- lib/annotate/parser.rb
 - lib/annotate/tasks.rb
 - lib/annotate/version.rb
 - lib/generators/annotate/USAGE
 - lib/generators/annotate/install_generator.rb
 - lib/generators/annotate/templates/auto_annotate_models.rake
 - lib/tasks/annotate_models.rake
+- lib/tasks/annotate_models_migrate.rake
 - lib/tasks/annotate_routes.rake
-- lib/tasks/migrate.rake
-homepage: http://github.com/ctran/annotate_models
+- potato.md
+homepage: https://github.com/ctran/annotate_models
 licenses:
 - Ruby
-metadata: {}
+metadata:
+  bug_tracker_uri: https://github.com/ctran/annotate_models/issues/
+  source_code_uri: https://github.com/ctran/annotate_models.git
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: annotate
-rubygems_version: 2.2.2
+rubygems_version: 3.3.7
 signing_key: 
 specification_version: 4
 summary: Annotates Rails Models, routes, fixtures, and others based on the database
   schema.
 test_files: []
-has_rdoc: 

data/.travis.yml

@@ -1,6 +0,0 @@
-language: ruby
-rvm:
-  - 1.9.3
-
-before_install:
-  - rvm @global do gem install bundler

data/CHANGELOG.rdoc

@@ -1,175 +0,0 @@
-== 2.6.2
-* Retain the current annotate block unless --force is specified
-* Always load models, since they may not be autoloaded by Rails
-* The pg array type is now detected (see #158)
-
-== 2.6.0.beta2
-
-* support for composite_primary_keys (garysweaver)
-* bug fix for annotate_one_file (vlado)
-
-== 2.6.0.beta1
-
-* It's now possible to use Annotate in standalone ActiveRecord (non-Rails)
-  projects again.
-* Adding note that Markdown is actually MultiMarkdown, and recommending the use
-  of the `kramdown` engine for parsing it.
-* Improved Markdown formatting considerably.
-* Bugfix: Needed to use inline-code tag for column and table names, otherwise
-  underscores would cause havok with the formatting.
-* Bugfix: Markdown syntax was incorrect (can't have trailing spaces before the
-  closing marker for an emphasis tag).
-* Bugfix: Remove-annotations wasn't properly finding test/spec files, and
-  wasn't even looking for FactoryGirl factories under the new naming
-  convention.
-* Bugfix: Load the Rakefile from the current directory, not the first Rakefile
-  in our load path.
-* Added support for new FactoryGirl naming convention.
-* Fix behavior of route annotations in newer versions of Rake that don't spit
-  out the CWD as their first line of output.
-* Overhauled integration testing system to be much easier to work with, better
-  compartmentalized, and so forth -- at the cost that you must be using RVM to
-  utilize it.  (It'll spit out appropriate pending messages if you don't.)
-  Also includes a mode for "tinkering" by hand with a scenario, and won't let
-  you run it through rspect if the repo is in a dirty state.  Added appropriate
-  rake tasks to help with all of this.
-* Routes can now be appended, pre-pended, or removed -- and do sane things in
-  all cases.
-* Expose all `position_*` variables as CLI params.
-* Make `ENV ['position']` work as a default for all the `ENV ['position_*']`
-  variables.
-* Make rake tasks more resilient to unusual circumstances / code loading
-  behavior.
-* Resolve annotate vs. annotate_models ambiguity once and for all by settling
-  on `annotate_models` _and_ `annotate_routes`.  This avoids a name collision
-  with RMagick while not needlessly overloading the term.
-* Fixed that schema kept prepending additional newlines
-* Updates to make annotate smarter about when to touch a model
-* Recognize column+type, and don't change a file unless the column+type
-  combination of the new schema are different than that of the old (i.e., don't
-  regenerate if columns happen to be in a different order. That's just how life
-  is sometimes)
-* Change annotate to use options hash instead of ENV.
-
-== 2.5.0
-
-* Works better with Rails 3
-* Bugfix: schema kept prepending additional newlines
-* Updates to make annotate smarter about when to touch a model
-* Recognize column+type, and don't change a file unless the column+type combination of the new schema are different than that of the old (i.e., don't regenerate if columns happen to be in a different order. That's just how life is sometimes.)
-* Grab old specification even if it has \r\n as line endings rather than pure \ns
-* Various warning and specification fixes
-* Fix "no such file to load -- annotate/annotate_models (MissingSourceFile)"
-  error (require statements in tasks now use full path to lib files)
-* warn about macros, to mitigate when we're included during a production run,
-  not just a rakefile run -- possibly at the expense of too much noise
-* Adding rake as a runtime dependency
-* If the schema is already in the model file, it will be replaced into the same
-  location.  If it didn't previously exist, it'll be placed according to the
-  "position", as before.
-* Allow task loading from Rakefile for gems (plugin installation already
-  auto-detects).
-* Add skip_on_db_migrate option as well for people that don't want it
-* Fix options parsing to convert strings to proper booleans
-* Add support for Fabrication fabricators
-* Leave magic encoding comment intact
-* Fix issue #14 - RuntimeError: Already memoized
-* Count a model as 'annotated' if any of its tests/fixtures are annotated
-* Support FactoryGirl
-* Support :change migrations (Rails 3.1)
-* Allow models with non-standard capitalization
-* Widen type column so we can handle longtexts with chopping things off.
-* Skip trying to get list of models from commandline when running via Rake (was
-  preventing the use of multiple rake tasks in one command if one of them was
-  db:migrate).
-* Add ability to skip annotations for a model by adding
-  '# -*- SkipSchemaAnnotations' anywhere in the file.
-* Don't show column limits for integer and boolean types.
-* Add sorting for columns and indexes. (Helpful for out-of-order migration
-  execution.  Use --sort if you want this.)
-* Annotate unit tests in subfolders.
-* Add generator to install rakefile that automatically annotates on db:migrate.
-* Correct Gemfile to clarify which environments need which gems.
-* Add an .rvmrc to facilitate clean development.
-* Refactor out ActiveRecord monkey-patch to permit extending without
-  side-effects.
-* Use ObjectSpace to locate models to facilitate handling of models with
-  non-standard capitalization.
-  Note that this still requires that the inflector be configured to understand
-  the special case.
-* Shore up test cases a bit.
-* Merge against many of the older branches on Github whose functionality is
-  already reflected to reduce confusion about what is and is not implemented
-  here.
-* Accept String or Symbol for :position (et al) options.
-* Add RDoc output formatting as an option.
-* Add Markdown output formatting as an option.
-* Add option to force annotation regeneration.
-* Add new configuration option for controlling where info is placed in
-  fixtures/factories.
-* Fix for models without tables.
-* Fix gemspec generation now that Jeweler looks at Gemfile.
-* Fix warning: `NOTE: Gem::Specification#default_executable= is deprecated with
-  no replacement. It will be removed on or after 2011-10-01.`
-* Fix handling of files with no trailing newline when putting annotations at
-  the end of the file.
-* Now works on tables with no primary key.
-* --format=markdown option
-* --trace option to help debug "Unable to annotate" errors
-* "Table name" annotation (if table name is different from model name)
-* "Human name" annotation (enabling translation to non-English locales)
-* Fix JRuby ObjectSpace compatibility bug (https://github.com/ctran/annotate_models/pull/85)
-* Fix FactoryGirl compatibility bug (https://github.com/ctran/annotate_models/pull/82)
-
-== 2.4.2 2009-11-21
-
-* Annotates (spec|test)/factories/<model>_factory.rb files
-
-== 2.4.1 2009-11-20
-
-* Annotates thoughtbot's factory_girl factories (test/factories/<model>_factory.rb)
-* Move default annotation position back to top
-
-== 2.4.0 2009-12-13
-
-* Incorporated lots of patches from the Github community, including support for
-  Blueprints fixtures
-* Several bug fixes
-
-== 2.1 2009-10-18
-
-* New options
-  * -R to require additional files before loading the models
-  * -i to show database indexes in annotations
-  * -e to exclude annotating tests or fixtures
-  * -m to include the migration version number in the annotation
-  * --model-dir to annotate model files stored a different place than app/models
-* Ignore unknown macros ('acts_as_whatever')
-
-== 2.0 2009-02-03
-
-* Add annotate_models plugin fork additions
-  * Annotates Rspec and Test Unit models
-  * Annotates Object Daddy exemplars
-  * Annotates geometrical columns
-* Add AnnotateRoutes rake task
-* Up gem structure to newgem defaults
-
-== 1.0.4 2008-09-04
-
-* Only update modified models since last run, thanks to sant0sk1
-
-== 1.0.3 2008-05-02
-
-* Add misc changes from Dustin Sallings and Henrik N
-  * Remove trailing whitespace
-  * More intuitive info messages
-  * Update README file with update-to-date example
-
-== 1.0.2 2008-03-22
-
-* Add contributions from Michael Bumann (http://github.com/bumi)
-  * added an option "position" to choose to put the annotation,
-  * spec/fixtures now also get annotated
-  * added a task to remove the annotations
-  * these options can be specified from command line as -d and -p [before|after]