# /=====================================================================\ #
# |  latexml.perlcritic                                                 | #
# | perlcritic profile for LaTeXML perl sources                         | #
# |=====================================================================| #
# | support tools for LaTeXML:                                          | #
# |  Public domain software, produced as part of work done by the       | #
# |  United States Government & not subject to copyright in the US.     | #
# |---------------------------------------------------------------------| #
# | Bruce Miller <bruce.miller@nist.gov>                        #_#     | #
# | http://dlmf.nist.gov/LaTeXML/                              (o o)    | #
# \=========================================================ooo==U==ooo=/ #

#======================================================================
# This profile contains the a rearrangement of Perl::Critic Modules
# that seem useful for LaTeXML style. We'll reinterpret perlcritic
# severity for the following purposes:
#    5 = critical : must fix
#    4 = required : must fix before committing (used in git pre-commit)
#    3 = desirable: try to fix, eventually.
#    2 = hints    : useful hints to improve code
#    1 = useless  : don't bother; dumping ground for unwanted policies
#
# In this profile, I've moved policies up or down in severity to
# match the above usage model, and according to my own coding style.
#
# See "perlcritic --profile-proto" for an annotated list of all policies.
#======================================================================
# Let's aim for passing level 3, by default
# use 4 for pre-commit, 2 for code review
severity=3
# Exclude Bangs (which are annoyingly picky)
exclude = Bangs
#exclude = Bangs CodeLayout::RequireUseUTF8 Documentation::RequirePODUseEncodingUTF8

[LaTeXML::RequireDoubleSigils]

#======================================================================
# Downgrade some 4 & 5 level Policies that I either don't agree with
# or have already used a bit too much (maybe will clear these gradually)

[BuiltinFunctions::ProhibitStringyEval]
severity=3
# was 5; Well, we need it! (alternatives?)

[InputOutput::RequireBriefOpen]
severity=2
# was 4; Sensible policy but triggers on ALL opens!!!

[Modules::ProhibitAutomaticExportation]
severity=2
# was 4; Well, if I explicitly exported them, I meant it...

[Modules::RequireBarewordIncludes]
severity=3
# was 5; Well, we need it! (alternatives?)

[Modules::RequireFilenameMatchesPackage]
add_themes = non_binding
# use theme='not non_binding' for bindings to disable!

[Modules::ProhibitMultiplePackages]
severity=2
# was 4; Seemingly good policy, but I use it extensively!

[Subroutines::ProhibitBuiltinHomonyms]
severity=2
# was 4; too late now (for now)

[Subroutines::RequireArgUnpacking]
severity=3
# was 4; good policy but needs a slow cleaning out.

[TestingAndDebugging::ProhibitNoStrict]
severity=2
# was 5; If we're doing it explicitly
# it's prbobably because of some other overzealous policy, right?

[TestingAndDebugging::ProhibitNoWarnings]
severity=2
# was 4; Well, if I only do it sometimes?

[ValuesAndExpressions::ProhibitConstantPragma]
severity=2
# was 4; too late now (for now)

#======================================================================
# Adjust some level 3 Policies up or down into required or hints,
# according to my dubious personal taste.

[BuiltinFunctions::ProhibitLvalueSubstr]
severity=4
# was 3; good policy

[BuiltinFunctions::ProhibitVoidMap]
severity=1
# was 3; can't use map for side-effects?!?!

[CodeLayout::ProhibitHardTabs]
severity=4
# was 3; portability mess

[CodeLayout::ProhibitHashBarewords]
severity=1
# was 3; oh c'mon!?!?

[ControlStructures::ProhibitCascadingIfElse]
severity=2
# was 3; a good hint, but too restrictive

[ControlStructures::ProhibitDeepNests]
severity=2
# was 3; a good hint, but too restricive

[ErrorHandling::RequireCarping]
severity=1
# was 3; We've got our own exotic error reporting; don't need Carp.

[Modules::ProhibitExcessMainComplexity]
add_themes = non_binding
# Seems not useful for binding files (use theme='not non_binding')
max_mccabe = 30
# was 20

[NamingConventions::ProhibitAmbiguousNames]
severity=1
# was 3; names are often not ambiguous in context

[Subroutines::ProhibitExcessComplexity]
max_mccabe = 30
# was 20

[Subroutines::ProhibitManyArgs]
severity=2
# was 3

[RegularExpressions::RequireExtendedFormatting]
severity=2
# was 3; requiring /x on ALL regexps!!!?

[RegularExpressions::ProhibitComplexRegexes]
severity=2
# was 3

[Variables::ProhibitPackageVars]
severity=2
# was 3; would be severity=4 if it was selective enough!!!

#======================================================================
# Try out Perl::Critic::StricterSubs

[Modules::RequireExplicitInclusion]
#severity=4
severity=1

# This sounds wonderful, but doesn't actually track the imports
# implicitly imported by a plain "use Module;"
[Subroutines::ProhibitCallsToUndeclaredSubs]
#severity=4
severity=1

[Subroutines::ProhibitCallsToUnexportedSubs]
#severity=4
severity=1

[Subroutines::ProhibitExportingUndeclaredSubs]
severity=4

[Subroutines::ProhibitQualifiedSubDeclarations]
severity=4

#======================================================================
# [Probably will want to]
# Adjust some level 2 Policies up or down into required or hints,
# according to my dubious personal taste.

# Look into this later, it might be useful to aim for level 2....

# #
# # Some of these might be worth re-examining ?

# [References::ProhibitDoubleSigils]
# severity=1
# # or even 0; was 2; I like double sigils.

# [Documentation::RequirePodSections]
# severity=1
# # was 2; possibly useful, but not yet...

# [Documentation::RequirePodLinksIncludeText]
# severity=1
# # was 2; possibly useful, but not yet...

#======================================================================
# DISABLE some policies that we may want to revisit in the future

# What's the point of using "## no critic" if you just get different complaints?
[-Miscellanea::ProhibitUnrestrictedNoCritic]

# Exclude (for now) the suggestion to "use utf8" (and also in POD)
# [probably would prefer that the sources remain pure ASCII]
[-CodeLayout::RequireUseUTF8]
[-Documentation::RequirePODUseEncodingUTF8]

# Does Perl even have a (decent) Exception system? (maybe it does now)
[-ErrorHandling::RequireUseOfExceptions]

# Why is -f so bad?
[-ValuesAndExpressions::ProhibitFiletest_f]
[-InputOutput::ProhibitInteractiveTest]

# I really don't need compatibility with Perl 5.6 or 5.8!!!
#[-Compatibility::ProhibitColonsInBarewordHashKeys]
[-Compatibility::ProhibitThreeArgumentOpen]

# I don't necessarily disagree with this policy,
# but it seems to be itself buggy; it complains about $_->[0], eg.
[-ValuesAndExpressions::ProhibitAccessOfPrivateData]
# Ditto, seems buggy
[-ValuesAndExpressions::ProhibitCommaSeparatedStatements]
#======================================================================



